From 29c8ee7aaa0ee19e05b1c1ebc40c45e7c2aafe16 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Fri, 6 Nov 2026 23:33:39 -0500
Subject: [PATCH 01/38] feat(read): read any UTF-8 file outside the dedicated
 types as text

vault_read_file now returns HTML pages, scripts and files with no
extension as text. A file outside the dedicated types is refused when a
NUL byte sits in its first 8,000 bytes (binary data or UTF-16 text) or
when its bytes are not UTF-8. The dedicated text formats keep their path
with no NUL check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../server-error-contracts.test.ts            |  23 +++
 .../__tests__/decode-text-buffer.test.ts      |  64 ++++++++
 src/utils/decode-text-buffer.ts               |  26 ++++
 .../__tests__/tool-definitions.test.ts        |  22 ++-
 .../__tests__/asset-operations.test.ts        | 137 +++++++++++++++---
 .../vault-operations/asset-operations.ts      |  62 ++++++--
 6 files changed, 298 insertions(+), 36 deletions(-)
 create mode 100644 src/utils/__tests__/decode-text-buffer.test.ts
 create mode 100644 src/utils/decode-text-buffer.ts

diff --git a/src/__tests__/integration/server-error-contracts.test.ts b/src/__tests__/integration/server-error-contracts.test.ts
index cbbb78bf5..59d63e498 100644
--- a/src/__tests__/integration/server-error-contracts.test.ts
+++ b/src/__tests__/integration/server-error-contracts.test.ts
@@ -2229,6 +2229,29 @@ describe("malformed canvas", () => {
   })
 })
 
+// ── Binary file ──────────────────────────────────────────────
+
+describe("binary file", () => {
+  it("vault_read_file on a file holding a NUL byte", async () => {
+    const filePath = "Archive.zip"
+    const fileFullPath = join(serverVaultPath, filePath)
+    // A ZIP local file header, whose version and flag fields hold NUL bytes
+    await writeFile(fileFullPath, Buffer.from([0x50, 0x4b, 0x03, 0x04, 0x14, 0x00, 0x00, 0x00]))
+    onTestFinished(() => rm(fileFullPath))
+
+    const result = await callTool({ client, name: "vault_read_file", args: { path: filePath } })
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: '[Error]: unsupported file type ".zip": "Archive.zip" exists (8 bytes) and holds a NUL byte in its first 8,000 bytes (binary data or UTF-16 text). Readable types: images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and UTF-8 text files',
+        },
+      ],
+      isError: true,
+    })
+  })
+})
+
 // ── Whitespace-only task text ────────────────────────────────
 
 describe("whitespace-only task text", () => {
diff --git a/src/utils/__tests__/decode-text-buffer.test.ts b/src/utils/__tests__/decode-text-buffer.test.ts
new file mode 100644
index 000000000..25291e8c9
--- /dev/null
+++ b/src/utils/__tests__/decode-text-buffer.test.ts
@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest"
+import { decodeTextBuffer } from "../decode-text-buffer.js"
+
+/** `length` bytes of ASCII "a" with a NUL byte at `nulIndex`. */
+const buildBufferWithNulAt = (params: { length: number; nulIndex: number }): Buffer => {
+  const buffer = Buffer.alloc(params.length, "a")
+  buffer[params.nulIndex] = 0
+  return buffer
+}
+
+describe("decodeTextBuffer", () => {
+  it("decodes UTF-8 text, multibyte characters included", () => {
+    expect(decodeTextBuffer(Buffer.from("café — ✓\n", "utf8"))).toEqual({
+      status: "text",
+      text: "café — ✓\n",
+    })
+  })
+
+  it("decodes an empty buffer as empty text", () => {
+    expect(decodeTextBuffer(Buffer.alloc(0))).toEqual({ status: "text", text: "" })
+  })
+
+  it("calls bytes binary when a NUL byte is the first byte", () => {
+    expect(decodeTextBuffer(buildBufferWithNulAt({ length: 10, nulIndex: 0 }))).toEqual({
+      status: "binary",
+    })
+  })
+
+  it("calls bytes binary when a NUL byte is the last byte of the first 8,000", () => {
+    expect(decodeTextBuffer(buildBufferWithNulAt({ length: 9_000, nulIndex: 7_999 }))).toEqual({
+      status: "binary",
+    })
+  })
+
+  it("decodes bytes whose first NUL byte sits just past the first 8,000", () => {
+    const buffer = buildBufferWithNulAt({ length: 8_001, nulIndex: 8_000 })
+
+    expect(decodeTextBuffer(buffer)).toEqual({
+      status: "text",
+      text: `${"a".repeat(8_000)}\u0000`,
+    })
+  })
+
+  it("calls BOM-less UTF-16 text binary, since its ASCII characters carry NUL bytes", () => {
+    expect(decodeTextBuffer(Buffer.from("hi", "utf16le"))).toEqual({ status: "binary" })
+  })
+
+  it("calls bytes that are not UTF-8 invalid", () => {
+    // 0xE9 is "é" in Latin-1 and never a complete UTF-8 sequence
+    expect(decodeTextBuffer(Buffer.from([0x63, 0x61, 0x66, 0xe9]))).toEqual({
+      status: "invalid-utf8",
+    })
+  })
+
+  it("calls an encoded UTF-16 surrogate invalid, as a strict UTF-8 decoder does", () => {
+    expect(decodeTextBuffer(Buffer.from([0xed, 0xa0, 0x80]))).toEqual({ status: "invalid-utf8" })
+  })
+
+  it("drops a leading byte-order mark", () => {
+    const withByteOrderMark = Buffer.from([0xef, 0xbb, 0xbf, 0x68, 0x69])
+
+    expect(decodeTextBuffer(withByteOrderMark)).toEqual({ status: "text", text: "hi" })
+  })
+})
diff --git a/src/utils/decode-text-buffer.ts b/src/utils/decode-text-buffer.ts
new file mode 100644
index 000000000..bf20b12c4
--- /dev/null
+++ b/src/utils/decode-text-buffer.ts
@@ -0,0 +1,26 @@
+import { isUtf8 } from "node:buffer"
+
+/** How many leading bytes are searched for a NUL byte. Git calls a file binary
+ *  when its first 8,000 bytes hold one (FIRST_FEW_BYTES in xdiff-interface.c):
+ *  https://github.com/git/git/blob/master/xdiff-interface.c */
+export const NUL_SEARCH_WINDOW_BYTES = 8_000
+
+type DecodedTextBuffer =
+  | Readonly<{ status: "text"; text: string }>
+  | Readonly<{ status: "binary" }>
+  | Readonly<{ status: "invalid-utf8" }>
+
+// Decoding is stateless outside streaming mode, so one decoder serves every call.
+const utf8Decoder = new TextDecoder("utf-8")
+
+/** Decodes bytes as UTF-8 text.
+ *  - A NUL byte within the first NUL_SEARCH_WINDOW_BYTES marks them binary.
+ *  - Any byte sequence that is not UTF-8 marks them invalid.
+ *  - A leading byte-order mark is dropped, as TextDecoder does by default. */
+export const decodeTextBuffer = (buffer: Uint8Array): DecodedTextBuffer => {
+  const holdsEarlyNulByte = buffer.subarray(0, NUL_SEARCH_WINDOW_BYTES).includes(0)
+
+  if (holdsEarlyNulByte) return { status: "binary" }
+  if (!isUtf8(buffer)) return { status: "invalid-utf8" }
+  return { status: "text", text: utf8Decoder.decode(buffer) }
+}
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index e99a747d4..c09bf4c4d 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -2848,21 +2848,37 @@ describe("file tool handlers", () => {
     })
   })
 
-  it("rejects an unsupported extension naming the readable types", async () => {
+  it("rejects a file holding NUL bytes, naming the readable types", async () => {
     const { vault, readAsset } = await setupAssetHarness()
-    await writeFile(join(vault, "song.mp3"), "xxxx", "utf8")
+    // An ID3v2.4 tag header, which opens most MP3 files and holds NUL bytes
+    await writeFile(join(vault, "song.mp3"), Buffer.from([0x49, 0x44, 0x33, 0x04, 0x00, 0x00]))
     const result = await readAsset({ path: "song.mp3" })
     expect(result).toEqual({
       isError: true,
       content: [
         {
           type: "text",
-          text: '[Error]: unsupported file type ".mp3": "song.mp3" exists (4 bytes). Readable types: images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base)',
+          text: '[Error]: unsupported file type ".mp3": "song.mp3" exists (6 bytes) and holds a NUL byte in its first 8,000 bytes (binary data or UTF-16 text). Readable types: images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and UTF-8 text files',
         },
       ],
     })
   })
 
+  it("returns an HTML page's source as text", async () => {
+    const { vault, readAsset } = await setupAssetHarness()
+    const pageSource = "<!doctype html>\n<h1>Runbook</h1>\n<script>restart()</script>\n"
+    await writeFile(join(vault, "runbook.html"), pageSource, "utf8")
+    const result = await readAsset({ path: "runbook.html" })
+    expect(result).toEqual({ content: [{ type: "text", text: pageSource }] })
+  })
+
+  it("reads a note whose .MD extension is uppercase as text, until notes with that extension are supported", async () => {
+    const { vault, readAsset } = await setupAssetHarness()
+    await writeFile(join(vault, "Note.MD"), "# Upper\n", "utf8")
+    const result = await readAsset({ path: "Note.MD" })
+    expect(result).toEqual({ content: [{ type: "text", text: "# Upper\n" }] })
+  })
+
   it("rejects a .md path without touching the note", async () => {
     const { vault, readAsset } = await setupAssetHarness()
     await writeFile(join(vault, "note.md"), "# A note\n", "utf8")
diff --git a/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts b/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
index d9697e90f..d476c3f38 100644
--- a/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
+++ b/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
@@ -440,25 +440,6 @@ describe("readAssetContent — PDF extraction", () => {
     )
   })
 
-  it("includes .pdf in the unsupported-type error's readable types list", async () => {
-    mockedReadAsset.mockResolvedValue({
-      buffer: Buffer.from("fake-audio"),
-      bytes: 10_000,
-      extension: ".mp3",
-    })
-
-    await expect(
-      assetOperations.readAssetContent({ ...defaultParams, path: "audio/song.mp3" }, logger),
-    ).rejects.toThrow(
-      new Error(
-        'unsupported file type ".mp3": "audio/song.mp3" exists ' +
-          "(10000 bytes). Readable types: images " +
-          "(.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and text formats " +
-          "(.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base)",
-      ),
-    )
-  })
-
   it("passes a PDF load failure other than pdf.js refusing the file through unchanged", async () => {
     mockedReadAsset.mockResolvedValue({
       buffer: Buffer.from("not-a-real-pdf"),
@@ -1017,6 +998,124 @@ describe("readAssetContent — PDF page rendering (raw: true)", () => {
   })
 })
 
+describe("readAssetContent — UTF-8 files outside the dedicated types", () => {
+  /** Stubs readAsset with the given bytes, reporting the extension lowercased
+   *  as readAsset does. */
+  const stubReadAsset = (params: { buffer: Buffer; extension: string }): void => {
+    mockedReadAsset.mockResolvedValue({
+      buffer: params.buffer,
+      bytes: params.buffer.length,
+      extension: params.extension,
+    })
+  }
+
+  /** `length` bytes of ASCII "a" with a NUL byte at `nulIndex`. */
+  const buildBufferWithNulAt = (params: { length: number; nulIndex: number }): Buffer => {
+    const buffer = Buffer.alloc(params.length, "a")
+    buffer[params.nulIndex] = 0
+    return buffer
+  }
+
+  it.each([
+    {
+      label: "an HTML page's source",
+      path: "runbooks/restart.html",
+      extension: ".html",
+      source: '<!doctype html>\n<p class="step">Restart &mdash; then wait</p>\n',
+    },
+    {
+      label: "a Python script",
+      path: "scripts/report.py",
+      extension: ".py",
+      source: "def get_user_name():\n    return 'café'\n",
+    },
+    {
+      label: "a PowerShell script",
+      path: "scripts/Backup.ps1",
+      extension: ".ps1",
+      source: "Get-ChildItem -Path $Home | Out-Null\r\n",
+    },
+    {
+      label: "a file with no extension",
+      path: "scripts/Makefile",
+      extension: "",
+      source: "build:\n\tnpm run build\n",
+    },
+  ])("returns $label byte-exact as text", async ({ path, extension, source }) => {
+    stubReadAsset({ buffer: Buffer.from(source, "utf8"), extension })
+
+    const result = await assetOperations.readAssetContent({ ...defaultParams, path }, logger)
+
+    expect(result).toEqual({ kind: "text", text: source, path })
+  })
+
+  it("pages a script by line like the dedicated text formats", async () => {
+    stubReadAsset({ buffer: Buffer.from("one\ntwo\nthree\nfour\n", "utf8"), extension: ".sh" })
+
+    const result = await assetOperations.readAssetContent(
+      { ...defaultParams, path: "deploy.sh", startLine: 2, limit: 2 },
+      logger,
+    )
+
+    expect(result).toEqual({
+      kind: "text",
+      text: "two\nthree",
+      path: "deploy.sh",
+      lineWindow: { startLine: 2, endLine: 3, totalLines: 4 },
+    })
+  })
+
+  it("refuses a file with a NUL byte in its first 8,000 bytes, naming the readable types", async () => {
+    stubReadAsset({
+      buffer: buildBufferWithNulAt({ length: 9_000, nulIndex: 7_999 }),
+      extension: ".mp3",
+    })
+
+    await expect(
+      assetOperations.readAssetContent({ ...defaultParams, path: "audio/song.mp3" }, logger),
+    ).rejects.toThrow(
+      new Error(
+        'unsupported file type ".mp3": "audio/song.mp3" exists (9000 bytes) and holds a NUL ' +
+          "byte in its first 8,000 bytes (binary data or UTF-16 text). Readable types: images " +
+          "(.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and UTF-8 text files",
+      ),
+    )
+  })
+
+  it("reads an HTML page whose first NUL byte sits just past the first 8,000 bytes", async () => {
+    const buffer = buildBufferWithNulAt({ length: 8_001, nulIndex: 8_000 })
+    stubReadAsset({ buffer, extension: ".html" })
+
+    const result = await assetOperations.readAssetContent(
+      { ...defaultParams, path: "padded.html" },
+      logger,
+    )
+
+    expect(result).toEqual({ kind: "text", text: buffer.toString("utf8"), path: "padded.html" })
+  })
+
+  it("refuses an HTML page that is not UTF-8", async () => {
+    // 0xE9 is "é" in Latin-1 and never a complete UTF-8 sequence
+    stubReadAsset({ buffer: Buffer.from([0x3c, 0x70, 0x3e, 0xe9]), extension: ".html" })
+
+    await expect(
+      assetOperations.readAssetContent({ ...defaultParams, path: "latin1.html" }, logger),
+    ).rejects.toThrow(new Error('not valid UTF-8: "latin1.html" cannot be returned as text'))
+  })
+
+  it("keeps reading a log that opens with NUL bytes, since the dedicated text formats skip the NUL check", async () => {
+    const buffer = Buffer.concat([Buffer.alloc(4), Buffer.from("boot ok\n", "utf8")])
+    stubReadAsset({ buffer, extension: ".log" })
+
+    const result = await assetOperations.readAssetContent(
+      { ...defaultParams, path: "server.log" },
+      logger,
+    )
+
+    expect(result).toEqual({ kind: "text", text: buffer.toString("utf8"), path: "server.log" })
+  })
+})
+
 describe("readAssetContent — line paging", () => {
   /** Stubs readAsset with a UTF-8 text file of the given extension. */
   const stubReadAsset = (content: string, extension: string): void => {
diff --git a/src/vault-mcp/vault-operations/asset-operations.ts b/src/vault-mcp/vault-operations/asset-operations.ts
index 5f15be56c..14a49d24c 100644
--- a/src/vault-mcp/vault-operations/asset-operations.ts
+++ b/src/vault-mcp/vault-operations/asset-operations.ts
@@ -7,6 +7,7 @@ import { pageTextByLines } from "../obsidian-markdown/lines.js"
 import type { LineWindow } from "../obsidian-markdown/lines.js"
 import { extractPdfText } from "../obsidian-markdown/pdf.js"
 import { canvasImport, createPdfDocumentProxy } from "../obsidian-markdown/pdf-engine.js"
+import { decodeTextBuffer, NUL_SEARCH_WINDOW_BYTES } from "../../utils/decode-text-buffer.js"
 import { describeErrorForLog } from "../../utils/describe-error.js"
 import { fitImageToByteBudget } from "../../utils/fit-image-to-byte-budget.js"
 import type { FittedImage } from "../../utils/fit-image-to-byte-budget.js"
@@ -19,9 +20,9 @@ import type { Logger } from "../../logger.js"
  *
  * - `readAssetContent` dispatches one file to its most useful representation:
  *   images fitted to a byte budget, canvases linearized (or their raw JSON
- *   source), PDFs as extracted text (or rendered page images), text formats
- *   decoded verbatim — whole, or as a 1-based line window when paging params
- *   are supplied — structured errors for the rest.
+ *   source), PDFs as extracted text (or rendered page images), and every other
+ *   file decoded verbatim as UTF-8 text — whole, or as a 1-based line window
+ *   when paging params are supplied.
  * - `buildAssetListing` browses many: extension-filtered, counted per
  *   extension over the full filtered set, and capped to a statted slice.
  *   There is no pagination — `limit` caps the returned entries, and
@@ -36,8 +37,9 @@ import type { Logger } from "../../logger.js"
 /** Extensions dispatched to the image pipeline (model-visible image blocks). */
 const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"])
 
-/** Extensions returned verbatim as text — plain-text formats an agent can
- *  read directly. .svg is XML source; .base is Obsidian Bases YAML. */
+/** Extensions returned verbatim as text with no NUL byte check, so a
+ *  NUL-padded log still reads. .svg is XML source; .base is Obsidian Bases
+ *  YAML. */
 const TEXT_PASSTHROUGH_EXTENSIONS = new Set([
   ".svg",
   ".json",
@@ -167,6 +169,36 @@ const decodeUtf8Strict = (params: { buffer: Buffer; path: string }): string => {
   }
 }
 
+/** Builds the text result for a file outside the dedicated types (HTML pages,
+ *  scripts, files with no extension), refusing binary data and bytes that are
+ *  not UTF-8. */
+const buildUtf8SourceResult = (params: {
+  buffer: Buffer
+  bytes: number
+  extension: string
+  path: string
+  startLine?: number | undefined
+  limit?: number | undefined
+}): AssetReadResult => {
+  const { path, startLine, limit } = params
+  const decodedSource = decodeTextBuffer(params.buffer)
+
+  switch (decodedSource.status) {
+    case "text":
+      return buildTextResult({ text: decodedSource.text, path, startLine, limit })
+    case "binary":
+      throw new Error(
+        `unsupported file type "${params.extension}": "${path}" exists ` +
+          `(${params.bytes} bytes) and holds a NUL byte in its first ` +
+          `${NUL_SEARCH_WINDOW_BYTES.toLocaleString("en-US")} bytes (binary data or UTF-16 text). ` +
+          `Readable types: images (${[...IMAGE_EXTENSIONS].join("/")}), .canvas, .pdf, ` +
+          `and UTF-8 text files`,
+      )
+    case "invalid-utf8":
+      throw new Error(`not valid UTF-8: "${path}" cannot be returned as text`)
+  }
+}
+
 // ── PDF reading ───────────────────────────────────────────────
 
 /** The server's message for pdf.js refusing to open a vault file, worded like
@@ -337,9 +369,9 @@ const readPdfPages = async (
  *   outline or raw JSON, PDF-extracted text), so every path that can hit the
  *   text cap can also be paged.
  * - Throws structured errors for images with `raw`, non-text reads with
- *   paging params, PDFs that can't be opened or yield nothing, and
- *   unsupported types; the PDF and unsupported-type errors state the file's
- *   existence and size.
+ *   paging params, PDFs that can't be opened or yield nothing, binary data
+ *   outside the dedicated types, and text that is not UTF-8; the PDF and
+ *   binary-data errors state the file's existence and size.
  */
 const readAssetContent = async (
   params: {
@@ -438,12 +470,14 @@ const readAssetContent = async (
       limit,
     })
   }
-  throw new Error(
-    `unsupported file type "${asset.extension}": "${path}" exists ` +
-      `(${asset.bytes} bytes). Readable types: images ` +
-      `(${[...IMAGE_EXTENSIONS].join("/")}), .canvas, .pdf, and text formats ` +
-      `(${[...TEXT_PASSTHROUGH_EXTENSIONS].join("/")})`,
-  )
+  return buildUtf8SourceResult({
+    buffer: asset.buffer,
+    bytes: asset.bytes,
+    extension: asset.extension,
+    path,
+    startLine,
+    limit,
+  })
 }
 
 // ── Browsing ────────────────────────────────────────────────────

From 76c8cd0d3f7c0121b3cdcc4e1a0e55259dedf448 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 00:05:32 -0500
Subject: [PATCH 02/38] fix(search): index and link files whatever the letter
 case of their extension

One file-kind helper (obsidian-markdown/file-kinds.ts) maps a lowercased
extension to a kind, and every extension check in reading, indexing, the
note mover and the link tools uses it. A scanner's .PDF, an .TXT or a
.CSV is now searchable, a .Canvas's file cards count as links and are
rewritten when a note moves, and search results report the extension
lowercased, as vault_list_files does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../__tests__/file-kinds.test.ts              |  96 ++++++++
 src/vault-mcp/obsidian-markdown/file-kinds.ts |  48 ++++
 .../search/__tests__/file-watcher.test.ts     | 107 +++++++++
 .../search/__tests__/search-index.test.ts     | 129 ++++++++--
 src/vault-mcp/search/file-watcher.ts          |  23 +-
 src/vault-mcp/search/hybrid-search.ts         |  22 +-
 src/vault-mcp/search/search-helpers.ts        |   3 +-
 src/vault-mcp/search/search-index.ts          |  35 +--
 src/vault-mcp/search/search-queries.ts        |  12 +-
 .../__tests__/note-mover.test.ts              |  59 +++--
 .../vault-operations/asset-operations.ts      | 225 ++++++++++--------
 src/vault-mcp/vault-operations/note-mover.ts  |   5 +-
 12 files changed, 589 insertions(+), 175 deletions(-)
 create mode 100644 src/vault-mcp/obsidian-markdown/__tests__/file-kinds.test.ts
 create mode 100644 src/vault-mcp/obsidian-markdown/file-kinds.ts

diff --git a/src/vault-mcp/obsidian-markdown/__tests__/file-kinds.test.ts b/src/vault-mcp/obsidian-markdown/__tests__/file-kinds.test.ts
new file mode 100644
index 000000000..433687bd3
--- /dev/null
+++ b/src/vault-mcp/obsidian-markdown/__tests__/file-kinds.test.ts
@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest"
+import { getExtensionsOfKind, getFileKind, isCanvasPath } from "../file-kinds.js"
+
+// Test-owned, so a change to the production map has to change this table too
+const EXPECTED_KINDS = [
+  { extension: ".png", kind: "image" },
+  { extension: ".jpg", kind: "image" },
+  { extension: ".jpeg", kind: "image" },
+  { extension: ".gif", kind: "image" },
+  { extension: ".webp", kind: "image" },
+  { extension: ".canvas", kind: "canvas" },
+  { extension: ".pdf", kind: "pdf" },
+  { extension: ".txt", kind: "text" },
+  { extension: ".csv", kind: "text" },
+  { extension: ".json", kind: "text" },
+  { extension: ".xml", kind: "text" },
+  { extension: ".svg", kind: "text" },
+  { extension: ".log", kind: "text" },
+  { extension: ".yaml", kind: "text" },
+  { extension: ".yml", kind: "text" },
+  { extension: ".base", kind: "text" },
+  { extension: ".html", kind: "html" },
+  { extension: ".htm", kind: "html" },
+  { extension: ".py", kind: "script" },
+  { extension: ".sh", kind: "script" },
+  { extension: ".ps1", kind: "script" },
+] as const
+
+/** Uppercases every second letter of an extension: ".canvas" becomes ".cAnVaS". */
+const toMixedCase = (extension: string): string => {
+  return [...extension]
+    .map((character, index) => (index % 2 === 0 ? character.toUpperCase() : character))
+    .join("")
+}
+
+describe("getFileKind", () => {
+  it.each(EXPECTED_KINDS)("maps $extension to $kind", ({ extension, kind }) => {
+    expect(getFileKind(`Folder/file${extension}`)).toBe(kind)
+  })
+
+  it.each(EXPECTED_KINDS)("maps an uppercase $extension to $kind", ({ extension, kind }) => {
+    expect(getFileKind(`Folder/FILE${extension.toUpperCase()}`)).toBe(kind)
+  })
+
+  it.each(EXPECTED_KINDS)("maps a mixed-case $extension to $kind", ({ extension, kind }) => {
+    expect(getFileKind(`Folder/file${toMixedCase(extension)}`)).toBe(kind)
+  })
+
+  it("maps a file with no extension to other", () => {
+    expect(getFileKind("scripts/Makefile")).toBe("other")
+  })
+
+  it("maps an extension the map does not list to other", () => {
+    expect(getFileKind("audio/song.mp3")).toBe("other")
+  })
+
+  it("maps a markdown note to other, since notes are not files", () => {
+    expect(getFileKind("Projects/plan.md")).toBe("other")
+  })
+
+  it("reads the kind from the last extension only", () => {
+    expect(getFileKind("exports/report.pdf.txt")).toBe("text")
+  })
+
+  it("maps a dot-prefixed name with no other dot to other", () => {
+    expect(getFileKind("config/.pdf")).toBe("other")
+  })
+})
+
+describe("isCanvasPath", () => {
+  it("accepts a canvas in any letter case", () => {
+    expect(["Board.canvas", "Board.Canvas", "Board.CANVAS"].map(isCanvasPath)).toEqual([
+      true,
+      true,
+      true,
+    ])
+  })
+
+  it("rejects a note and other files", () => {
+    expect(["Board.md", "Board.canvas.md", "Board.json"].map(isCanvasPath)).toEqual([
+      false,
+      false,
+      false,
+    ])
+  })
+})
+
+describe("getExtensionsOfKind", () => {
+  it("lists the image extensions in order", () => {
+    expect(getExtensionsOfKind("image")).toEqual([".png", ".jpg", ".jpeg", ".gif", ".webp"])
+  })
+
+  it("lists nothing for other, which covers unlisted extensions", () => {
+    expect(getExtensionsOfKind("other")).toEqual([])
+  })
+})
diff --git a/src/vault-mcp/obsidian-markdown/file-kinds.ts b/src/vault-mcp/obsidian-markdown/file-kinds.ts
new file mode 100644
index 000000000..74c64ca7b
--- /dev/null
+++ b/src/vault-mcp/obsidian-markdown/file-kinds.ts
@@ -0,0 +1,48 @@
+import { posix } from "node:path"
+
+/** What a non-markdown vault file holds, which decides how it is read and
+ *  indexed. "other" covers every extension the map below does not list, and
+ *  files with no extension. */
+export type FileKind = "image" | "canvas" | "pdf" | "text" | "html" | "script" | "other"
+
+/** Keys are lowercase, and lookups lowercase the extension first, so a
+ *  scanner's ".PDF" is a PDF. .svg is XML source; .base is Obsidian Bases
+ *  YAML. */
+const FILE_KINDS_BY_EXTENSION: ReadonlyMap<string, FileKind> = new Map([
+  [".png", "image"],
+  [".jpg", "image"],
+  [".jpeg", "image"],
+  [".gif", "image"],
+  [".webp", "image"],
+  [".canvas", "canvas"],
+  [".pdf", "pdf"],
+  [".txt", "text"],
+  [".csv", "text"],
+  [".json", "text"],
+  [".xml", "text"],
+  [".svg", "text"],
+  [".log", "text"],
+  [".yaml", "text"],
+  [".yml", "text"],
+  [".base", "text"],
+  [".html", "html"],
+  [".htm", "html"],
+  [".py", "script"],
+  [".sh", "script"],
+  [".ps1", "script"],
+])
+
+export const getFileKind = (filePath: string): FileKind => {
+  return FILE_KINDS_BY_EXTENSION.get(posix.extname(filePath).toLowerCase()) ?? "other"
+}
+
+export const isCanvasPath = (filePath: string): boolean => {
+  return getFileKind(filePath) === "canvas"
+}
+
+/** The lowercase extensions mapped to `kind`, in the map's order. */
+export const getExtensionsOfKind = (kind: FileKind): string[] => {
+  return [...FILE_KINDS_BY_EXTENSION]
+    .filter(([, mappedKind]) => mappedKind === kind)
+    .map(([extension]) => extension)
+}
diff --git a/src/vault-mcp/search/__tests__/file-watcher.test.ts b/src/vault-mcp/search/__tests__/file-watcher.test.ts
index 35f81e143..6d6ef662c 100644
--- a/src/vault-mcp/search/__tests__/file-watcher.test.ts
+++ b/src/vault-mcp/search/__tests__/file-watcher.test.ts
@@ -501,6 +501,113 @@ describe("file-watcher — file content indexing", () => {
     ])
   })
 
+  it.each([
+    {
+      label: ".TXT",
+      fileName: "upper.TXT",
+      content: "crimson memo\n",
+      query: "crimson",
+      extension: ".txt",
+    },
+    {
+      label: ".CSV",
+      fileName: "Prices.CSV",
+      content: "id,item\n1,saffron\n",
+      query: "saffron",
+      extension: ".csv",
+    },
+  ])(
+    "indexes a file with an uppercase $label extension and removes it on delete",
+    { timeout: 15000 },
+    async ({ fileName, content, query, extension }) => {
+      const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
+        fileToolsEnabled: true,
+      })
+      const upsertSpy = vi.spyOn(fileIndex, "upsertFileContent")
+      const removeSpy = vi.spyOn(fileIndex, "removeFileContent")
+
+      await startWatcherWithoutRebuild(
+        { vaultPath: vault, search: fileIndex },
+        REAL_WATCHER_OPTIONS,
+      )
+      await writeFile(join(vault, fileName), content, "utf8")
+      await waitFor(() => upsertSpy.mock.calls.length > 0)
+
+      const indexed = await fileIndex.hybridSearch({ query }, logger)
+      expect(
+        indexed.results.map((result) => ({ path: result.path, extension: result.extension })),
+      ).toEqual([{ path: fileName, extension }])
+
+      await unlink(join(vault, fileName))
+      await waitFor(() => removeSpy.mock.calls.length > 0)
+
+      const removed = await fileIndex.hybridSearch({ query }, logger)
+      expect(removed.results).toEqual([])
+    },
+  )
+
+  it(
+    "indexes a PDF with an uppercase extension and removes it on delete",
+    { timeout: 15000 },
+    async () => {
+      const { buildMinimalPdf } = await import("../../obsidian-markdown/__tests__/pdf-fixture.js")
+      const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
+        fileToolsEnabled: true,
+      })
+      const upsertSpy = vi.spyOn(fileIndex, "upsertFileContent")
+      const removeSpy = vi.spyOn(fileIndex, "removeFileContent")
+
+      await startWatcherWithoutRebuild(
+        { vaultPath: vault, search: fileIndex },
+        REAL_WATCHER_OPTIONS,
+      )
+      await writeFile(join(vault, "Report.PDF"), buildMinimalPdf())
+      await waitFor(() => upsertSpy.mock.calls.length > 0)
+
+      const indexed = await fileIndex.hybridSearch({ query: "Hello PDF" }, logger)
+      expect(
+        indexed.results.map((result) => ({ path: result.path, extension: result.extension })),
+      ).toEqual([{ path: "Report.PDF", extension: ".pdf" }])
+
+      await unlink(join(vault, "Report.PDF"))
+      await waitFor(() => removeSpy.mock.calls.length > 0)
+
+      const removed = await fileIndex.hybridSearch({ query: "Hello PDF" }, logger)
+      expect(removed.results).toEqual([])
+    },
+  )
+
+  it(
+    "links the file cards of a canvas with an uppercase extension and drops them on delete",
+    { timeout: 15000 },
+    async () => {
+      const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
+        fileToolsEnabled: true,
+      })
+      const upsertSpy = vi.spyOn(fileIndex, "upsertFileContent")
+      const removeSpy = vi.spyOn(fileIndex, "removeFileContent")
+      const canvasSource = JSON.stringify({
+        nodes: [{ id: "f1", type: "file", x: 0, y: 0, width: 200, height: 100, file: "Plan.md" }],
+        edges: [],
+      })
+
+      await startWatcherWithoutRebuild(
+        { vaultPath: vault, search: fileIndex },
+        REAL_WATCHER_OPTIONS,
+      )
+      await writeFile(join(vault, "Board.Canvas"), canvasSource, "utf8")
+      await waitFor(() => upsertSpy.mock.calls.length > 0)
+
+      const linkedTargets = fileIndex.getOutgoingLinks({ path: "Board.Canvas" }, logger)
+      expect(linkedTargets.map((link) => link.path)).toEqual(["Plan.md"])
+
+      await unlink(join(vault, "Board.Canvas"))
+      await waitFor(() => removeSpy.mock.calls.length > 0)
+
+      expect(fileIndex.getOutgoingLinks({ path: "Board.Canvas" }, logger)).toEqual([])
+    },
+  )
+
   it("calls embedFileContent when indexing a non-md file", { timeout: 15000 }, async () => {
     const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
       fileToolsEnabled: true,
diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index c0a0ee355..550741ce7 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -7,12 +7,13 @@ import Database from "better-sqlite3"
 import { DateTime } from "luxon"
 import * as sqliteVec from "sqlite-vec"
 vi.mock("sqlite-vec", { spy: true })
-import { createSearchIndex, INDEXABLE_TEXT_EXTENSIONS } from "../search-index.js"
+import { createSearchIndex, CONTENT_INDEXED_FILE_KINDS } from "../search-index.js"
 import type { NoteMetadata, OutgoingLinkEntry, SearchIndex, TaskEntry } from "../search-index.js"
 import type { StatusClassification } from "../../obsidian-markdown/tasks.js"
 import { logger } from "../../../logger.js"
 import { statOrNull } from "../../../utils/fs.js"
 import { extractPdfText } from "../../obsidian-markdown/pdf.js"
+import { buildPdf } from "../../obsidian-markdown/__tests__/pdf-fixture.js"
 import type { BodyTagParser, BodyTagParseResult } from "../body-tag-parser.js"
 import { inProcessBodyTagParser, withBodyTags } from "./body-tag-test-helpers.js"
 
@@ -7038,20 +7039,9 @@ Shared datefilter content for mtime boundary tests.
 
 // ── File content indexing constants ──────────────────────────
 
-describe("INDEXABLE_TEXT_EXTENSIONS", () => {
-  it("contains the expected set of extensions for FTS indexing", () => {
-    expect([...INDEXABLE_TEXT_EXTENSIONS].sort()).toEqual([
-      ".base",
-      ".csv",
-      ".json",
-      ".log",
-      ".pdf",
-      ".svg",
-      ".txt",
-      ".xml",
-      ".yaml",
-      ".yml",
-    ])
+describe("CONTENT_INDEXED_FILE_KINDS", () => {
+  it("indexes the content of PDF and text files", () => {
+    expect([...CONTENT_INDEXED_FILE_KINDS].toSorted()).toEqual(["pdf", "text"])
   })
 })
 
@@ -7847,6 +7837,115 @@ describe("canvas file content and links", () => {
 
 // ── File content vector embeddings ────────────────────────────
 
+// Each test rebuilds a vault holding two PDFs, whose text extraction can pass
+// the default 5-second limit on a loaded machine
+describe("files with an uppercase extension", { timeout: 15_000 }, () => {
+  /** A canvas holding one text card and one file card naming `cardPath`. */
+  const buildCanvasWithFileCard = (params: { cardPath: string; text: string }): string => {
+    return JSON.stringify({
+      nodes: [
+        { id: "t1", type: "text", x: 0, y: 0, width: 200, height: 100, text: params.text },
+        { id: "f1", type: "file", x: 300, y: 0, width: 200, height: 100, file: params.cardPath },
+      ],
+      edges: [],
+    })
+  }
+
+  /** Each file holds one word no other file holds, so a search for that word
+   *  finds only that file. Every uppercase file has a lowercase control. */
+  const writeMixedCaseVault = async (): Promise<string> => {
+    const vaultDir = await mkdtemp(join(tmpdir(), "uppercase-extensions-"))
+    onTestFinished(() => rm(vaultDir, { recursive: true }))
+    await mkdir(join(vaultDir, "Notes"))
+    await mkdir(join(vaultDir, "files"))
+    await writeFile(join(vaultDir, "Notes/Plan.md"), "# Plan\n", "utf8")
+    await writeFile(join(vaultDir, "Notes/Route.md"), "# Route\n", "utf8")
+    await writeFile(join(vaultDir, "Notes/Index.md"), "See [[files/Board.Canvas]].\n", "utf8")
+    await writeFile(join(vaultDir, "files/upper.TXT"), "crimson memo\n", "utf8")
+    await writeFile(join(vaultDir, "files/lower.txt"), "teal memo\n", "utf8")
+    await writeFile(join(vaultDir, "files/Prices.CSV"), "id,item\n1,saffron\n", "utf8")
+    await writeFile(join(vaultDir, "files/costs.csv"), "id,item\n1,umber\n", "utf8")
+    await writeFile(
+      join(vaultDir, "files/Report.PDF"),
+      buildPdf([{ text: "amber ledger", x: 100, y: 700, fontSize: 12 }]),
+    )
+    await writeFile(
+      join(vaultDir, "files/control.pdf"),
+      buildPdf([{ text: "violet ledger", x: 100, y: 700, fontSize: 12 }]),
+    )
+    await writeFile(
+      join(vaultDir, "files/Board.Canvas"),
+      buildCanvasWithFileCard({ cardPath: "Notes/Plan.md", text: "indigo board" }),
+      "utf8",
+    )
+    await writeFile(
+      join(vaultDir, "files/control.canvas"),
+      buildCanvasWithFileCard({ cardPath: "Notes/Route.md", text: "olive board" }),
+      "utf8",
+    )
+    return vaultDir
+  }
+
+  const rebuildMixedCaseIndex = async (): Promise<SearchIndex> => {
+    const vaultDir = await writeMixedCaseVault()
+    const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
+      fileToolsEnabled: true,
+    })
+    await fileIndex.rebuildFromVault(
+      { vaultPath: vaultDir, bodyTagParser: inProcessBodyTagParser },
+      logger,
+    )
+    return fileIndex
+  }
+
+  it("finds every file by its content after a rebuild, reporting its extension lowercased", async () => {
+    const fileIndex = await rebuildMixedCaseIndex()
+    const queries = ["crimson", "teal", "saffron", "umber", "amber", "violet", "indigo", "olive"]
+
+    const searchFor = async (query: string) => {
+      const { results } = await fileIndex.hybridSearch({ query }, logger)
+      return results.map(({ path, extension }) => ({ path, extension }))
+    }
+
+    expect(await Promise.all(queries.map(searchFor))).toEqual([
+      [{ path: "files/upper.TXT", extension: ".txt" }],
+      [{ path: "files/lower.txt", extension: ".txt" }],
+      [{ path: "files/Prices.CSV", extension: ".csv" }],
+      [{ path: "files/costs.csv", extension: ".csv" }],
+      [{ path: "files/Report.PDF", extension: ".pdf" }],
+      [{ path: "files/control.pdf", extension: ".pdf" }],
+      [{ path: "files/Board.Canvas", extension: ".canvas" }],
+      [{ path: "files/control.canvas", extension: ".canvas" }],
+    ])
+  })
+
+  it("lists the file cards of a canvas with an uppercase extension as its outgoing links", async () => {
+    const fileIndex = await rebuildMixedCaseIndex()
+
+    const outgoingLinks = fileIndex.getOutgoingLinks({ path: "files/Board.Canvas" }, logger)
+
+    expect(outgoingLinks.map(({ path, exists }) => ({ path, exists }))).toEqual([
+      { path: "Notes/Plan.md", exists: true },
+    ])
+  })
+
+  it("lists a canvas with an uppercase extension among a note's backlinks", async () => {
+    const fileIndex = await rebuildMixedCaseIndex()
+
+    const backlinks = fileIndex.getBacklinks({ path: "Notes/Plan.md" }, logger)
+
+    expect(backlinks.map((backlink) => backlink.path)).toEqual(["files/Board.Canvas"])
+  })
+
+  it("lists the notes linking to a canvas with an uppercase extension", async () => {
+    const fileIndex = await rebuildMixedCaseIndex()
+
+    const backlinks = fileIndex.getBacklinks({ path: "files/Board.Canvas" }, logger)
+
+    expect(backlinks.map((backlink) => backlink.path)).toEqual(["Notes/Index.md"])
+  })
+})
+
 describe("committed embedding source versions", () => {
   it.each(["note", "file"] as const)(
     "rejects a %s model result after source deletion",
diff --git a/src/vault-mcp/search/file-watcher.ts b/src/vault-mcp/search/file-watcher.ts
index 9fd6007f8..a339e1d1a 100644
--- a/src/vault-mcp/search/file-watcher.ts
+++ b/src/vault-mcp/search/file-watcher.ts
@@ -7,9 +7,9 @@ import { watch } from "chokidar"
 import { DateTime } from "luxon"
 import { readFile, readdir, stat } from "node:fs/promises"
 import type { Stats } from "node:fs"
-import { extname, join, relative, resolve as resolvePath, sep } from "node:path"
+import { join, relative, resolve as resolvePath, sep } from "node:path"
 import {
-  INDEXABLE_TEXT_EXTENSIONS,
+  CONTENT_INDEXED_FILE_KINDS,
   INDEXING_FILE_READ_CONCURRENCY,
   PDF_EXTRACTION_CONCURRENCY,
 } from "./search-index.js"
@@ -21,6 +21,7 @@ import {
 } from "./body-tag-parser.js"
 import { splitPropertiesBlock } from "../obsidian-markdown/frontmatter.js"
 import { extractPdfText } from "../obsidian-markdown/pdf.js"
+import { getFileKind, isCanvasPath } from "../obsidian-markdown/file-kinds.js"
 import type { Logger } from "../../logger.js"
 import { describeError, describeErrorForLog } from "../../utils/describe-error.js"
 import { isErrnoException } from "../../utils/is-errno-exception.js"
@@ -225,17 +226,16 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
     }
 
     // Canvas files are always read — link extraction is unconditional.
-    // PDF and text files (INDEXABLE_TEXT_EXTENSIONS, which includes .pdf) are
-    // only read when file content FTS is enabled.
-    const extension = extname(filePath)
-    const isCanvas = extension === ".canvas"
+    // PDF and text files are only read when file content FTS is enabled.
+    const fileKind = getFileKind(filePath)
+    const isCanvas = fileKind === "canvas"
     const isIndexableNonCanvas =
-      search.fileContentIndexingEnabled && INDEXABLE_TEXT_EXTENSIONS.has(extension)
+      search.fileContentIndexingEnabled && CONTENT_INDEXED_FILE_KINDS.has(fileKind)
 
     if (isCanvas || isIndexableNonCanvas) {
       try {
         const readContentToIndex = async (): Promise<string> => {
-          if (extension !== ".pdf") return await readFile(filePath, "utf8")
+          if (fileKind !== "pdf") return await readFile(filePath, "utf8")
 
           const buffer = await readFile(filePath)
           // pdfjs throws on a Node Buffer, so it gets a plain Uint8Array view
@@ -518,10 +518,9 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
 
       // The content rows live in their own tables, so they are removed even
       // when the asset-table removal above failed.
-      const deletedExtension = extname(filePath)
-      const isDeletedCanvas = deletedExtension === ".canvas"
+      const isDeletedCanvas = isCanvasPath(filePath)
       const isDeletedIndexable =
-        search.fileContentIndexingEnabled && INDEXABLE_TEXT_EXTENSIONS.has(deletedExtension)
+        search.fileContentIndexingEnabled && CONTENT_INDEXED_FILE_KINDS.has(getFileKind(filePath))
 
       if (isDeletedCanvas || isDeletedIndexable) {
         try {
@@ -914,7 +913,7 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
     // indexChangedNonMdFile extracts a PDF's text only when file content
     // indexing is on; otherwise a PDF is only statted and keeps the general bound.
     const needsPdfExtraction = ({ filePath }: ReservedPath): boolean => {
-      return search.fileContentIndexingEnabled && extname(filePath) === ".pdf"
+      return search.fileContentIndexingEnabled && getFileKind(filePath) === "pdf"
     }
     const pdfReads = reservedPaths.filter(needsPdfExtraction)
     const otherReads = reservedPaths.filter((reservedPath) => !needsPdfExtraction(reservedPath))
diff --git a/src/vault-mcp/search/hybrid-search.ts b/src/vault-mcp/search/hybrid-search.ts
index 27f43c318..63fe95447 100644
--- a/src/vault-mcp/search/hybrid-search.ts
+++ b/src/vault-mcp/search/hybrid-search.ts
@@ -4,6 +4,7 @@ import type Database from "better-sqlite3"
 import type { Logger } from "../../logger.js"
 import { describeError } from "../../utils/describe-error.js"
 import { compareByUtf8Bytes } from "../../utils/compare-utf8-bytes.js"
+import { getFileKind } from "../obsidian-markdown/file-kinds.js"
 import { sanitizeFtsQuery } from "./fts-query.js"
 import { computeRrfScores } from "./rrf.js"
 import { blendScores } from "./reranker.js"
@@ -46,11 +47,20 @@ const DEFAULT_FILE_LEG_WEIGHT = 0.5
  *  kind that is off-topic for the query. Overridable like the leg weight. */
 const DEFAULT_RERANK_KIND_PREFIX = false
 
-/** Kind label for the reranker prefix, from the file's extension. */
-const fileKindLabel = (extension: string | undefined): string => {
-  if (extension === ".pdf") return "PDF file"
-  if (extension === ".canvas") return "Canvas file"
-  return "File"
+/** Kind label for the reranker prefix. */
+const fileKindLabel = (filePath: string): string => {
+  switch (getFileKind(filePath)) {
+    case "pdf":
+      return "PDF file"
+    case "canvas":
+      return "Canvas file"
+    case "image":
+    case "text":
+    case "html":
+    case "script":
+    case "other":
+      return "File"
+  }
 }
 
 // ── Vector search (internal) ───────────────────────────────────
@@ -299,7 +309,7 @@ const tryRerank = async (params: {
       // Kind marker only — the chunk text already opens with the file's
       // title, so prefixing the filename again would just repeat it.
       if (params.rerankKindPrefix && result.kind === "file") {
-        return `${fileKindLabel(result.extension)}: ${documentText}`
+        return `${fileKindLabel(result.path)}: ${documentText}`
       }
       return documentText
     })
diff --git a/src/vault-mcp/search/search-helpers.ts b/src/vault-mcp/search/search-helpers.ts
index 361c07e34..20306be71 100644
--- a/src/vault-mcp/search/search-helpers.ts
+++ b/src/vault-mcp/search/search-helpers.ts
@@ -321,7 +321,8 @@ export const fileContentRowToSearchResult = (
   folder: row.folder,
   type: null,
   kind: "file",
-  extension: posix.extname(row.path) || undefined,
+  // Lowercased, as vault_list_files reports it
+  extension: posix.extname(row.path).toLowerCase() || undefined,
   modified: storedMtimeToIso(row.mtime),
   bytes: row.bytes,
 })
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index d9dafc936..031eb7337 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -9,6 +9,8 @@ import type { Logger } from "../../logger.js"
 import { parseLeadingCallout } from "../obsidian-markdown/callouts.js"
 import type { LeadingCallout } from "../obsidian-markdown/callouts.js"
 import { linearizeCanvas, extractCanvasFileLinks } from "../obsidian-markdown/canvas.js"
+import { getFileKind, isCanvasPath } from "../obsidian-markdown/file-kinds.js"
+import type { FileKind } from "../obsidian-markdown/file-kinds.js"
 import { links } from "../obsidian-markdown/links.js"
 import { splitIntoLines } from "../obsidian-markdown/lines.js"
 import { parseHeadings } from "../obsidian-markdown/headings.js"
@@ -62,20 +64,10 @@ export const INDEXING_FILE_READ_CONCURRENCY = 16
  *  CPU-heavy, so fewer run together than other file reads. */
 export const PDF_EXTRACTION_CONCURRENCY = 4
 
-/** Extensions whose content is indexed into file_content_fts for vault_search.
- *  Excludes .canvas (own path with link extraction) and .md (notes_fts). */
-export const INDEXABLE_TEXT_EXTENSIONS = new Set([
-  ".pdf",
-  ".txt",
-  ".csv",
-  ".json",
-  ".xml",
-  ".svg",
-  ".log",
-  ".yaml",
-  ".yml",
-  ".base",
-])
+/** File kinds whose content is indexed into file_content_fts when file tools
+ *  are on. A canvas is left out because it is read whatever that setting is,
+ *  since its file cards are graph links. */
+export const CONTENT_INDEXED_FILE_KINDS: ReadonlySet<FileKind> = new Set(["pdf", "text"])
 
 /** Cap on rendered content indexed into file_content_fts — prevents
  *  pathological FTS rows from large CSVs or verbose JSONs. */
@@ -1331,10 +1323,10 @@ export const createSearchIndex = (
     logger: Logger,
   ): symbol => {
     const extension = posix.extname(params.filePath)
-    const isCanvas = extension === ".canvas"
+    const isCanvas = isCanvasPath(params.filePath)
 
-    // Canvas: linearize for FTS, raw JSON for link extraction.
-    // Other types: rawContent is already the rendered text.
+    // A canvas is linearized for FTS, and its raw JSON is read for links.
+    // Every other kind arrives as its rendered text.
     const contentToIndex = isCanvas ? linearizeCanvas(params.rawContent) : params.rawContent
 
     // Truncate content exceeding the FTS cap — iterates Unicode code points
@@ -2316,17 +2308,14 @@ export const createSearchIndex = (
       mapper: readFileSize,
     })
     const nonMarkdownFileSizes = nonMarkdownFileSizeResults.filter((entry) => entry !== null)
-    const canvasFiles = allNonMdFiles.filter((file) => file.relativePath.endsWith(".canvas"))
+    const canvasFiles = allNonMdFiles.filter((file) => isCanvasPath(file.relativePath))
     // PDF and text files are only read when file content FTS is enabled —
     // without the tables, the extraction is wasted I/O.
     const pdfFiles = fileToolsEnabled
-      ? allNonMdFiles.filter((file) => file.relativePath.endsWith(".pdf"))
+      ? allNonMdFiles.filter((file) => getFileKind(file.relativePath) === "pdf")
       : []
     const textFiles = fileToolsEnabled
-      ? allNonMdFiles.filter((file) => {
-          const extension = posix.extname(file.relativePath)
-          return extension !== ".pdf" && INDEXABLE_TEXT_EXTENSIONS.has(extension)
-        })
+      ? allNonMdFiles.filter((file) => getFileKind(file.relativePath) === "text")
       : []
 
     const readRebuildFileContent = async (params: {
diff --git a/src/vault-mcp/search/search-queries.ts b/src/vault-mcp/search/search-queries.ts
index d561ee337..09d8cf526 100644
--- a/src/vault-mcp/search/search-queries.ts
+++ b/src/vault-mcp/search/search-queries.ts
@@ -6,6 +6,7 @@ import { classifyIsoDate } from "../../utils/classify-iso-date.js"
 import { describeError } from "../../utils/describe-error.js"
 import { compareByUtf8Bytes } from "../../utils/compare-utf8-bytes.js"
 import { assertPathHasExtension } from "../../utils/assert-path-has-extension.js"
+import { isCanvasPath } from "../obsidian-markdown/file-kinds.js"
 import { sanitizeFtsQuery, sanitizeFtsQueryAnyTerm } from "./fts-query.js"
 import { computeRrfScores } from "./rrf.js"
 import { sigmoid } from "./reranker.js"
@@ -1467,6 +1468,13 @@ export const searchByProperty = (
 
 // ── Link queries ───────────────────────────────────────────────
 
+/** A link query takes a note, whose ".md" must be lowercase, or a canvas in
+ *  any letter case. */
+const assertLinkQueryPath = (path: string): void => {
+  if (isCanvasPath(path)) return
+  assertPathHasExtension(path, [".md", ".canvas"])
+}
+
 /** Returns notes and files that link TO the given path (incoming links /
  *  backlinks). Canvas file-node references are included — a canvas that
  *  embeds a note via a `file`-type node appears as a backlink source. */
@@ -1475,7 +1483,7 @@ export const getBacklinks = (
   params: { path: string },
   logger: Logger,
 ): BacklinkEntry[] => {
-  assertPathHasExtension(params.path, [".md", ".canvas"])
+  assertLinkQueryPath(params.path)
   const sql = `
     SELECT l.source as path,
            COALESCE(n.title, f.basename) as title,
@@ -1516,7 +1524,7 @@ export const getOutgoingLinks = (
   params: { path: string; dailyNotesFolder?: string | null },
   logger: Logger,
 ): OutgoingLinkEntry[] => {
-  assertPathHasExtension(params.path, [".md", ".canvas"])
+  assertLinkQueryPath(params.path)
   // Left-join against both notes and non_md_files to classify each link target:
   // notes → kind "note", non_md_files → kind "file", neither → broken (defaults to "note").
   const sql = `
diff --git a/src/vault-mcp/vault-operations/__tests__/note-mover.test.ts b/src/vault-mcp/vault-operations/__tests__/note-mover.test.ts
index 1cef3f302..21113552a 100644
--- a/src/vault-mcp/vault-operations/__tests__/note-mover.test.ts
+++ b/src/vault-mcp/vault-operations/__tests__/note-mover.test.ts
@@ -1266,29 +1266,58 @@ describe("moveNote — Canvas sources", () => {
     expect(vi.mocked(logger.warn)).not.toHaveBeenCalled()
   })
 
-  it("treats only a lowercase .canvas extension as a Canvas", async () => {
-    const { writeFixture, moveNote, readNote, logger } = setupVault()
+  it("points the file card of a Canvas with an uppercase extension at the moved note's new path", async () => {
+    const { writeFixture, moveNote, readNote } = setupVault()
+    await writeFixture("Plan.md", "# Plan\n")
+    await writeFixture(
+      "Board.Canvas",
+      obsidianCanvas([
+        '{"id":"f1","type":"file","file":"Plan.md","x":0,"y":0,"width":400,"height":400}',
+      ]),
+    )
+
+    const result = await moveNote({
+      oldPath: "Plan.md",
+      newPath: "Roadmap.md",
+      backlinkSources: ["Board.Canvas"],
+    })
+
+    expect(await readNote("Board.Canvas")).toBe(
+      obsidianCanvas([
+        '{"id":"f1","type":"file","file":"Roadmap.md","x":0,"y":0,"width":400,"height":400}',
+      ]),
+    )
+    expect(result).toEqual({
+      moved_to: "Roadmap.md",
+      links_updated: 1,
+      updated_notes: ["Board.Canvas"],
+      pruned_empty_folders: 0,
+    })
+  })
+
+  it("finds and rewrites a text-card link in a Canvas with an uppercase extension that the index missed", async () => {
+    const { writeFixture, moveNote, readNote } = setupVault()
     await writeFixture("Foo.md", "# Foo\n")
-    const upperCaseCanvas = obsidianCanvas([
-      '{"id":"t1","type":"text","text":"Start from [[Foo]]","x":0,"y":0,"width":250,"height":60}',
-    ])
-    await writeFixture("Board.CANVAS", upperCaseCanvas)
+    await writeFixture(
+      "Board.CANVAS",
+      obsidianCanvas([
+        '{"id":"t1","type":"text","text":"Start from [[Foo]]","x":0,"y":0,"width":250,"height":60}',
+      ]),
+    )
 
     const result = await moveNote({ oldPath: "Foo.md", newPath: "Bar.md" })
 
+    expect(await readNote("Board.CANVAS")).toBe(
+      obsidianCanvas([
+        '{"id":"t1","type":"text","text":"Start from [[Bar]]","x":0,"y":0,"width":250,"height":60}',
+      ]),
+    )
     expect(result).toEqual({
       moved_to: "Bar.md",
-      links_updated: 0,
-      updated_notes: [],
+      links_updated: 1,
+      updated_notes: ["Board.CANVAS"],
       pruned_empty_folders: 0,
     })
-    expect(await readNote("Board.CANVAS")).toBe(upperCaseCanvas)
-    // The scan skips Board.CANVAS and no other file links Foo.md, so the log
-    // must never fire, whatever its context.
-    expect(vi.mocked(logger.info)).not.toHaveBeenCalledWith(
-      "backlink verification discovered sources the index missed",
-      expect.anything(),
-    )
   })
 
   it("aborts without writing when a Canvas backlink source is not valid JSON", async () => {
diff --git a/src/vault-mcp/vault-operations/asset-operations.ts b/src/vault-mcp/vault-operations/asset-operations.ts
index 14a49d24c..94ec860e5 100644
--- a/src/vault-mcp/vault-operations/asset-operations.ts
+++ b/src/vault-mcp/vault-operations/asset-operations.ts
@@ -3,6 +3,7 @@ import { getMeta, renderPageAsImage } from "unpdf"
 import type { PDFDocumentProxy } from "unpdf/pdfjs"
 import { vaultFs } from "./vault-filesystem.js"
 import { linearizeCanvas } from "../obsidian-markdown/canvas.js"
+import { getExtensionsOfKind, getFileKind } from "../obsidian-markdown/file-kinds.js"
 import { pageTextByLines } from "../obsidian-markdown/lines.js"
 import type { LineWindow } from "../obsidian-markdown/lines.js"
 import { extractPdfText } from "../obsidian-markdown/pdf.js"
@@ -34,25 +35,7 @@ import type { Logger } from "../../logger.js"
 
 // ── Reading ─────────────────────────────────────────────────────
 
-/** Extensions dispatched to the image pipeline (model-visible image blocks). */
-const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"])
-
-/** Extensions returned verbatim as text with no NUL byte check, so a
- *  NUL-padded log still reads. .svg is XML source; .base is Obsidian Bases
- *  YAML. */
-const TEXT_PASSTHROUGH_EXTENSIONS = new Set([
-  ".svg",
-  ".json",
-  ".txt",
-  ".csv",
-  ".xml",
-  ".log",
-  ".yaml",
-  ".yml",
-  ".base",
-])
-
-/** Fixed cap on text output (passthrough files, canvas renditions and
+/** Fixed cap on text output (text files, canvas renditions and
  *  PDF-extracted text) so a huge text asset can't blow a client's response
  *  limit. Deliberately not an env var — the image budget is the tunable
  *  surface; text past this size is read in line windows, not raised into a
@@ -191,7 +174,7 @@ const buildUtf8SourceResult = (params: {
         `unsupported file type "${params.extension}": "${path}" exists ` +
           `(${params.bytes} bytes) and holds a NUL byte in its first ` +
           `${NUL_SEARCH_WINDOW_BYTES.toLocaleString("en-US")} bytes (binary data or UTF-16 text). ` +
-          `Readable types: images (${[...IMAGE_EXTENSIONS].join("/")}), .canvas, .pdf, ` +
+          `Readable types: images (${getExtensionsOfKind("image").join("/")}), .canvas, .pdf, ` +
           `and UTF-8 text files`,
       )
     case "invalid-utf8":
@@ -359,13 +342,103 @@ const readPdfPages = async (
   }
 }
 
+type ReadAsset = Readonly<{ buffer: Buffer; bytes: number }>
+
+/** Images have no raw source or line range, because the fitted image block is
+ *  the only form delivered. */
+const readImageAsset = async (params: {
+  asset: ReadAsset
+  path: string
+  raw: boolean | undefined
+  isPagedRead: boolean
+  maxImageOutputBytes: number
+}): Promise<AssetReadResult> => {
+  const { asset, path } = params
+
+  if (params.raw) {
+    throw new Error(
+      `raw source is not available for images: "${path}" is ` +
+        `binary — its image block is the delivered form`,
+    )
+  }
+  if (params.isPagedRead) {
+    throw new Error(
+      `line range is not available for images: "${path}" is ` +
+        `binary — its image block is the delivered form`,
+    )
+  }
+
+  const fitted = await fitImageToByteBudget({
+    buffer: asset.buffer,
+    budgetBytes: params.maxImageOutputBytes,
+  })
+  return { kind: "image", fitted, originalBytes: asset.bytes, path }
+}
+
+/** Reads a PDF as its extracted text, or with `raw` as rendered page images,
+ *  which cannot be paged by line. */
+const readPdfAsset = async (
+  params: {
+    asset: ReadAsset
+    path: string
+    raw: boolean | undefined
+    startLine: number | undefined
+    limit: number | undefined
+    maxPdfRenderPages: number
+    maxImageOutputBytes: number
+  },
+  logger: Logger,
+): Promise<AssetReadResult> => {
+  const { asset, path, raw, startLine, limit } = params
+
+  if (raw && requestsLineWindow({ startLine, limit })) {
+    throw new Error(
+      `line range is not available for rendered PDF pages: ` +
+        `"${path}" delivers page images, not text`,
+    )
+  }
+
+  // Buffer → Uint8Array view: Buffer.buffer may be Node's shared pool,
+  // so byteOffset/byteLength carve out this buffer's portion.
+  const pdfData = new Uint8Array(
+    asset.buffer.buffer,
+    asset.buffer.byteOffset,
+    asset.buffer.byteLength,
+  )
+
+  if (raw) {
+    return readPdfPages(
+      {
+        pdfData,
+        path,
+        bytes: asset.bytes,
+        maxPdfRenderPages: params.maxPdfRenderPages,
+        maxImageOutputBytes: params.maxImageOutputBytes,
+      },
+      logger,
+    )
+  }
+
+  const pdfResult = await readPdfText({ pdfData, path, bytes: asset.bytes })
+
+  if (!pdfResult.text) {
+    throw new Error(
+      `PDF has no extractable text: "${path}" exists ` +
+        `(${asset.bytes} bytes, ${pdfResult.totalPages} pages) but ` +
+        `contains no text content — it may be a scanned document or ` +
+        `image-only PDF`,
+    )
+  }
+  return buildTextResult({ text: pdfResult.text, path, startLine, limit })
+}
+
 /**
  * Reads a non-markdown vault file and returns its most useful representation
  * per type.
  * - `raw` returns a canvas's exact JSON source instead of its rendition, and
  *   a PDF's rendered page images instead of its text.
  * - `startLine`/`limit` page any text rendition as a 1-based line window.
- *   They apply after the rendition is produced (passthrough source, canvas
+ *   They apply after the rendition is produced (a text file's source, canvas
  *   outline or raw JSON, PDF-extracted text), so every path that can hit the
  *   text cap can also be paged.
  * - Throws structured errors for images with `raw`, non-text reads with
@@ -387,97 +460,55 @@ const readAssetContent = async (
   logger: Logger,
 ): Promise<AssetReadResult> => {
   const { path, raw, startLine, limit } = params
-  const isPagedRead = requestsLineWindow({ startLine, limit })
   const asset = await vaultFs.readAsset(
     { vaultPath: params.vaultPath, path, maxBytes: params.maxFileBytes },
     logger,
   )
 
-  // readAsset reports the extension lowercased, as these lookups expect
-  const isImage = IMAGE_EXTENSIONS.has(asset.extension)
-
-  if (isImage && raw) {
-    throw new Error(
-      `raw source is not available for images: "${path}" is ` +
-        `binary — its image block is the delivered form`,
-    )
-  }
-  if (isImage && isPagedRead) {
-    throw new Error(
-      `line range is not available for images: "${path}" is ` +
-        `binary — its image block is the delivered form`,
-    )
-  }
-  if (isImage) {
-    const fitted = await fitImageToByteBudget({
-      buffer: asset.buffer,
-      budgetBytes: params.maxImageOutputBytes,
-    })
-    return { kind: "image", fitted, originalBytes: asset.bytes, path }
-  }
-  if (asset.extension === ".canvas") {
-    const canvasSource = decodeUtf8Strict({ buffer: asset.buffer, path })
-    const text = raw ? canvasSource : linearizeCanvas(canvasSource)
-    return buildTextResult({ text, path, startLine, limit })
-  }
-  if (TEXT_PASSTHROUGH_EXTENSIONS.has(asset.extension)) {
-    const text = decodeUtf8Strict({ buffer: asset.buffer, path })
-    return buildTextResult({ text, path, startLine, limit })
-  }
-  if (asset.extension === ".pdf") {
-    if (raw && isPagedRead) {
-      throw new Error(
-        `line range is not available for rendered PDF pages: ` +
-          `"${path}" delivers page images, not text`,
-      )
+  switch (getFileKind(path)) {
+    case "image":
+      return readImageAsset({
+        asset,
+        path,
+        raw,
+        isPagedRead: requestsLineWindow({ startLine, limit }),
+        maxImageOutputBytes: params.maxImageOutputBytes,
+      })
+    case "canvas": {
+      const canvasSource = decodeUtf8Strict({ buffer: asset.buffer, path })
+      const text = raw ? canvasSource : linearizeCanvas(canvasSource)
+      return buildTextResult({ text, path, startLine, limit })
     }
-
-    // Buffer → Uint8Array view: Buffer.buffer may be Node's shared pool,
-    // so byteOffset/byteLength carve out this buffer's portion.
-    const pdfData = new Uint8Array(
-      asset.buffer.buffer,
-      asset.buffer.byteOffset,
-      asset.buffer.byteLength,
-    )
-
-    if (raw) {
-      return readPdfPages(
+    case "pdf":
+      return readPdfAsset(
         {
-          pdfData,
+          asset,
           path,
-          bytes: asset.bytes,
+          raw,
+          startLine,
+          limit,
           maxPdfRenderPages: params.maxPdfRenderPages,
           maxImageOutputBytes: params.maxImageOutputBytes,
         },
         logger,
       )
+    case "text": {
+      // No NUL byte check here, so a NUL-padded log keeps reading
+      const text = decodeUtf8Strict({ buffer: asset.buffer, path })
+      return buildTextResult({ text, path, startLine, limit })
     }
-
-    const pdfResult = await readPdfText({ pdfData, path, bytes: asset.bytes })
-
-    if (!pdfResult.text) {
-      throw new Error(
-        `PDF has no extractable text: "${path}" exists ` +
-          `(${asset.bytes} bytes, ${pdfResult.totalPages} pages) but ` +
-          `contains no text content — it may be a scanned document or ` +
-          `image-only PDF`,
-      )
-    }
-    return buildTextResult({
-      text: pdfResult.text,
-      path,
-      startLine,
-      limit,
-    })
+    case "html":
+    case "script":
+    case "other":
+      return buildUtf8SourceResult({
+        buffer: asset.buffer,
+        bytes: asset.bytes,
+        extension: asset.extension,
+        path,
+        startLine,
+        limit,
+      })
   }
-  return buildUtf8SourceResult({
-    buffer: asset.buffer,
-    bytes: asset.bytes,
-    extension: asset.extension,
-    path,
-    startLine,
-    limit,
-  })
 }
 
 // ── Browsing ────────────────────────────────────────────────────
diff --git a/src/vault-mcp/vault-operations/note-mover.ts b/src/vault-mcp/vault-operations/note-mover.ts
index b121c274b..7b13604c5 100644
--- a/src/vault-mcp/vault-operations/note-mover.ts
+++ b/src/vault-mcp/vault-operations/note-mover.ts
@@ -47,6 +47,7 @@ import {
   extractCanvasFileLinks,
   rewriteCanvasLinks,
 } from "../obsidian-markdown/canvas.js"
+import { isCanvasPath } from "../obsidian-markdown/file-kinds.js"
 import { withExclusiveMultiFileLock } from "../../utils/file-write-lock.js"
 import { caseFoldPath } from "../../utils/case-fold-path.js"
 import { mapWithConcurrency } from "../../utils/map-with-concurrency.js"
@@ -467,10 +468,6 @@ const rewriteNoteContent = (
   return { content, linksRewritten }
 }
 
-/** Case-sensitive, like the search index: only a lowercase ".canvas"
- *  extension marks a file as a Canvas. */
-const isCanvasPath = (path: string): boolean => posix.extname(path) === ".canvas"
-
 /** True when a file card's path names a note. Obsidian opens a file card by
  *  its exact path, so a card for Plan.pdf opens the PDF even though the
  *  resolver's ".md" fallback would match a note named Plan.pdf.md. */

From 372d4ddf68d6a627b9745586fde6ecdd3077f64e Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 00:09:24 -0500
Subject: [PATCH 03/38] feat(search): extract an HTML page's visible text

extractHtmlVisibleText runs htmlparser2's stackless tokenizer, so
unclosed tags cost no more than closed ones. Hidden elements end only at
a closing tag with their own name, block elements become line breaks,
whitespace collapses, and reading stops once the text reaches the cap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 package-lock.json                             |  91 ++++++++-
 package.json                                  |   1 +
 .../obsidian-markdown/__tests__/html.test.ts  | 121 ++++++++++++
 src/vault-mcp/obsidian-markdown/html.ts       | 175 ++++++++++++++++++
 4 files changed, 387 insertions(+), 1 deletion(-)
 create mode 100644 src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
 create mode 100644 src/vault-mcp/obsidian-markdown/html.ts

diff --git a/package-lock.json b/package-lock.json
index d466e88c9..424b95fef 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -18,6 +18,7 @@
         "express": "5.3.0",
         "express-rate-limit": "8.7.3",
         "gray-matter": "4.0.3",
+        "htmlparser2": "12.0.0",
         "luxon": "3.7.2",
         "pdfjs-dist": "6.5.438",
         "picomatch": "4.0.7",
@@ -5890,6 +5891,73 @@
       "dev": true,
       "license": "BSD-3-Clause"
     },
+    "node_modules/dom-serializer": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-3.1.1.tgz",
+      "integrity": "sha512-4MEa38/QexBob6gFNwu+EGdWvhJ1OKuNwdYY3Y3NyeWDQfnGeDYQUDfIRzWu5B5gsv03so2Uxd28YC6zrsx3Lw==",
+      "license": "MIT",
+      "dependencies": {
+        "domelementtype": "^3.0.0",
+        "domhandler": "^6.0.0",
+        "entities": "^8.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/cheeriojs/dom-serializer?sponsor=1"
+      }
+    },
+    "node_modules/domelementtype": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-3.0.0.tgz",
+      "integrity": "sha512-umCQid3jKbDmVjx8jGaW7uUykm4DEUeyV21hPxNMo2nV955DhUThwqyOIDtreepP31hl84X7G5U9ZfsWvIB3Pg==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fb55"
+        }
+      ],
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/domhandler": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-6.0.1.tgz",
+      "integrity": "sha512-gYzvtM72ZtxQO0T048kd6HWSbbGCNOUwcnfQ01cqIJ4X2IYKFFHZ5mKvrQETcFXxsRObZulDaKmy//R7TPtsBg==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "domelementtype": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/fb55/domhandler?sponsor=1"
+      }
+    },
+    "node_modules/domutils": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/domutils/-/domutils-4.0.2.tgz",
+      "integrity": "sha512-qI4JLRKnSzqFqr7hAlS5xQDusBCjKSEG4t4+7aNrIQMHBcsC2TGEhuyABJdYkgSewL57PNLYEiibY2iPKhKpaA==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "dom-serializer": "^3.0.0",
+        "domelementtype": "^3.0.0",
+        "domhandler": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/fb55/domutils?sponsor=1"
+      }
+    },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
@@ -5930,7 +5998,6 @@
       "version": "8.1.0",
       "resolved": "https://registry.npmjs.org/entities/-/entities-8.1.0.tgz",
       "integrity": "sha512-kxL7msIffSuh9aaFAMD7rxAIuTRMAHMeBtgHW2yUdWw732ZNh4MehkF2gdjvtdmikkaIP9bFDDJOPlsvm7avrA==",
-      "dev": true,
       "license": "BSD-2-Clause",
       "engines": {
         "node": ">=20.19.0"
@@ -6936,6 +7003,28 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/htmlparser2": {
+      "version": "12.0.0",
+      "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-12.0.0.tgz",
+      "integrity": "sha512-Tz7u1i95/g2x2jz81+x0FBVhBhY5aRTvD3tXXdFaljuNdzDLJ8UGNRrTcj2cgQvAg3iW/h77Fz15nLW0L0CrZw==",
+      "funding": [
+        "https://github.com/fb55/htmlparser2?sponsor=1",
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fb55"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "domelementtype": "^3.0.0",
+        "domhandler": "^6.0.0",
+        "domutils": "^4.0.2",
+        "entities": "^8.0.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
     "node_modules/http-errors": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
diff --git a/package.json b/package.json
index 39d792976..9fd75183c 100644
--- a/package.json
+++ b/package.json
@@ -106,6 +106,7 @@
     "express": "5.3.0",
     "express-rate-limit": "8.7.3",
     "gray-matter": "4.0.3",
+    "htmlparser2": "12.0.0",
     "luxon": "3.7.2",
     "pdfjs-dist": "6.5.438",
     "picomatch": "4.0.7",
diff --git a/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts b/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
new file mode 100644
index 000000000..e068de862
--- /dev/null
+++ b/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
@@ -0,0 +1,121 @@
+import { describe, it, expect } from "vitest"
+import { DateTime } from "luxon"
+import { extractHtmlVisibleText } from "../html.js"
+
+const LARGE_CAP = 1_000_000
+
+const extractAll = (html: string): string => extractHtmlVisibleText({ html, maxBytes: LARGE_CAP })
+
+describe("extractHtmlVisibleText", () => {
+  it("returns the visible text of a page, one line per block element", () => {
+    const page =
+      "<!doctype html><html><head><title>Restart runbook</title></head>" +
+      "<body><h1>Restart</h1><p>Stop the <b>service</b> first.</p>" +
+      "<ul><li>Check logs</li><li>Start it</li></ul></body></html>"
+
+    expect(extractAll(page)).toBe(
+      "Restart runbook\nRestart\nStop the service first.\nCheck logs\nStart it",
+    )
+  })
+
+  it("drops the text of script, style, noscript and template elements", () => {
+    const page =
+      "<p>before</p><script>var secret = 1</script><style>p { color: red }</style>" +
+      "<noscript>enable scripts</noscript><template><p>inert</p></template><p>after</p>"
+
+    expect(extractAll(page)).toBe("before\nafter")
+  })
+
+  it("drops the raw text of iframe, noembed and noframes fallback content", () => {
+    const page =
+      "<p>shown</p><iframe><p>iframe fallback</p></iframe>" +
+      "<noembed>embed fallback</noembed><noframes>frames fallback</noframes>"
+
+    expect(extractAll(page)).toBe("shown")
+  })
+
+  it("drops an uppercase SCRIPT element's text", () => {
+    expect(extractAll("<P>shown</P><SCRIPT>hidden()</SCRIPT>")).toBe("shown")
+  })
+
+  it("ignores a stray closing tag for a hidden element that never opened", () => {
+    expect(extractAll("</noscript><p>VISIBLE</p>")).toBe("VISIBLE")
+  })
+
+  it("keeps a hidden element's text hidden through a closing tag with another name", () => {
+    expect(extractAll("<template>SECRET</noscript>LEAKED</template><p>VISIBLE</p>")).toBe("VISIBLE")
+  })
+
+  it("keeps text hidden until the outer element of nested hidden elements closes", () => {
+    expect(extractAll("<template><style>a{}</style>inner</template>outer")).toBe("outer")
+  })
+
+  it("treats a self-closing script tag as open, as HTML does", () => {
+    expect(extractAll('<p>shown</p><script src="app.js"/>hidden()</script><p>after</p>')).toBe(
+      "shown\nafter",
+    )
+  })
+
+  it("hides everything after a template that never closes", () => {
+    expect(extractAll("<p>shown</p><template><p>never shown</p>")).toBe("shown")
+  })
+
+  it("drops comments", () => {
+    expect(extractAll("<p>kept<!-- dropped --> text</p>")).toBe("kept text")
+  })
+
+  it("decodes named and numeric entities", () => {
+    expect(extractAll("<p>A &mdash; B &amp; C &#169; &#x2713;</p>")).toBe("A — B & C © ✓")
+  })
+
+  it("collapses whitespace runs, line breaks and no-break spaces to one space", () => {
+    expect(extractAll("<p>  one \n\t two&nbsp;&nbsp;three  </p>")).toBe("one two three")
+  })
+
+  it("keeps a space between words split across inline tags", () => {
+    expect(extractAll("<p><span>one</span> <span>two</span><em> three</em></p>")).toBe(
+      "one two three",
+    )
+  })
+
+  it("joins words that inline tags split with no whitespace", () => {
+    expect(extractAll("<p>un<b>broken</b></p>")).toBe("unbroken")
+  })
+
+  it("separates table cells with spaces and rows with line breaks", () => {
+    const table =
+      "<table><tr><th>Name</th><th>Port</th></tr><tr><td>api</td><td>8000</td></tr></table>"
+
+    expect(extractAll(table)).toBe("Name Port\napi 8000")
+  })
+
+  it("breaks the line at a br element", () => {
+    expect(extractAll("<p>first<br>second</p>")).toBe("first\nsecond")
+  })
+
+  it("returns an empty string for an empty page", () => {
+    expect(extractAll("")).toBe("")
+  })
+
+  it("returns an empty string for a page with no visible text", () => {
+    expect(extractAll("<html><head><script>x()</script></head><body> </body></html>")).toBe("")
+  })
+
+  it("stops reading once the text reaches maxBytes", () => {
+    const page = Array.from({ length: 50 }, (_, index) => `<p>paragraph ${index}</p>`).join("")
+
+    // "paragraph 0" is 11 bytes, and each later line adds a line break first
+    expect(extractHtmlVisibleText({ html: page, maxBytes: 20 })).toBe("paragraph 0\nparagraph 1")
+  })
+
+  it("extracts 1 MB of unclosed nested tags within a second", () => {
+    const unclosedTags = "<div><span><b>x".repeat(Math.ceil(1_000_000 / 15))
+
+    const startedAt = DateTime.now()
+    const text = extractAll(unclosedTags)
+    const elapsedMs = DateTime.now().diff(startedAt).as("milliseconds")
+
+    expect(text.slice(0, 5)).toBe("x\nx\nx")
+    expect(elapsedMs).toBeLessThan(1_000)
+  })
+})
diff --git a/src/vault-mcp/obsidian-markdown/html.ts b/src/vault-mcp/obsidian-markdown/html.ts
new file mode 100644
index 000000000..66bf24df7
--- /dev/null
+++ b/src/vault-mcp/obsidian-markdown/html.ts
@@ -0,0 +1,175 @@
+import { Tokenizer } from "htmlparser2"
+
+/** Elements whose content a browser does not show on the page.
+ *  - script, style, noscript and template hold code, styling, fallback and
+ *    inert markup.
+ *  - iframe, noembed and noframes hold fallback content that the tokenizer
+ *    reads as raw text, markup included, and that modern browsers never show. */
+const HIDDEN_ELEMENTS: ReadonlySet<string> = new Set([
+  "script",
+  "style",
+  "noscript",
+  "template",
+  "iframe",
+  "noembed",
+  "noframes",
+])
+
+/** Elements that start and end on a line of their own when a page renders. */
+const LINE_BREAKING_ELEMENTS: ReadonlySet<string> = new Set([
+  "address",
+  "article",
+  "aside",
+  "blockquote",
+  "br",
+  "caption",
+  "dd",
+  "details",
+  "dialog",
+  "div",
+  "dl",
+  "dt",
+  "fieldset",
+  "figcaption",
+  "figure",
+  "footer",
+  "form",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "header",
+  "hgroup",
+  "hr",
+  "li",
+  "main",
+  "nav",
+  "ol",
+  "p",
+  "pre",
+  "section",
+  "summary",
+  "table",
+  "title",
+  "tr",
+  "ul",
+])
+
+/** Table cells sit side by side, so a cell boundary separates words. */
+const CELL_ELEMENTS: ReadonlySet<string> = new Set(["td", "th"])
+
+/** Any run of whitespace, the no-break space included. */
+const WHITESPACE_RUN = /\s+/g
+
+/** Attributes, comments, doctypes and the tokenizer's other events hold no
+ *  visible text. */
+const ignoreToken = (): void => {}
+
+/**
+ * The text a browser would show for an HTML page: hidden elements, tags and
+ * comments dropped, entities decoded, one line per block element, and every
+ * other run of whitespace collapsed to one space.
+ * - Reading stops once the text reaches `maxBytes` of UTF-8, so the result can
+ *   run past it by up to one text section; the caller cuts it to size.
+ * - The tokenizer keeps no element stack, so unclosed tags cost no more than
+ *   closed ones and the time stays linear in the page's size.
+ * - A hidden element ends only at a closing tag with its own name, so a stray
+ *   or mismatched closing tag never shows the text inside it.
+ */
+export const extractHtmlVisibleText = (params: { html: string; maxBytes: number }): string => {
+  const { html, maxBytes } = params
+  const textParts: string[] = []
+  const hiddenElementStack: string[] = []
+
+  // Collapsing state threads through every callback in document order, so
+  // these are lets: whether the output sits at a line start, whether a space
+  // is owed before the next word, and the UTF-8 bytes written so far.
+  let atLineStart = true
+  let spaceOwed = false
+  let textBytes = 0
+
+  const emit = (text: string): void => {
+    textParts.push(text)
+    textBytes += Buffer.byteLength(text, "utf8")
+
+    if (textBytes >= maxBytes) tokenizer.pause()
+  }
+
+  const appendText = (text: string): void => {
+    if (hiddenElementStack.length > 0) return
+
+    const collapsedText = text.replace(WHITESPACE_RUN, " ")
+    const words = collapsedText.trim()
+
+    if (!words) {
+      spaceOwed = spaceOwed || collapsedText === " "
+      return
+    }
+    if (!atLineStart && (spaceOwed || collapsedText.startsWith(" "))) emit(" ")
+    emit(words)
+    atLineStart = false
+    spaceOwed = collapsedText.endsWith(" ")
+  }
+
+  const breakLine = (): void => {
+    if (!atLineStart) emit("\n")
+    atLineStart = true
+    spaceOwed = false
+  }
+
+  /** Lowercased, because HTML tag names ignore letter case. */
+  const readTagName = (start: number, end: number): string => html.slice(start, end).toLowerCase()
+
+  const handleTagBoundary = (tagName: string): void => {
+    if (LINE_BREAKING_ELEMENTS.has(tagName)) breakLine()
+    if (CELL_ELEMENTS.has(tagName)) spaceOwed = true
+  }
+
+  const tokenizer = new Tokenizer(
+    {},
+    {
+      ontext: (start, end) => appendText(html.slice(start, end)),
+      ontextentity: (codePoint) => appendText(String.fromCodePoint(codePoint)),
+      // A self-closing <script/> still opens it, because HTML ignores the
+      // slash on an element that is not void, so the name alone decides.
+      onopentagname: (start, end) => {
+        const tagName = readTagName(start, end)
+
+        if (HIDDEN_ELEMENTS.has(tagName)) {
+          hiddenElementStack.push(tagName)
+          return
+        }
+        if (hiddenElementStack.length === 0) handleTagBoundary(tagName)
+      },
+      onclosetag: (start, end) => {
+        const tagName = readTagName(start, end)
+
+        if (hiddenElementStack.length > 0) {
+          if (hiddenElementStack.at(-1) === tagName) hiddenElementStack.pop()
+          return
+        }
+        handleTagBoundary(tagName)
+      },
+      onattribdata: ignoreToken,
+      onattribentity: ignoreToken,
+      onattribend: ignoreToken,
+      onattribname: ignoreToken,
+      oncdata: ignoreToken,
+      oncomment: ignoreToken,
+      ondeclaration: ignoreToken,
+      onend: ignoreToken,
+      onopentagend: ignoreToken,
+      onprocessinginstruction: ignoreToken,
+      onselfclosingtag: ignoreToken,
+    },
+  )
+
+  tokenizer.write(html)
+
+  // A paused tokenizer has stopped reading at the cap, and ending it would
+  // read on through the rest of the page.
+  if (tokenizer.running) tokenizer.end()
+  return textParts.join("").trimEnd()
+}

From 45727f3863d12d1c866e81678bf5ea283b9d895b Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 00:12:02 -0500
Subject: [PATCH 04/38] feat(search): index the visible text of HTML pages

HTML pages are read as bytes and indexed only when they decode as UTF-8
with no early NUL byte, the test vault_read_file applies. Search holds
a page's visible text, capped like other files; a page over 16 MiB is
found by its name only. When a watched page stops reading as text, its
stored content is removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/vault-mcp/search/file-watcher.ts |  45 ++++++++---
 src/vault-mcp/search/search-index.ts | 113 ++++++++++++++++++++++++---
 2 files changed, 139 insertions(+), 19 deletions(-)

diff --git a/src/vault-mcp/search/file-watcher.ts b/src/vault-mcp/search/file-watcher.ts
index a339e1d1a..534366832 100644
--- a/src/vault-mcp/search/file-watcher.ts
+++ b/src/vault-mcp/search/file-watcher.ts
@@ -23,6 +23,7 @@ import { splitPropertiesBlock } from "../obsidian-markdown/frontmatter.js"
 import { extractPdfText } from "../obsidian-markdown/pdf.js"
 import { getFileKind, isCanvasPath } from "../obsidian-markdown/file-kinds.js"
 import type { Logger } from "../../logger.js"
+import { decodeTextBuffer } from "../../utils/decode-text-buffer.js"
 import { describeError, describeErrorForLog } from "../../utils/describe-error.js"
 import { isErrnoException } from "../../utils/is-errno-exception.js"
 import { isMissingPathError, readdirOrNull, realpathOrNull, statOrNull } from "../../utils/fs.js"
@@ -226,7 +227,7 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
     }
 
     // Canvas files are always read — link extraction is unconditional.
-    // PDF and text files are only read when file content FTS is enabled.
+    // PDF, text and HTML files are only read when file content FTS is enabled.
     const fileKind = getFileKind(filePath)
     const isCanvas = fileKind === "canvas"
     const isIndexableNonCanvas =
@@ -234,20 +235,44 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
 
     if (isCanvas || isIndexableNonCanvas) {
       try {
-        const readContentToIndex = async (): Promise<string> => {
-          if (fileKind !== "pdf") return await readFile(filePath, "utf8")
-
-          const buffer = await readFile(filePath)
-          // pdfjs throws on a Node Buffer, so it gets a plain Uint8Array view
-          // over the same bytes.
-          const pdfData = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)
-          const pdfResult = await extractPdfText(pdfData)
-          return pdfResult.text
+        /** The file's text, or null for an HTML page that is not UTF-8 or
+         *  holds a NUL byte early on, which vault_read_file refuses too. */
+        const readContentToIndex = async (): Promise<string | null> => {
+          switch (fileKind) {
+            case "pdf": {
+              const buffer = await readFile(filePath)
+              // pdfjs throws on a Node Buffer, so it gets a plain Uint8Array view
+              // over the same bytes.
+              const pdfData = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)
+              const pdfResult = await extractPdfText(pdfData)
+              return pdfResult.text
+            }
+            case "html": {
+              const decodedSource = decodeTextBuffer(await readFile(filePath))
+
+              if (decodedSource.status !== "text") return null
+              return decodedSource.text
+            }
+            case "canvas":
+            case "text":
+            case "image":
+            case "script":
+            case "other":
+              return await readFile(filePath, "utf8")
+          }
         }
         const contentToIndex = await readContentToIndex()
 
         if (currentEvents.get(relativePath) !== eventToken) return { status: "superseded" }
 
+        // A page that stopped reading as text loses what search held for it,
+        // while its file row above stays
+        if (contentToIndex === null) {
+          search.removeFileContent({ filePath: relativePath }, logger)
+          logger.debug("indexed non-md file without its content", { path: relativePath })
+          return { status: "file-indexed" }
+        }
+
         const sourceVersion = search.upsertFileContent(
           {
             filePath: relativePath,
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index 031eb7337..7299e2013 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -11,6 +11,8 @@ import type { LeadingCallout } from "../obsidian-markdown/callouts.js"
 import { linearizeCanvas, extractCanvasFileLinks } from "../obsidian-markdown/canvas.js"
 import { getFileKind, isCanvasPath } from "../obsidian-markdown/file-kinds.js"
 import type { FileKind } from "../obsidian-markdown/file-kinds.js"
+import { extractHtmlVisibleText } from "../obsidian-markdown/html.js"
+import { decodeTextBuffer } from "../../utils/decode-text-buffer.js"
 import { links } from "../obsidian-markdown/links.js"
 import { splitIntoLines } from "../obsidian-markdown/lines.js"
 import { parseHeadings } from "../obsidian-markdown/headings.js"
@@ -67,12 +69,44 @@ export const PDF_EXTRACTION_CONCURRENCY = 4
 /** File kinds whose content is indexed into file_content_fts when file tools
  *  are on. A canvas is left out because it is read whatever that setting is,
  *  since its file cards are graph links. */
-export const CONTENT_INDEXED_FILE_KINDS: ReadonlySet<FileKind> = new Set(["pdf", "text"])
+export const CONTENT_INDEXED_FILE_KINDS: ReadonlySet<FileKind> = new Set(["pdf", "text", "html"])
 
 /** Cap on rendered content indexed into file_content_fts — prevents
  *  pathological FTS rows from large CSVs or verbose JSONs. */
 const MAX_INDEXED_CONTENT_BYTES = 102_400
 
+/** An HTML page larger than this is indexed by its name only, like a scanned
+ *  PDF. Extracting its text runs on the main thread, and attribute-heavy pages
+ *  at 16 MiB already took up to 1.7 s, close to the 2-second point at which
+ *  this server moves a parser to a worker thread. */
+const MAX_INDEXED_HTML_PAGE_BYTES = 16 * 1024 * 1024
+
+/** The text file_content_fts holds for a file, from the file's own text: a
+ *  canvas's outline, an HTML page's visible text, and every other kind as
+ *  it arrives. */
+const rawContentToIndexedText = (params: {
+  filePath: string
+  rawContent: string
+  fileBytes: number
+}): string => {
+  switch (getFileKind(params.filePath)) {
+    case "canvas":
+      return linearizeCanvas(params.rawContent)
+    case "html":
+      if (params.fileBytes > MAX_INDEXED_HTML_PAGE_BYTES) return ""
+      return extractHtmlVisibleText({
+        html: params.rawContent,
+        maxBytes: MAX_INDEXED_CONTENT_BYTES,
+      })
+    case "image":
+    case "pdf":
+    case "text":
+    case "script":
+    case "other":
+      return params.rawContent
+  }
+}
+
 /** Truncates a string to fit within a UTF-8 byte limit without splitting
  *  multi-byte characters — iterates Unicode code points and accumulates
  *  each code point's UTF-8 byte length, stopping before the cap. */
@@ -1313,6 +1347,7 @@ export const createSearchIndex = (
 
   /** Pass the returned source version to embedFileContent for this upsert.
    *  - Canvas JSON is linearized for FTS and parsed for graph links regardless of fileToolsEnabled.
+   *  - An HTML page arrives as its source and is indexed as its visible text.
    *  - Other files supply rendered text; FTS storage requires fileToolsEnabled and caps UTF-8 bytes. */
   const upsertFileContent = (
     params: {
@@ -1324,10 +1359,11 @@ export const createSearchIndex = (
   ): symbol => {
     const extension = posix.extname(params.filePath)
     const isCanvas = isCanvasPath(params.filePath)
-
-    // A canvas is linearized for FTS, and its raw JSON is read for links.
-    // Every other kind arrives as its rendered text.
-    const contentToIndex = isCanvas ? linearizeCanvas(params.rawContent) : params.rawContent
+    const contentToIndex = rawContentToIndexedText({
+      filePath: params.filePath,
+      rawContent: params.rawContent,
+      fileBytes: params.fileStat.size,
+    })
 
     // Truncate content exceeding the FTS cap — iterates Unicode code points
     // and accumulates UTF-8 byte length so the cap is enforced in bytes
@@ -2317,6 +2353,9 @@ export const createSearchIndex = (
     const textFiles = fileToolsEnabled
       ? allNonMdFiles.filter((file) => getFileKind(file.relativePath) === "text")
       : []
+    const htmlFiles = fileToolsEnabled
+      ? allNonMdFiles.filter((file) => getFileKind(file.relativePath) === "html")
+      : []
 
     const readRebuildFileContent = async (params: {
       file: RebuildFilePaths
@@ -2392,6 +2431,57 @@ export const createSearchIndex = (
     })
     const textFileContents = textFileContentResults.filter((entry) => entry !== null)
 
+    /** Reads an HTML page as bytes and keeps it only when the bytes are UTF-8
+     *  with no NUL byte early on, the test vault_read_file applies, so search
+     *  never holds text that a read refuses. */
+    const readDecodedSourceFile = async (
+      file: RebuildFilePaths,
+    ): Promise<RebuildFileContent | null> => {
+      const readSource = async () => {
+        try {
+          const [buffer, fileStat] = await Promise.all([
+            readFile(file.absolutePath),
+            stat(file.absolutePath),
+          ])
+          return { buffer, fileStat }
+        } catch (error) {
+          logger.warn("skipped unreadable file during rebuild", {
+            path: file.relativePath,
+            error: describeError(error),
+          })
+          return null
+        }
+      }
+      const source = await readSource()
+
+      if (!source) return null
+
+      const decodedSource = decodeTextBuffer(source.buffer)
+
+      switch (decodedSource.status) {
+        case "text":
+          return {
+            relativePath: file.relativePath,
+            content: decodedSource.text,
+            modifiedAtMs: source.fileStat.mtimeMs,
+            sizeBytes: source.fileStat.size,
+          }
+        case "binary":
+        case "invalid-utf8":
+          logger.debug("left a file that is not UTF-8 text out of the index", {
+            path: file.relativePath,
+            decodeStatus: decodedSource.status,
+          })
+          return null
+      }
+    }
+    const htmlContentResults = await mapWithConcurrency({
+      items: htmlFiles,
+      concurrency: INDEXING_FILE_READ_CONCURRENCY,
+      mapper: readDecodedSourceFile,
+    })
+    const htmlContents = htmlContentResults.filter((entry) => entry !== null)
+
     const noteContentResults = await mapWithConcurrency({
       items: markdownFiles,
       concurrency: INDEXING_FILE_READ_CONCURRENCY,
@@ -2529,10 +2619,15 @@ export const createSearchIndex = (
           }
         }
 
-        // File content indexing: canvas (FTS + link extraction), PDF and text
-        // (FTS only). upsertFileContent deletes old canvas links before
-        // inserting, so canvas links append cleanly after the note link pass.
-        const allFileContents = [...canvasContents, ...pdfContents, ...textFileContents]
+        // Canvas content is indexed with its links, and PDF, text and HTML
+        // content for search only. upsertFileContent deletes old canvas links
+        // before inserting, so canvas links append cleanly after the note link pass.
+        const allFileContents = [
+          ...canvasContents,
+          ...pdfContents,
+          ...textFileContents,
+          ...htmlContents,
+        ]
         for (const fileEntry of allFileContents) {
           try {
             const sourceVersion = upsertFileContent(

From 27510f44ab8136b000008418ec2a353aae9dc4e9 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 00:14:15 -0500
Subject: [PATCH 05/38] test(search): cover HTML page indexing through the
 rebuild and the watcher

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../search/__tests__/file-watcher.test.ts     | 89 ++++++++++++++++++
 .../search/__tests__/search-index.test.ts     | 93 +++++++++++++++++++
 2 files changed, 182 insertions(+)

diff --git a/src/vault-mcp/search/__tests__/file-watcher.test.ts b/src/vault-mcp/search/__tests__/file-watcher.test.ts
index 6d6ef662c..f48c8a020 100644
--- a/src/vault-mcp/search/__tests__/file-watcher.test.ts
+++ b/src/vault-mcp/search/__tests__/file-watcher.test.ts
@@ -1553,6 +1553,95 @@ describe("file watcher — obsolete events and embedding queues", () => {
     },
   )
 
+  it.each([{ fileName: "page.html" }, { fileName: "page.htm" }])(
+    "indexes the visible text of $fileName and replaces it when the page changes",
+    async ({ fileName }) => {
+      const { testVault, search, fire } = await createControlledWatcher()
+      const searchPaths = async (query: string) => {
+        const { results } = await search.hybridSearch({ query }, logger)
+        return results.map((result) => result.path)
+      }
+
+      await writeFile(
+        join(testVault, fileName),
+        "<p>oldquartz</p><script>scriptonlyword()</script>",
+        "utf8",
+      )
+      await fire("add", fileName)
+
+      expect(await searchPaths("oldquartz")).toEqual([fileName])
+      expect(await searchPaths("scriptonlyword")).toEqual([])
+
+      await writeFile(join(testVault, fileName), "<p>newopal</p>", "utf8")
+      await fire("change", fileName)
+
+      expect(await searchPaths("newopal")).toEqual([fileName])
+      expect(await searchPaths("oldquartz")).toEqual([])
+    },
+  )
+
+  it("leaves a page that is not UTF-8 out of search", async () => {
+    const { testVault, database, fire } = await createControlledWatcher()
+    // 0xE9 is "é" in Latin-1 and never a complete UTF-8 sequence
+    const latin1Page = Buffer.concat([
+      Buffer.from("<p>caf"),
+      Buffer.from([0xe9]),
+      Buffer.from(" latinword</p>"),
+    ])
+    await writeFile(join(testVault, "latin1.html"), latin1Page)
+
+    await fire("add", "latin1.html")
+
+    expect(database.prepare("SELECT path FROM file_content").all()).toEqual([])
+    expect(database.prepare("SELECT path FROM non_md_files").all()).toEqual([
+      { path: "latin1.html" },
+    ])
+  })
+
+  it("drops a page from search while it holds a NUL byte, and a held embedding cannot restore it", async () => {
+    const firstEntered = Promise.withResolvers<undefined>()
+    const releaseFirst = Promise.withResolvers<Float32Array>()
+    const vector = new Float32Array(384).fill(0.1)
+    const embedder = {
+      embedText: vi.fn(async (text: string) => {
+        if (text === "page\n\nfirstgarnet") {
+          firstEntered.resolve(undefined)
+          return releaseFirst.promise
+        }
+        return vector
+      }),
+      embedBatch: vi.fn(async (texts: readonly string[]) => texts.map(() => vector)),
+    }
+    const { testVault, database, search, fire } = await createControlledWatcher(embedder)
+    const pagePath = join(testVault, "page.html")
+    const storedContent = () => database.prepare("SELECT path, content FROM file_content").all()
+    const storedChunks = () => database.prepare("SELECT file_path FROM file_content_chunks").all()
+
+    await writeFile(pagePath, "<p>firstgarnet</p>", "utf8")
+    const firstChange = fire("change", "page.html")
+    await firstEntered.promise
+    expect(storedContent()).toEqual([{ path: "page.html", content: "firstgarnet" }])
+
+    const withNulByte = Buffer.concat([
+      Buffer.from("<p>nulgarnet"),
+      Buffer.from([0]),
+      Buffer.from("</p>"),
+    ])
+    await writeFile(pagePath, withNulByte)
+    await fire("change", "page.html")
+    expect(storedContent()).toEqual([])
+
+    releaseFirst.resolve(vector)
+    await firstChange
+    await vi.waitFor(() => expect(embedder.embedText).toHaveBeenCalledTimes(1))
+    expect(storedChunks()).toEqual([])
+    expect(search.fullTextSearch({ query: "firstgarnet" }, logger)).toEqual([])
+
+    await writeFile(pagePath, "<p>secondgarnet</p>", "utf8")
+    await fire("change", "page.html")
+    expect(storedContent()).toEqual([{ path: "page.html", content: "secondgarnet" }])
+  })
+
   it("reports a detached file embedding failure and runs its queued replacement", async () => {
     const failingEntered = Promise.withResolvers<undefined>()
     const releaseFailure = Promise.withResolvers<Float32Array>()
diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index 550741ce7..7822ac351 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -7946,6 +7946,99 @@ describe("files with an uppercase extension", { timeout: 15_000 }, () => {
   })
 })
 
+describe("HTML pages", () => {
+  /** Rebuilds an index over a vault holding the given files. */
+  const rebuildVaultOf = async (
+    files: ReadonlyArray<{ path: string; content: string | Buffer }>,
+  ): Promise<SearchIndex> => {
+    const vaultDir = await mkdtemp(join(tmpdir(), "html-pages-"))
+    onTestFinished(() => rm(vaultDir, { recursive: true }))
+    for (const file of files) {
+      await writeFile(join(vaultDir, file.path), file.content)
+    }
+
+    const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
+      fileToolsEnabled: true,
+    })
+    await fileIndex.rebuildFromVault(
+      { vaultPath: vaultDir, bodyTagParser: inProcessBodyTagParser },
+      logger,
+    )
+    return fileIndex
+  }
+
+  /** The paths each query finds, in query order. */
+  const searchEach = async (
+    search: SearchIndex,
+    queries: readonly string[],
+  ): Promise<string[][]> => {
+    const findPaths = async (query: string): Promise<string[]> => {
+      const { results } = await search.hybridSearch({ query }, logger)
+      return results.map((result) => result.path)
+    }
+    return Promise.all(queries.map(findPaths))
+  }
+
+  it("finds an .html or .htm page by its visible text, never by its script", async () => {
+    const fileIndex = await rebuildVaultOf([
+      { path: "runbook.html", content: "<p>visiblequartz</p><script>scriptquartz()</script>" },
+      { path: "report.htm", content: "<p>visibleopal</p><script>scriptopal()</script>" },
+    ])
+
+    const queries = ["visiblequartz", "scriptquartz", "visibleopal", "scriptopal"]
+    expect(await searchEach(fileIndex, queries)).toEqual([["runbook.html"], [], ["report.htm"], []])
+  })
+
+  it("indexes a page's last paragraph when its markup passes the 100 KiB cap but its text does not", async () => {
+    // About 140 KB of markup around about 2 KB of text
+    const styledWords = '<span style="color: red; font-weight: bold; padding: 2px">a</span>'.repeat(
+      2_000,
+    )
+    const fileIndex = await rebuildVaultOf([
+      { path: "styled.html", content: `<p>${styledWords}</p><p>closingamber</p>` },
+    ])
+
+    expect(await searchEach(fileIndex, ["closingamber"])).toEqual([["styled.html"]])
+  })
+
+  it("finds a page over 16 MiB by its name and not by its text", async () => {
+    const filler = "<p>filler</p>".repeat(Math.ceil((16 * 1024 * 1024) / 13) + 1)
+    const fileIndex = await rebuildVaultOf([
+      { path: "giganticpage.html", content: `<p>buriedcobalt</p>${filler}` },
+    ])
+
+    expect(await searchEach(fileIndex, ["giganticpage", "buriedcobalt"])).toEqual([
+      ["giganticpage.html"],
+      [],
+    ])
+  })
+
+  it("leaves out a page that is not UTF-8 or holds a NUL byte, and keeps the rest", async () => {
+    const fileIndex = await rebuildVaultOf([
+      {
+        path: "latin1.html",
+        // 0xE9 is "é" in Latin-1 and never a complete UTF-8 sequence
+        content: Buffer.concat([
+          Buffer.from("<p>latinword caf"),
+          Buffer.from([0xe9]),
+          Buffer.from("</p>"),
+        ]),
+      },
+      {
+        path: "nul.html",
+        content: Buffer.concat([Buffer.from("<p>nulword"), Buffer.from([0]), Buffer.from("</p>")]),
+      },
+      { path: "plain.html", content: "<p>plainword</p>" },
+    ])
+
+    expect(await searchEach(fileIndex, ["latinword", "nulword", "plainword"])).toEqual([
+      [],
+      [],
+      ["plain.html"],
+    ])
+  })
+})
+
 describe("committed embedding source versions", () => {
   it.each(["note", "file"] as const)(
     "rejects a %s model result after source deletion",

From a5bfbf0140005af0694b2f4df45b0345f2210721 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 00:17:28 -0500
Subject: [PATCH 06/38] feat(search): find scripts by keyword, never embedding
 them

.py, .sh and .ps1 files are indexed for keyword search through the same
UTF-8 test as HTML pages. Embedding skips them before their text loads,
because the markdown chunker reads their comment lines as headings. The
startup embedding pass now loads each file's text only when it reaches
that file, instead of holding every file's text at once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../search/__tests__/search-index.test.ts     |   4 +-
 src/vault-mcp/search/file-watcher.ts          |  12 +-
 src/vault-mcp/search/search-index.ts          | 106 +++++++++---------
 3 files changed, 58 insertions(+), 64 deletions(-)

diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index 7822ac351..b24e9631f 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -7040,8 +7040,8 @@ Shared datefilter content for mtime boundary tests.
 // ── File content indexing constants ──────────────────────────
 
 describe("CONTENT_INDEXED_FILE_KINDS", () => {
-  it("indexes the content of PDF and text files", () => {
-    expect([...CONTENT_INDEXED_FILE_KINDS].toSorted()).toEqual(["pdf", "text"])
+  it("indexes the content of PDF, text and HTML files and scripts", () => {
+    expect([...CONTENT_INDEXED_FILE_KINDS].toSorted()).toEqual(["html", "pdf", "script", "text"])
   })
 })
 
diff --git a/src/vault-mcp/search/file-watcher.ts b/src/vault-mcp/search/file-watcher.ts
index 534366832..be09ba768 100644
--- a/src/vault-mcp/search/file-watcher.ts
+++ b/src/vault-mcp/search/file-watcher.ts
@@ -227,7 +227,7 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
     }
 
     // Canvas files are always read — link extraction is unconditional.
-    // PDF, text and HTML files are only read when file content FTS is enabled.
+    // PDF, text, HTML and script files are only read when file content FTS is enabled.
     const fileKind = getFileKind(filePath)
     const isCanvas = fileKind === "canvas"
     const isIndexableNonCanvas =
@@ -235,8 +235,8 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
 
     if (isCanvas || isIndexableNonCanvas) {
       try {
-        /** The file's text, or null for an HTML page that is not UTF-8 or
-         *  holds a NUL byte early on, which vault_read_file refuses too. */
+        /** The file's text, or null for an HTML page or script that is not
+         *  UTF-8 or holds a NUL byte early on, which vault_read_file refuses too. */
         const readContentToIndex = async (): Promise<string | null> => {
           switch (fileKind) {
             case "pdf": {
@@ -247,7 +247,8 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
               const pdfResult = await extractPdfText(pdfData)
               return pdfResult.text
             }
-            case "html": {
+            case "html":
+            case "script": {
               const decodedSource = decodeTextBuffer(await readFile(filePath))
 
               if (decodedSource.status !== "text") return null
@@ -256,7 +257,6 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
             case "canvas":
             case "text":
             case "image":
-            case "script":
             case "other":
               return await readFile(filePath, "utf8")
           }
@@ -265,7 +265,7 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
 
         if (currentEvents.get(relativePath) !== eventToken) return { status: "superseded" }
 
-        // A page that stopped reading as text loses what search held for it,
+        // A file that stopped reading as text loses what search held for it,
         // while its file row above stays
         if (contentToIndex === null) {
           search.removeFileContent({ filePath: relativePath }, logger)
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index 7299e2013..8a681d91b 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -69,7 +69,17 @@ export const PDF_EXTRACTION_CONCURRENCY = 4
 /** File kinds whose content is indexed into file_content_fts when file tools
  *  are on. A canvas is left out because it is read whatever that setting is,
  *  since its file cards are graph links. */
-export const CONTENT_INDEXED_FILE_KINDS: ReadonlySet<FileKind> = new Set(["pdf", "text", "html"])
+export const CONTENT_INDEXED_FILE_KINDS: ReadonlySet<FileKind> = new Set([
+  "pdf",
+  "text",
+  "html",
+  "script",
+])
+
+/** File kinds whose indexed text is also embedded for semantic search. A
+ *  script is found by keyword only, because the markdown chunker reads its
+ *  "# comment" lines as headings and turns snake_case names into one word. */
+const EMBEDDED_FILE_KINDS: ReadonlySet<FileKind> = new Set(["canvas", "pdf", "text", "html"])
 
 /** Cap on rendered content indexed into file_content_fts — prevents
  *  pathological FTS rows from large CSVs or verbose JSONs. */
@@ -1060,11 +1070,6 @@ export const createSearchIndex = (
   const selectAllNoteChunkPathsStmt = embedder
     ? db.prepare<[], { note_path: string }>("SELECT DISTINCT note_path FROM note_chunks")
     : null
-  const selectAllFileContentForEmbeddingStmt = fileContentVectorEnabled
-    ? db.prepare<[], { path: string; title: string; content: string }>(
-        "SELECT path, title, content FROM file_content",
-      )
-    : null
   const selectAllFileContentPathsStmt = fileContentVectorEnabled
     ? db.prepare<[], { path: string }>("SELECT path FROM file_content")
     : null
@@ -2035,14 +2040,16 @@ export const createSearchIndex = (
     }
   }
 
-  /** The return counts changed chunks committed before completion or obsolescence.
-   *  Zero covers disabled, cached and obsolete calls. */
+  /** Embeds a file's indexed text from file_content. The return counts changed
+   *  chunks committed before completion or obsolescence. Zero covers disabled,
+   *  unembedded-kind, cached and obsolete calls. */
   const embedAndStoreFileChunks = async (
-    params: { filePath: string; title: string; content: string; sourceVersion: symbol },
+    params: { filePath: string; sourceVersion: symbol },
     logger: Logger,
   ): Promise<number> => {
     if (
       !embedder ||
+      !selectFileContentForEmbeddingStmt ||
       !upsertFileChunkStmt ||
       !selectFileChunkHashesStmt ||
       !selectFileChunkIdStmt ||
@@ -2053,6 +2060,8 @@ export const createSearchIndex = (
       return 0
     }
 
+    // Checked before the content loads, so a script's text is never read for embedding
+    if (!EMBEDDED_FILE_KINDS.has(getFileKind(params.filePath))) return 0
     if (
       !isCurrentSourceVersion(
         { sourcePath: params.filePath, sourceVersion: params.sourceVersion },
@@ -2061,11 +2070,15 @@ export const createSearchIndex = (
     )
       return 0
 
+    const fileContentRow = selectFileContentForEmbeddingStmt.get(params.filePath)
+
+    if (!fileContentRow) return 0
+
     // chunkContent handles file content too — sourcePath extracts folder
     // segments for the TOC chunk's disambiguation line.
     const chunks = chunkContent({
-      noteTitle: params.title,
-      bodyContent: params.content,
+      noteTitle: fileContentRow.title,
+      bodyContent: fileContentRow.content,
       sourcePath: params.filePath,
     })
 
@@ -2156,32 +2169,13 @@ export const createSearchIndex = (
   /** Embed a file's rendered content into vector storage. Reads the processed
    *  content from the file_content table (already linearized/truncated by
    *  upsertFileContent). No-op when the embedding pipeline or file tools are
-   *  disabled, or the file is not in the FTS index. Safe to call unconditionally. */
+   *  disabled, the file is a script, or the file is not in the FTS index.
+   *  Safe to call unconditionally. */
   const embedFileContent = async (
     params: { filePath: string; sourceVersion: symbol },
     logger: Logger,
   ): Promise<void> => {
-    if (!embedder || !selectFileContentForEmbeddingStmt) return
-    if (
-      !isCurrentSourceVersion(
-        { sourcePath: params.filePath, sourceVersion: params.sourceVersion },
-        logger,
-      )
-    )
-      return
-
-    const fileContentRow = selectFileContentForEmbeddingStmt.get(params.filePath)
-
-    if (!fileContentRow) return
-    await embedAndStoreFileChunks(
-      {
-        filePath: params.filePath,
-        sourceVersion: params.sourceVersion,
-        title: fileContentRow.title,
-        content: fileContentRow.content,
-      },
-      logger,
-    )
+    await embedAndStoreFileChunks(params, logger)
   }
 
   /** Removes a note from the notes table, FTS index, links, tasks, vectors,
@@ -2353,8 +2347,11 @@ export const createSearchIndex = (
     const textFiles = fileToolsEnabled
       ? allNonMdFiles.filter((file) => getFileKind(file.relativePath) === "text")
       : []
-    const htmlFiles = fileToolsEnabled
-      ? allNonMdFiles.filter((file) => getFileKind(file.relativePath) === "html")
+    const sourceFiles = fileToolsEnabled
+      ? allNonMdFiles.filter((file) => {
+          const fileKind = getFileKind(file.relativePath)
+          return fileKind === "html" || fileKind === "script"
+        })
       : []
 
     const readRebuildFileContent = async (params: {
@@ -2431,9 +2428,9 @@ export const createSearchIndex = (
     })
     const textFileContents = textFileContentResults.filter((entry) => entry !== null)
 
-    /** Reads an HTML page as bytes and keeps it only when the bytes are UTF-8
-     *  with no NUL byte early on, the test vault_read_file applies, so search
-     *  never holds text that a read refuses. */
+    /** Reads an HTML page or script as bytes and keeps it only when the bytes
+     *  are UTF-8 with no NUL byte early on, the test vault_read_file applies,
+     *  so search never holds text that a read refuses. */
     const readDecodedSourceFile = async (
       file: RebuildFilePaths,
     ): Promise<RebuildFileContent | null> => {
@@ -2475,12 +2472,12 @@ export const createSearchIndex = (
           return null
       }
     }
-    const htmlContentResults = await mapWithConcurrency({
-      items: htmlFiles,
+    const sourceContentResults = await mapWithConcurrency({
+      items: sourceFiles,
       concurrency: INDEXING_FILE_READ_CONCURRENCY,
       mapper: readDecodedSourceFile,
     })
-    const htmlContents = htmlContentResults.filter((entry) => entry !== null)
+    const sourceContents = sourceContentResults.filter((entry) => entry !== null)
 
     const noteContentResults = await mapWithConcurrency({
       items: markdownFiles,
@@ -2619,14 +2616,14 @@ export const createSearchIndex = (
           }
         }
 
-        // Canvas content is indexed with its links, and PDF, text and HTML
-        // content for search only. upsertFileContent deletes old canvas links
-        // before inserting, so canvas links append cleanly after the note link pass.
+        // Canvas content is indexed with its links, and PDF, text, HTML and
+        // script content for search only. upsertFileContent deletes old canvas
+        // links before inserting, so canvas links append cleanly after the note link pass.
         const allFileContents = [
           ...canvasContents,
           ...pdfContents,
           ...textFileContents,
-          ...htmlContents,
+          ...sourceContents,
         ]
         for (const fileEntry of allFileContents) {
           try {
@@ -2668,15 +2665,17 @@ export const createSearchIndex = (
       ...(skippedNotePaths.size > 0 ? { skipped: skippedNotePaths.size } : {}),
     })
 
-    // File content for embedding — read the processed text from file_content
-    // (already linearized/extracted/truncated by upsertFileContent above).
-    const withFileSourceVersion = (file: { path: string; title: string; content: string }) => {
+    // Files of an embedded kind whose text this rebuild indexed. Each file's
+    // text loads from file_content only when the embedding pass reaches it,
+    // so the pass holds one file's text at a time.
+    const withFileSourceVersion = (file: { path: string }) => {
       const sourceVersion = fileVersionsForEmbedding.get(file.path)
+      const isEmbeddedKind = EMBEDDED_FILE_KINDS.has(getFileKind(file.path))
 
-      return sourceVersion ? [{ ...file, sourceVersion }] : []
+      return sourceVersion && isEmbeddedKind ? [{ path: file.path, sourceVersion }] : []
     }
     const filesForEmbedding =
-      selectAllFileContentForEmbeddingStmt?.all().flatMap(withFileSourceVersion) ?? []
+      selectAllFileContentPathsStmt?.all().flatMap(withFileSourceVersion) ?? []
     // Every note read from disk, including notes that failed to index, unlike indexedNotes
     const readableNotePaths = new Set(noteContents.map((note) => note.relativePath))
 
@@ -2804,12 +2803,7 @@ export const createSearchIndex = (
 
                 try {
                   fileChunksEmbedded += await embedAndStoreFileChunks(
-                    {
-                      filePath: file.path,
-                      sourceVersion: file.sourceVersion,
-                      title: file.title,
-                      content: file.content,
-                    },
+                    { filePath: file.path, sourceVersion: file.sourceVersion },
                     logger,
                   )
                 } catch (err) {

From 5712fba31669a4d042e6c85b5649446b22f54dbe Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 00:19:26 -0500
Subject: [PATCH 07/38] test(search): cover script indexing through the rebuild
 and the watcher

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../search/__tests__/file-watcher.test.ts     |  52 ++++++++
 .../search/__tests__/search-index.test.ts     | 115 ++++++++++++++++++
 2 files changed, 167 insertions(+)

diff --git a/src/vault-mcp/search/__tests__/file-watcher.test.ts b/src/vault-mcp/search/__tests__/file-watcher.test.ts
index f48c8a020..a69639f69 100644
--- a/src/vault-mcp/search/__tests__/file-watcher.test.ts
+++ b/src/vault-mcp/search/__tests__/file-watcher.test.ts
@@ -1598,6 +1598,58 @@ describe("file watcher — obsolete events and embedding queues", () => {
     ])
   })
 
+  it("finds a script by keyword through an add, a change and a delete, never embedding it", async () => {
+    const vector = new Float32Array(384).fill(0.1)
+    const embedder = {
+      embedText: vi.fn().mockResolvedValue(vector),
+      embedBatch: vi.fn(async (texts: readonly string[]) => texts.map(() => vector)),
+    }
+    const { testVault, database, search, fire } = await createControlledWatcher(embedder)
+    const settledEmbeds: string[] = []
+    const realFileEmbed = search.embedFileContent
+    vi.spyOn(search, "embedFileContent").mockImplementation(async (params, requestLogger) => {
+      await realFileEmbed(params, requestLogger)
+      settledEmbeds.push(params.filePath)
+    })
+    const keywordPaths = (phrase: string): string[] => {
+      return database
+        .prepare<[string], { path: string }>(
+          "SELECT path FROM file_content_fts WHERE file_content_fts MATCH ? ORDER BY path",
+        )
+        .all(`"${phrase}"`)
+        .map((row) => row.path)
+    }
+    const storedChunkPaths = () => {
+      return database.prepare("SELECT DISTINCT file_path FROM file_content_chunks").all()
+    }
+
+    await writeFile(join(testVault, "report.py"), "def get_user_name():\n    pass\n", "utf8")
+    await writeFile(join(testVault, "control.txt"), "plain text control\n", "utf8")
+    await fire("add", "report.py")
+    await fire("add", "control.txt")
+    await vi.waitFor(() => expect(settledEmbeds.toSorted()).toEqual(["control.txt", "report.py"]))
+
+    expect(keywordPaths("get user name")).toEqual(["report.py"])
+    expect(storedChunkPaths()).toEqual([{ file_path: "control.txt" }])
+
+    await writeFile(join(testVault, "report.py"), "def get_order_total():\n    pass\n", "utf8")
+    await fire("change", "report.py")
+    await vi.waitFor(() => expect(settledEmbeds).toHaveLength(3))
+
+    expect(keywordPaths("get order total")).toEqual(["report.py"])
+    expect(keywordPaths("get user name")).toEqual([])
+    expect(storedChunkPaths()).toEqual([{ file_path: "control.txt" }])
+
+    await unlink(join(testVault, "report.py"))
+    await fire("unlink", "report.py")
+
+    expect(keywordPaths("get order total")).toEqual([])
+    expect(database.prepare("SELECT path FROM file_content").all()).toEqual([
+      { path: "control.txt" },
+    ])
+    expect(embedder.embedText).toHaveBeenCalledExactlyOnceWith("control\n\nplain text control")
+  })
+
   it("drops a page from search while it holds a NUL byte, and a held embedding cannot restore it", async () => {
     const firstEntered = Promise.withResolvers<undefined>()
     const releaseFirst = Promise.withResolvers<Float32Array>()
diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index b24e9631f..95c025814 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -8039,6 +8039,121 @@ describe("HTML pages", () => {
   })
 })
 
+describe("scripts", () => {
+  const SCRIPT_FILES = [
+    { path: "report.py", content: "def get_user_name():\n    return 'jade'\n" },
+    { path: "deploy.sh", content: "#!/bin/sh\n# restart_service_now\nsystemctl restart api\n" },
+    { path: "Backup.ps1", content: "# copy_backup_files\nCopy-Item -Path $Source\n" },
+  ]
+
+  /** Writes the files into a new vault and rebuilds an index over it. */
+  const rebuildVaultOf = async (params: {
+    files: ReadonlyArray<{ path: string; content: string | Buffer }>
+    embedder?: Parameters<typeof createSearchIndex>[1]
+  }) => {
+    const dir = await mkdtemp(join(tmpdir(), "script-index-"))
+    onTestFinished(() => rm(dir, { recursive: true, force: true }))
+    const vaultPath = join(dir, "vault")
+    await mkdir(vaultPath)
+    for (const file of params.files) {
+      await writeFile(join(vaultPath, file.path), file.content)
+    }
+
+    const databasePath = join(dir, "index.db")
+    const fileIndex = createSearchIndex(databasePath, params.embedder, undefined, {
+      fileToolsEnabled: true,
+    })
+    const rebuilt = await fileIndex.rebuildFromVault(
+      { vaultPath, bodyTagParser: inProcessBodyTagParser },
+      logger,
+    )
+    await rebuilt.embedding
+
+    const database = new Database(databasePath, { readonly: true })
+    sqliteVec.load(database)
+    onTestFinished(() => {
+      database.close()
+    })
+    return { fileIndex, database }
+  }
+
+  /** The paths whose indexed text matches the phrase, by keyword alone. */
+  const keywordPaths = (database: Database.Database, phrase: string): string[] => {
+    return database
+      .prepare<[string], { path: string }>(
+        "SELECT path FROM file_content_fts WHERE file_content_fts MATCH ? ORDER BY path",
+      )
+      .all(`"${phrase}"`)
+      .map((row) => row.path)
+  }
+
+  it("finds .py, .sh and .ps1 scripts by keyword after a rebuild with embedding off", async () => {
+    const { fileIndex } = await rebuildVaultOf({ files: SCRIPT_FILES })
+    const queries = ["get_user_name", "restart_service_now", "copy_backup_files"]
+
+    const searchFor = async (query: string) => {
+      const { results } = await fileIndex.hybridSearch({ query }, logger)
+      return results.map((result) => result.path)
+    }
+
+    expect(await Promise.all(queries.map(searchFor))).toEqual([
+      ["report.py"],
+      ["deploy.sh"],
+      ["Backup.ps1"],
+    ])
+  })
+
+  it("embeds a text file but no script after a rebuild with embedding on, while both stay found by keyword", async () => {
+    const vector = new Float32Array(384).fill(0.1)
+    const embedder = {
+      embedText: vi.fn().mockResolvedValue(vector),
+      embedBatch: vi.fn(async (texts: readonly string[]) => texts.map(() => vector)),
+    }
+    const { database } = await rebuildVaultOf({
+      files: [...SCRIPT_FILES, { path: "notes.txt", content: "plain text control\n" }],
+      embedder,
+    })
+
+    const phrases = [
+      "get user name",
+      "restart service now",
+      "copy backup files",
+      "plain text control",
+    ]
+    const findByKeyword = (phrase: string) => keywordPaths(database, phrase)
+
+    expect(phrases.map(findByKeyword)).toEqual([
+      ["report.py"],
+      ["deploy.sh"],
+      ["Backup.ps1"],
+      ["notes.txt"],
+    ])
+    expect(database.prepare("SELECT file_path, chunk_text FROM file_content_chunks").all()).toEqual(
+      [{ file_path: "notes.txt", chunk_text: "notes\n\nplain text control" }],
+    )
+    expect(database.prepare("SELECT COUNT(*) AS count FROM file_content_vectors").get()).toEqual({
+      count: 1,
+    })
+    expect(embedder.embedText).toHaveBeenCalledExactlyOnceWith("notes\n\nplain text control")
+  })
+
+  it("leaves a script holding a NUL byte out of search", async () => {
+    const { database } = await rebuildVaultOf({
+      files: [
+        {
+          path: "binary.py",
+          content: Buffer.concat([Buffer.from("nulscriptword = 1\n"), Buffer.from([0])]),
+        },
+        { path: "plain.py", content: "plainscriptword = 1\n" },
+      ],
+    })
+
+    expect(database.prepare("SELECT path FROM file_content ORDER BY path").all()).toEqual([
+      { path: "plain.py" },
+    ])
+  })
+})
+
 describe("committed embedding source versions", () => {
   it.each(["note", "file"] as const)(
     "rejects a %s model result after source deletion",

From 0e2288d06a5c3ac232c327e886edb2b04aea0522 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 00:36:14 -0500
Subject: [PATCH 08/38] docs: describe HTML page and script reads and search

README's Files section, ARCHITECTURE's read dispatch and file-content
index, SECURITY's read scope, the SYNC_FILE_TYPES wording on every
surface, and the DeepWiki module lists now cover any-UTF-8 reads, HTML
visible text and keyword-only scripts. DOCKERHUB.md leaves the README's
Files section out, as it does Memory and Tasks, to stay under Docker
Hub's 25,000-byte cap; its feature list still links there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .devin/wiki.json                     |  4 +-
 .env.example                         |  4 +-
 ARCHITECTURE.md                      | 28 +++++++++++---
 CONTRIBUTING.md                      | 40 +++++++++----------
 DEPLOY.md                            | 56 +++++++++++++--------------
 DOCKERHUB.md                         | 18 +--------
 README.md                            |  5 ++-
 SECURITY.md                          |  9 ++++-
 cli/src/env.ts                       |  7 ++--
 deploy/railway/README.md             | 58 ++++++++++++++--------------
 deploy/remote/.env.example           |  7 ++--
 deploy/remote/README.md              | 44 ++++++++++-----------
 deploy/render/README.md              | 40 +++++++++----------
 scripts/generate-dockerhub-readme.ts |  1 +
 14 files changed, 165 insertions(+), 156 deletions(-)

diff --git a/.devin/wiki.json b/.devin/wiki.json
index c0619dd64..2549eb9b4 100644
--- a/.devin/wiki.json
+++ b/.devin/wiki.json
@@ -40,7 +40,7 @@
     },
     {
       "title": "Obsidian Markdown Parsing",
-      "purpose": "The pure parser layer in obsidian-markdown/ — no filesystem I/O: links.ts, lines.ts, frontmatter.ts, tags.ts, body-tags.ts with obsidian-remark-parser.ts and remark-ports/ (body tags on remark-parse 8, the parser Obsidian forked), callouts.ts, headings.ts, tasks.ts, recurrence.ts, memory-entries.ts, canvas.ts, plaintext.ts, pdf.ts, pdf-engine.ts, moment-format.ts. This layer encodes the Obsidian-parity behavior (every link form and 'New link format' mode Obsidian recognizes; both Tasks-plugin formats) that distinguishes Vault Cortex from simpler file-based integrations.",
+      "purpose": "The pure parser layer in obsidian-markdown/ — no filesystem I/O: links.ts, lines.ts, frontmatter.ts, tags.ts, body-tags.ts with obsidian-remark-parser.ts and remark-ports/ (body tags on remark-parse 8, the parser Obsidian forked), callouts.ts, headings.ts, tasks.ts, recurrence.ts, memory-entries.ts, canvas.ts, file-kinds.ts, html.ts, plaintext.ts, pdf.ts, pdf-engine.ts, moment-format.ts. This layer encodes the Obsidian-parity behavior (every link form and 'New link format' mode Obsidian recognizes; both Tasks-plugin formats) that distinguishes Vault Cortex from simpler file-based integrations.",
       "parent": "Architecture"
     },
     {
@@ -65,7 +65,7 @@
     },
     {
       "title": "Non-Markdown Files",
-      "purpose": "How non-markdown vault files (images, PDFs, canvases, text and data files) are read, browsed, and searched. Modules: asset-operations.ts (the use-case layer behind the file tools); canvas.ts (JSON Canvas to readable markdown); fit-image-to-byte-budget.ts (image byte-budget fitting); obsidian-markdown/pdf-engine.ts (the pdfjs bootstrap); obsidian-markdown/pdf.ts (PDF text extraction); the file_content and file_content_fts tables in the search index. Derive supported formats and size limits from the source at index time.",
+      "purpose": "How non-markdown vault files (images, PDFs, canvases, text and data files, HTML pages, scripts) are read, browsed, and searched. Modules: asset-operations.ts (the use-case layer behind the file tools); obsidian-markdown/file-kinds.ts (extension to file kind); utils/decode-text-buffer.ts (the UTF-8 text check reads and indexing share); obsidian-markdown/html.ts (HTML visible text); canvas.ts (JSON Canvas to readable markdown); fit-image-to-byte-budget.ts (image byte-budget fitting); obsidian-markdown/pdf-engine.ts (the pdfjs bootstrap); obsidian-markdown/pdf.ts (PDF text extraction); the file_content and file_content_fts tables in the search index. Derive supported formats and size limits from the source at index time.",
       "parent": "Architecture"
     },
     {
diff --git a/.env.example b/.env.example
index c867b4beb..2b0f2ae0a 100644
--- a/.env.example
+++ b/.env.example
@@ -66,8 +66,8 @@ GHCR_USER=
 # Folders to leave out of sync, comma-separated (default: none excluded).
 # SYNC_EXCLUDED_FOLDERS=
 # Attachment types to sync, comma-separated: image | audio | video | pdf | unsupported (default: image,audio,video,pdf).
-# To read CSV, JSON, TXT, XML, LOG, and YAML, set image,audio,video,pdf,unsupported (the value replaces the
-# default list) and turn on "Sync all other types" on the uploading device.
+# To read text files such as CSV, JSON, TXT, HTML and scripts, set image,audio,video,pdf,unsupported (the
+# value replaces the default list) and turn on "Sync all other types" on the uploading device.
 # SYNC_FILE_TYPES=
 # Obsidian settings categories to sync into the server's .obsidian/ folder
 # (default: daily notes settings, community plugin settings such as the
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index c46c3dd96..891171f58 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -345,11 +345,11 @@ Link queries use a `links` table populated during indexing:
 | `vault_read_file`  | `path, raw?, start_line?, limit?` | readOnlyHint |
 | `vault_list_files` | `folder?, extensions?, limit?`    | readOnlyHint |
 
-`vault_read_file` reads non-markdown vault files, dispatching on extension to the most useful representation per type:
+`vault_read_file` reads non-markdown vault files, dispatching on the file's kind to the most useful representation per type. `obsidian-markdown/file-kinds.ts` maps the lowercased extension to a kind, so `Report.PDF` is a PDF; every extension check in reads, indexing, the note mover and the link tools goes through it:
 
 1. **Images** (`.png`/`.jpg`/`.jpeg`/`.gif`/`.webp`) return an MCP `image` content block plus a one-line metadata text block: the path, the delivered format, dimensions and bytes, and, when the image was recompressed, its original dimensions and bytes. A shared fit-to-byte-budget pipeline (`utils/fit-image-to-byte-budget.ts`, built on sharp) makes oversized images deliverable: EXIF auto-orient → resize long edge to ≤1568px → walk a fixed quality ladder (JPEG via mozjpeg for opaque images, WebP for alpha — PNG has no quality knob) → shrink dimensions by √(budget/actual) if the ladder floor still exceeds the budget. Deterministic and terminating (bounded attempts, 64px floor); sharp's default `limitInputPixels` stays active as the decompression-bomb guard. The budget (`MAX_IMAGE_OUTPUT_BYTES`, default 48 KiB binary) is sized for the tightest mainstream client cap.
 2. **Canvas** (`.canvas`) linearizes to markdown via the pure `obsidian-markdown/canvas.ts` parser ([JSON Canvas 1.0](https://jsoncanvas.org)): group membership by spatial rect containment (innermost group wins; equal rects tiebreak deterministically by id), nodes in reading order (y, then x), and an edge list with node ids resolved to display names. Lenient parsing — unknown properties ignored, malformed entries skipped. `raw: true` skips the linearizer and returns the JSON source verbatim for full structural fidelity. Canvas content is also FTS-indexed (linearized text in `file_content` + `file_content_fts` tables, gated behind `FILE_TOOLS_ENABLED`) so canvas files appear in `vault_search` results with `kind: "file"`. Canvas `file`-type node references are extracted unconditionally into the `links` table for graph queries regardless of the feature gate.
-3. **Text formats** (`.svg`/`.json`/`.txt`/`.csv`/`.xml`/`.log`/`.yaml`/`.yml`/`.base`) pass through verbatim as text, capped at a fixed 100 KiB output size (explicit error over silent truncation). `start_line`/`limit` page any text result — passthrough formats, canvas renditions, PDF-extracted text — as a 1-based line window preceded by a window-metadata block stating the range, total line count, and next `start_line`; the cap applies to the window, and an unpaged read stays byte-exact.
+3. **Text formats** (`.svg`/`.json`/`.txt`/`.csv`/`.xml`/`.log`/`.yaml`/`.yml`/`.base`) pass through verbatim as text, capped at a fixed 100 KiB output size (explicit error over silent truncation). They skip the NUL-byte check in item 5, so a NUL-padded log still reads. `start_line`/`limit` page any text result — text files, canvas renditions, PDF-extracted text — as a 1-based line window preceded by a window-metadata block stating the range, total line count, and next `start_line`; the cap applies to the window, and an unpaged read stays byte-exact.
 4. **PDFs** (`.pdf`) return structured markdown reconstructed from layout-aware extraction (`unpdf`, based on Mozilla's PDF.js):
    - A document metadata header (title, page count, link count)
    - Heading hierarchy inferred from font sizes relative to the dominant
@@ -364,11 +364,27 @@ Link queries use a `links` table populated during indexing:
 
    **Why text works without system fonts:** every PDF read goes through `obsidian-markdown/pdf-engine.ts`, which swaps unpdf's bundled edge build for the `pdfjs-dist` legacy Node build and creates document proxies with `disableFontFace` + bundled standard fonts + cMaps. Glyphs render from font data (embedded or bundled), never from host system fonts, so text survives in the fontless container. unpdf's own defaults reach the bundled fonts only if a lookup of `pdfjs-dist` succeeds, and a failed lookup is silent: rendering falls back to system fonts, which drops all text glyphs where no fonts exist while vector graphics still draw.
 
-5. **Unknown types** return an error naming the readable set.
+5. **Every other file** — HTML pages, scripts, and files with an unlisted extension or none — returns its source as text, with the same cap and paging. `utils/decode-text-buffer.ts` refuses two cases:
+   - a NUL byte in the first 8,000 bytes, git's test for binary data, which also catches UTF-16 text; the error names the readable types
+   - bytes that are not UTF-8
 
 The extension-to-representation routing above is implemented by the `vault-operations/asset-operations.ts` use-case. Beneath it, every read goes through `vaultFs.readAsset`, which applies the same `resolveSafePath` traversal + hidden-path guards as notes, rejects `.md` paths (notes belong to `vault_read_note`), and enforces a stat-before-read size cap (`MAX_FILE_BYTES`, default 50 MiB). The read buffer is one byte longer than the statted size, so a file that grows during the read (an Obsidian Sync download can do this) fills that byte, and the read fails with "file changed while reading".
 
-`vault_list_files` is the discovery surface (also `vault-operations/asset-operations.ts`): a filesystem walk (`vaultFs.listAssets` — filesystem truth, deliberately not the index), folder and case-insensitive extension filters, per-extension counts computed over the full filtered set, and byte sizes statted only for the returned slice. Canvas, PDF, and text files (.txt, .csv, .json, .xml, .svg, .log, .yaml, .yml, .base) are indexed for full-text search in the `file_content` + `file_content_fts` tables — see Canvas entry above for the canvas-specific link graph integration. PDF text is extracted via `obsidian-markdown/pdf.ts` (structured markdown reconstruction) — this works on PDFs with embedded text content; scanned or image-only PDFs have no text to extract, so they are indexed with an empty body and found by file name only. Text files are indexed as raw UTF-8 content. Content exceeding 100 KiB is truncated before FTS insertion.
+`vault_list_files` is the discovery surface (also `vault-operations/asset-operations.ts`): a filesystem walk (`vaultFs.listAssets` — filesystem truth, deliberately not the index), folder and case-insensitive extension filters, per-extension counts computed over the full filtered set, and byte sizes statted only for the returned slice.
+
+Search indexes file content in the `file_content` + `file_content_fts` tables, cut to 100 KiB before FTS insertion. Each kind is indexed as follows:
+
+| Kind                         | Indexed text                                                                                                      | Embedded |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
+| Canvas                       | Linearized outline; file cards also go to the link graph (see Canvas above)                                       | Yes      |
+| PDF                          | Text extracted by `obsidian-markdown/pdf.ts`; a scanned or image-only PDF has none and is found by file name only | Yes      |
+| Text formats (item 3)        | The file's UTF-8 content                                                                                          | Yes      |
+| HTML (`.html`/`.htm`)        | The text a browser shows, from `obsidian-markdown/html.ts`; a page over 16 MiB is found by file name only         | Yes      |
+| Scripts (`.py`/`.sh`/`.ps1`) | The file's source                                                                                                 | No       |
+
+- **HTML extraction** runs htmlparser2's tokenizer, which keeps no element stack, so unclosed tags cost no more than closed ones. Hidden elements (script, style, noscript, template, and the fallback content of iframe, noembed and noframes) end only at a closing tag with their own name, so a stray closing tag never shows hidden text. Block elements become line breaks, other whitespace collapses, and reading stops at the 100 KiB cap. Extraction stays on the main thread; the 16 MiB page limit keeps its measured worst case under the 2-second bar for moving a parser to a worker.
+- **HTML pages and scripts are read as bytes** and indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds text a read refuses. When a watched page or script stops passing it, its stored content is removed and its file row stays.
+- **Scripts are searched by keyword only.** The markdown chunker reads a script's `# comment` lines as headings and turns `snake_case` names into one word, so embedding skips scripts before their text loads.
 
 **Opt-out:** File tools are opt-out: set `FILE_TOOLS_ENABLED=false` to hide `vault_read_file` and `vault_list_files`, and strip file tool references from server metadata and other tool descriptions. The `vault_get_outgoing_links` tool continues to report file links (it indexes from the links table, not the file tools). File config vars (`MAX_FILE_BYTES`, `MAX_IMAGE_OUTPUT_BYTES`, `MAX_PDF_RENDER_PAGES`) are still parsed when disabled.
 
@@ -460,7 +476,7 @@ Both models lazy-load on first use (~1–2s cold start each, kept in memory afte
 `vault_search` calls `hybridSearch`, which runs up to four ranked retrieval legs and merges results via RRF. The flow:
 
 1. **Note FTS5** keyword search (synchronous, `fullTextSearch`)
-2. **File content FTS5** — linearized canvas, extracted PDF text, plain text files (skipped when note-specific filters are active)
+2. **File content FTS5** — linearized canvas, extracted PDF text, text files, HTML visible text, and scripts (skipped when note-specific filters are active)
 3. **Note vector search** — embed the query → sqlite-vec KNN over `note_vectors` → deduplicate to best chunk per note
 4. **File content vector search** — same query embedding → KNN over `file_content_vectors` → deduplicate to best chunk per file (same skip condition as step 2)
 5. **RRF fusion** (`computeRrfScores`) — score = Σ(1/(k+rank)) across all available lists, k=60, with top-rank bonuses (+0.05 rank 1, +0.02 ranks 2–3):
@@ -563,7 +579,7 @@ Content-hash gating (SHA-256 per chunk) skips re-embedding unchanged content on
 
 - `note_chunks`: stores chunk text, position index, and content hash per note
 - `note_vectors` (vec0): stores 384-dim Float32 embeddings keyed by chunk ID
-- `file_content_chunks`: stores chunk text, position index, and content hash per non-markdown file (canvas, PDF, text)
+- `file_content_chunks`: stores chunk text, position index, and content hash per non-markdown file (canvas, PDF, text, HTML; scripts are never embedded)
 - `file_content_vectors` (vec0): stores 384-dim Float32 embeddings keyed by chunk ID
 
 **New-directory rescan:** chokidar handles a newly-appeared directory in two steps: first it scans the directory's contents, then it registers the directory's `fs.watch`. A file created between the scan and the registration is silently lost ([chokidar#1471](https://github.com/paulmillr/chokidar/issues/1471)) — the scan didn't see it, and no watch existed to catch the event. The server's atomic write into a freshly created folder can hit exactly that window, leaving the note invisible to search. As a safety net, the watcher schedules a one-shot rescan of every new directory, delayed to twice chokidar's write-stability threshold (`awaitWriteFinish`, 2 s — a 4 s delay) so in-flight writes settle first. The rescan:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3710638f7..31a94f34d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -313,26 +313,26 @@ these are its settings:
 
 Variables, in the order the deploy form shows them (everything after the six inputs sits under **Pre-Configured Environment Variables**, collapsed):
 
-| Variable                          | Value                                 | Description shown on the deploy form                                                                                                                                                                                                                                                                                                                                                                      |
-| --------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TZ`                              | _(optional input)_                    | Your timezone as an [IANA name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) (`America/Toronto`) — decides what "today" means for daily notes, task due dates, and memory timestamps. Leave empty for UTC                                                                                                                                                                           |
-| `VAULT_NAME`                      | _(required input)_                    | Your vault's name, the same as it is in Obsidian                                                                                                                                                                                                                                                                                                                                                          |
-| `VAULT_PASSWORD`                  | _(optional input)_                    | Only if your vault uses end-to-end encryption; otherwise leave empty                                                                                                                                                                                                                                                                                                                                      |
-| `SYNC_FILE_TYPES`                 | _(optional input)_                    | Attachment types to sync, comma-separated — the same toggles as Obsidian's Sync → Selective sync. **Valid values:** image, audio, video, pdf, unsupported. **Leave empty for the default:** image,audio,video,pdf. To read CSV, JSON, TXT, XML, LOG, and YAML files, enter image,audio,video,pdf,unsupported and turn on **Sync all other types** in Obsidian's Sync settings on the device that has them |
-| `OBSIDIAN_AUTH_TOKEN`             | _(optional input)_                    | Leave empty to sign in through the `/setup` page after deploy, or paste a token from `npx vault-cortex@latest get-sync-token`                                                                                                                                                                                                                                                                             |
-| `SYNC_EXCLUDED_FOLDERS`           | _(optional input)_                    | Folders to leave out of sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Leave empty to exclude nothing                                                                                                                                                                                                                                                                       |
-| `MCP_AUTH_TOKEN`                  | `${{secret(64, "0123456789abcdef")}}` | Generated for you — the token your MCP client enters on the consent page                                                                                                                                                                                                                                                                                                                                  |
-| `PORT`                            | `8000`                                | The port the image listens on. Leave as is.                                                                                                                                                                                                                                                                                                                                                               |
-| `STORAGE_ROOT`                    | `/persist`                            | Where the volume is mounted — vault, search index and its models, Sync device state, and logs live under it. Leave as is.                                                                                                                                                                                                                                                                                 |
-| `DEVICE_NAME`                     | `vault-cortex`                        | The device name that labels this container's changes in Obsidian's sync log                                                                                                                                                                                                                                                                                                                               |
-| `TRUST_PROXY_HOPS`                | `2`                                   | Railway proxies between a visitor and the container, so the server sees the visitor's real address                                                                                                                                                                                                                                                                                                        |
-| `RAILWAY_HEALTHCHECK_TIMEOUT_SEC` | `900`                                 | How long Railway waits for the first health check — the first start downloads the vault and builds the index                                                                                                                                                                                                                                                                                              |
-| `MEMORY_ENABLED`                  | `true`                                | The About Me/ memory layer and its tools. Set false to hide them and skip creating the folder                                                                                                                                                                                                                                                                                                             |
-| `EMBEDDING_ENABLED`               | `true`                                | Semantic search. Set false to skip the models and use keyword search only — fits in much less memory                                                                                                                                                                                                                                                                                                      |
-| `READONLY_MODE`                   | `false`                               | Set true to hide every tool that changes the vault — clients can only read and search                                                                                                                                                                                                                                                                                                                     |
-| `FILE_TOOLS_ENABLED`              | `true`                                | vault_read_file and vault_list_files. Set false when Obsidian Sync has attachment syncing off                                                                                                                                                                                                                                                                                                             |
-| `SYNC_MODE`                       | `bidirectional`                       | Sync direction: bidirectional, pull-only (edits made on the server stay on the server and are never uploaded), or mirror-remote (Obsidian Sync overwrites edits made on the server, so the server always matches your vault). An invalid value stops the container at boot                                                                                                                                |
-| `CONFLICT_STRATEGY`               | `merge`                               | Obsidian Sync conflict resolution: merge integrates changes automatically; conflict writes a separate conflict file                                                                                                                                                                                                                                                                                       |
+| Variable                          | Value                                 | Description shown on the deploy form                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TZ`                              | _(optional input)_                    | Your timezone as an [IANA name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) (`America/Toronto`) — decides what "today" means for daily notes, task due dates, and memory timestamps. Leave empty for UTC                                                                                                                                                                                      |
+| `VAULT_NAME`                      | _(required input)_                    | Your vault's name, the same as it is in Obsidian                                                                                                                                                                                                                                                                                                                                                                     |
+| `VAULT_PASSWORD`                  | _(optional input)_                    | Only if your vault uses end-to-end encryption; otherwise leave empty                                                                                                                                                                                                                                                                                                                                                 |
+| `SYNC_FILE_TYPES`                 | _(optional input)_                    | Attachment types to sync, comma-separated — the same toggles as Obsidian's Sync → Selective sync. **Valid values:** image, audio, video, pdf, unsupported. **Leave empty for the default:** image,audio,video,pdf. To read text files such as CSV, JSON, TXT, HTML and scripts, enter image,audio,video,pdf,unsupported and turn on **Sync all other types** in Obsidian's Sync settings on the device that has them |
+| `OBSIDIAN_AUTH_TOKEN`             | _(optional input)_                    | Leave empty to sign in through the `/setup` page after deploy, or paste a token from `npx vault-cortex@latest get-sync-token`                                                                                                                                                                                                                                                                                        |
+| `SYNC_EXCLUDED_FOLDERS`           | _(optional input)_                    | Folders to leave out of sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Leave empty to exclude nothing                                                                                                                                                                                                                                                                                  |
+| `MCP_AUTH_TOKEN`                  | `${{secret(64, "0123456789abcdef")}}` | Generated for you — the token your MCP client enters on the consent page                                                                                                                                                                                                                                                                                                                                             |
+| `PORT`                            | `8000`                                | The port the image listens on. Leave as is.                                                                                                                                                                                                                                                                                                                                                                          |
+| `STORAGE_ROOT`                    | `/persist`                            | Where the volume is mounted — vault, search index and its models, Sync device state, and logs live under it. Leave as is.                                                                                                                                                                                                                                                                                            |
+| `DEVICE_NAME`                     | `vault-cortex`                        | The device name that labels this container's changes in Obsidian's sync log                                                                                                                                                                                                                                                                                                                                          |
+| `TRUST_PROXY_HOPS`                | `2`                                   | Railway proxies between a visitor and the container, so the server sees the visitor's real address                                                                                                                                                                                                                                                                                                                   |
+| `RAILWAY_HEALTHCHECK_TIMEOUT_SEC` | `900`                                 | How long Railway waits for the first health check — the first start downloads the vault and builds the index                                                                                                                                                                                                                                                                                                         |
+| `MEMORY_ENABLED`                  | `true`                                | The About Me/ memory layer and its tools. Set false to hide them and skip creating the folder                                                                                                                                                                                                                                                                                                                        |
+| `EMBEDDING_ENABLED`               | `true`                                | Semantic search. Set false to skip the models and use keyword search only — fits in much less memory                                                                                                                                                                                                                                                                                                                 |
+| `READONLY_MODE`                   | `false`                               | Set true to hide every tool that changes the vault — clients can only read and search                                                                                                                                                                                                                                                                                                                                |
+| `FILE_TOOLS_ENABLED`              | `true`                                | vault_read_file and vault_list_files. Set false when Obsidian Sync has attachment syncing off                                                                                                                                                                                                                                                                                                                        |
+| `SYNC_MODE`                       | `bidirectional`                       | Sync direction: bidirectional, pull-only (edits made on the server stay on the server and are never uploaded), or mirror-remote (Obsidian Sync overwrites edits made on the server, so the server always matches your vault). An invalid value stops the container at boot                                                                                                                                           |
+| `CONFLICT_STRATEGY`               | `merge`                               | Obsidian Sync conflict resolution: merge integrates changes automatically; conflict writes a separate conflict file                                                                                                                                                                                                                                                                                                  |
 
 Update the template whenever the image tag, a boot-required variable, the
 port, or the health path changes, then re-publish; existing deployments keep
diff --git a/DEPLOY.md b/DEPLOY.md
index 021c6b2d9..88481163d 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -354,34 +354,34 @@ To find your stage: `cat .sst/stage` (after one-time setup).
 
 **Variables** (Settings → Secrets and variables → Actions → Variables tab):
 
-| Variable                              | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `GHCR_USER`                           | GitHub username. Used in image tags and instance `.env`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `DOCKERHUB_USERNAME`                  | Optional. Docker Hub username. When set, images are mirrored to Docker Hub alongside GHCR on release and README syncs automatically. Omit to skip entirely.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `EMBEDDING_ENABLED`                   | Optional. Set `false` to disable the embedding pipeline — skips model download, vector tables, embedding passes, and hybrid search. Search falls back to FTS5 keyword matching. Default: `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `RERANK_MODE`                         | Optional. Cross-encoder reranking mode: `blended` (default) applies position-aware score blending after RRF fusion, `none` skips reranking for lower latency. Only takes effect when `EMBEDDING_ENABLED` is true.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `MEMORY_ENABLED`                      | Optional. Set `false` to disable the memory layer entirely — hides memory tools, skips bootstrap, omits memory from server metadata. Default: `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `FILE_TOOLS_ENABLED`                  | Optional. Set `false` to hide file tools (`vault_read_file`, `vault_list_files`) for deployments without synced attachments. Default: `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `READONLY_MODE`                       | Optional. Set `true` to hide every tool that changes the vault and skip memory folder auto-creation — read and search only. Default: `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `DISABLED_TOOLS`                      | Optional. Hide individual tools by name, comma-separated. Names match the Tool column in the [README tools table](./README.md#tools). Subtractive only; an unknown tool name stops the server at startup. Default: none hidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `MEMORY_DIR`                          | Optional. Memory folder name in the vault (default: `About Me`). See the [Configuration](./README.md#configuration) section.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `PROTECTED_PATHS`                     | Optional. Comma-separated folders protected from deletion and moves (default: `MEMORY_DIR` plus the daily notes folder, read from `DAILY_NOTES_FOLDER` or `.obsidian/daily-notes.json`, default `Daily Notes`; none when that setting is the vault root or empty). Overrides the default entirely when set.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `ORPHAN_EXCLUDE_FOLDERS`              | Optional. Comma-separated folders excluded from orphan detection (default: the daily notes folder, `Templates`, and `MEMORY_DIR`). The `DAILY_NOTES_FOLDER` variable wins; otherwise synced `.obsidian/daily-notes.json` is reread per query (fallback `Daily Notes`). Overrides the default entirely when set. Use `,` to exclude nothing; an empty value uses the defaults. Apply variable changes with Force Deploy; synced Obsidian changes need no redeploy. See [Daily notes](./README.md#daily-notes) for root and empty settings.                                                                                                                                                                                                              |
-| `SERVICE_DOCUMENTATION_URL`           | Optional. URL in OAuth discovery metadata (default: `https://github.com/aliasunder/vault-cortex`). Set to your fork's URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `SYNC_CONFIGS`                        | Optional. Obsidian settings categories synced to the server, comma-separated (default: `core-plugin-data,community-plugin-data,app` — daily-notes settings, the Tasks plugin's format, and the new-note location). Set `none` to disable. See [Daily notes](./README.md#daily-notes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `SYNC_EXCLUDED_FOLDERS`               | Optional. Folders to leave out of Obsidian Sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Unset syncs everything.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `SYNC_FILE_TYPES`                     | Optional. Attachment types Obsidian Sync delivers, comma-separated. **Valid values:** `image`, `audio`, `video`, `pdf`, `unsupported`. **Unset (default):** `image,audio,video,pdf`. The text files Vault Cortex reads (CSV, JSON, TXT, XML, LOG, YAML) fall under `unsupported`, Obsidian Sync's name for its **Sync all other types** category; SVG syncs as `image`, and notes, canvases, and bases always sync. To read those text files, set it to `image,audio,video,pdf,unsupported` (the value replaces the default list, so keep the four defaults) and turn on **Sync all other types** in Obsidian's Sync settings on the device that has them. An invalid value is skipped with a warning in the logs, and the default types sync instead. |
-| `DAILY_NOTES_FOLDER`                  | Optional. Sets the daily notes folder: any vault-relative path, or `/` for the vault root (default: read from the vault's `.obsidian/daily-notes.json`; `Daily Notes` when that file is missing or unreadable). See [Daily notes](./README.md#daily-notes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `DAILY_NOTES_FORMAT`                  | Optional. Sets the daily note filename format, in the same tokens as Obsidian's daily note date format setting (default: read from the vault's config, falling back to `YYYY-MM-DD`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `TZ`                                  | Optional. Container timezone (default: `UTC`). Affects `vault_update_memory` date stamps and `vault_get_daily_note` date resolution. Set to your IANA timezone (e.g. `America/New_York`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `LOG_LEVEL`                           | Optional. Logging verbosity: `debug`, `info`, `warn`, `error`. Default: `info`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `LOG_DIR`                             | Optional. Directory for persistent log files inside the container. Default: `/data/logs`; `none` disables log files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `LOG_RETENTION_DAYS`                  | Optional. Days to keep log files before automatic cleanup on startup; only applies when `LOG_DIR` is a path. Default: `90`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `WINDOWS_MODE`                        | Optional. Set `true` when the vault is on a Windows drive (Docker Desktop). Default: `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `TRUST_PROXY_HOPS`                    | Optional. Trusted reverse-proxy hops for deriving `req.ip` from `X-Forwarded-For` (the fallback client IP). The compose file defaults the instance to `1` (API Gateway); set `2` for `ORIGIN_URL` deployments (a tunnel between the gateway and the instance).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `TRUST_FORWARDED_HOPS`                | Optional. How many entries from the end of the [RFC 7239](https://www.rfc-editor.org/rfc/rfc7239) `Forwarded` header's `for=` list to count to reach the client IP (OAuth rate limiting, request logs); `0` ignores the header. The compose file defaults the instance to `1` (API Gateway reports visitors there and sends no `X-Forwarded-For`). For `ORIGIN_URL` and CDN setups, see the **Client-IP trust with ORIGIN_URL** callout under [Port 8000 Hardening](#port-8000-hardening-optional).                                                                                                                                                                                                                                                    |
-| `ORIGIN_ACCESS_SERVICE_TOKEN_ENABLED` | Optional, SST deploys only. Set `true` once the tunnel hostname behind `ORIGIN_URL` is locked with a Cloudflare Access service token — API Gateway then presents the `OriginAccessClientId` / `OriginAccessClientSecret` SST secrets on every request (see [Port 8000 Hardening](#port-8000-hardening-optional), steps 5–8). It has no effect unless `ORIGIN_URL` is set.                                                                                                                                                                                                                                                                                                                                                                              |
-| `DISABLE_EXECUTE_API_ENDPOINT`        | Optional. Requires the `CUSTOM_DOMAIN` secret. Set `true` once every client uses the custom domain: the gateway stops answering on its default `execute-api` hostname at the next deploy. If a CDN sits in front of the custom domain, set this to `true` before setting `TRUST_FORWARDED_HOPS=2`; the **Client-IP trust with ORIGIN_URL** callout under [Port 8000 Hardening](#port-8000-hardening-optional) explains why.                                                                                                                                                                                                                                                                                                                            |
+| Variable                              | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GHCR_USER`                           | GitHub username. Used in image tags and instance `.env`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `DOCKERHUB_USERNAME`                  | Optional. Docker Hub username. When set, images are mirrored to Docker Hub alongside GHCR on release and README syncs automatically. Omit to skip entirely.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `EMBEDDING_ENABLED`                   | Optional. Set `false` to disable the embedding pipeline — skips model download, vector tables, embedding passes, and hybrid search. Search falls back to FTS5 keyword matching. Default: `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `RERANK_MODE`                         | Optional. Cross-encoder reranking mode: `blended` (default) applies position-aware score blending after RRF fusion, `none` skips reranking for lower latency. Only takes effect when `EMBEDDING_ENABLED` is true.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `MEMORY_ENABLED`                      | Optional. Set `false` to disable the memory layer entirely — hides memory tools, skips bootstrap, omits memory from server metadata. Default: `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `FILE_TOOLS_ENABLED`                  | Optional. Set `false` to hide file tools (`vault_read_file`, `vault_list_files`) for deployments without synced attachments. Default: `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `READONLY_MODE`                       | Optional. Set `true` to hide every tool that changes the vault and skip memory folder auto-creation — read and search only. Default: `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `DISABLED_TOOLS`                      | Optional. Hide individual tools by name, comma-separated. Names match the Tool column in the [README tools table](./README.md#tools). Subtractive only; an unknown tool name stops the server at startup. Default: none hidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `MEMORY_DIR`                          | Optional. Memory folder name in the vault (default: `About Me`). See the [Configuration](./README.md#configuration) section.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `PROTECTED_PATHS`                     | Optional. Comma-separated folders protected from deletion and moves (default: `MEMORY_DIR` plus the daily notes folder, read from `DAILY_NOTES_FOLDER` or `.obsidian/daily-notes.json`, default `Daily Notes`; none when that setting is the vault root or empty). Overrides the default entirely when set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `ORPHAN_EXCLUDE_FOLDERS`              | Optional. Comma-separated folders excluded from orphan detection (default: the daily notes folder, `Templates`, and `MEMORY_DIR`). The `DAILY_NOTES_FOLDER` variable wins; otherwise synced `.obsidian/daily-notes.json` is reread per query (fallback `Daily Notes`). Overrides the default entirely when set. Use `,` to exclude nothing; an empty value uses the defaults. Apply variable changes with Force Deploy; synced Obsidian changes need no redeploy. See [Daily notes](./README.md#daily-notes) for root and empty settings.                                                                                                                                                                                                                                   |
+| `SERVICE_DOCUMENTATION_URL`           | Optional. URL in OAuth discovery metadata (default: `https://github.com/aliasunder/vault-cortex`). Set to your fork's URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `SYNC_CONFIGS`                        | Optional. Obsidian settings categories synced to the server, comma-separated (default: `core-plugin-data,community-plugin-data,app` — daily-notes settings, the Tasks plugin's format, and the new-note location). Set `none` to disable. See [Daily notes](./README.md#daily-notes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `SYNC_EXCLUDED_FOLDERS`               | Optional. Folders to leave out of Obsidian Sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Unset syncs everything.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `SYNC_FILE_TYPES`                     | Optional. Attachment types Obsidian Sync delivers, comma-separated. **Valid values:** `image`, `audio`, `video`, `pdf`, `unsupported`. **Unset (default):** `image,audio,video,pdf`. The text files Vault Cortex reads (CSV, JSON, TXT, HTML, scripts and other UTF-8 files) fall under `unsupported`, Obsidian Sync's name for its **Sync all other types** category; SVG syncs as `image`, and notes, canvases, and bases always sync. To read those text files, set it to `image,audio,video,pdf,unsupported` (the value replaces the default list, so keep the four defaults) and turn on **Sync all other types** in Obsidian's Sync settings on the device that has them. An invalid value is skipped with a warning in the logs, and the default types sync instead. |
+| `DAILY_NOTES_FOLDER`                  | Optional. Sets the daily notes folder: any vault-relative path, or `/` for the vault root (default: read from the vault's `.obsidian/daily-notes.json`; `Daily Notes` when that file is missing or unreadable). See [Daily notes](./README.md#daily-notes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `DAILY_NOTES_FORMAT`                  | Optional. Sets the daily note filename format, in the same tokens as Obsidian's daily note date format setting (default: read from the vault's config, falling back to `YYYY-MM-DD`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `TZ`                                  | Optional. Container timezone (default: `UTC`). Affects `vault_update_memory` date stamps and `vault_get_daily_note` date resolution. Set to your IANA timezone (e.g. `America/New_York`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `LOG_LEVEL`                           | Optional. Logging verbosity: `debug`, `info`, `warn`, `error`. Default: `info`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `LOG_DIR`                             | Optional. Directory for persistent log files inside the container. Default: `/data/logs`; `none` disables log files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `LOG_RETENTION_DAYS`                  | Optional. Days to keep log files before automatic cleanup on startup; only applies when `LOG_DIR` is a path. Default: `90`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `WINDOWS_MODE`                        | Optional. Set `true` when the vault is on a Windows drive (Docker Desktop). Default: `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `TRUST_PROXY_HOPS`                    | Optional. Trusted reverse-proxy hops for deriving `req.ip` from `X-Forwarded-For` (the fallback client IP). The compose file defaults the instance to `1` (API Gateway); set `2` for `ORIGIN_URL` deployments (a tunnel between the gateway and the instance).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `TRUST_FORWARDED_HOPS`                | Optional. How many entries from the end of the [RFC 7239](https://www.rfc-editor.org/rfc/rfc7239) `Forwarded` header's `for=` list to count to reach the client IP (OAuth rate limiting, request logs); `0` ignores the header. The compose file defaults the instance to `1` (API Gateway reports visitors there and sends no `X-Forwarded-For`). For `ORIGIN_URL` and CDN setups, see the **Client-IP trust with ORIGIN_URL** callout under [Port 8000 Hardening](#port-8000-hardening-optional).                                                                                                                                                                                                                                                                         |
+| `ORIGIN_ACCESS_SERVICE_TOKEN_ENABLED` | Optional, SST deploys only. Set `true` once the tunnel hostname behind `ORIGIN_URL` is locked with a Cloudflare Access service token — API Gateway then presents the `OriginAccessClientId` / `OriginAccessClientSecret` SST secrets on every request (see [Port 8000 Hardening](#port-8000-hardening-optional), steps 5–8). It has no effect unless `ORIGIN_URL` is set.                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `DISABLE_EXECUTE_API_ENDPOINT`        | Optional. Requires the `CUSTOM_DOMAIN` secret. Set `true` once every client uses the custom domain: the gateway stops answering on its default `execute-api` hostname at the next deploy. If a CDN sits in front of the custom domain, set this to `true` before setting `TRUST_FORWARDED_HOPS=2`; the **Client-IP trust with ORIGIN_URL** callout under [Port 8000 Hardening](#port-8000-hardening-optional) explains why.                                                                                                                                                                                                                                                                                                                                                 |
 
 **Secrets** (Settings → Secrets and variables → Actions → Secrets tab):
 
diff --git a/DOCKERHUB.md b/DOCKERHUB.md
index 8a7517ee5..e2047bd36 100644
--- a/DOCKERHUB.md
+++ b/DOCKERHUB.md
@@ -48,7 +48,7 @@
 - **[Structured memory](https://github.com/aliasunder/vault-cortex#memory)** — dated, append-only entries accumulate into a personal knowledge layer, auto-initialized for AI personalization. Topic recall answers "what do I think about X?" with the current take and the dated history behind it — evolution included.
 - **[Tasks](https://github.com/aliasunder/vault-cortex#tasks)** — Kanban-aware task queries and updates: triage by status, dates, or priority, then complete, reprioritize, or move tasks between lanes in one call. Completing a recurring task spawns its next occurrence. Parses both [Tasks plugin](https://publish.obsidian.md/tasks/) emoji and [Dataview](https://blacksmithgu.github.io/obsidian-dataview/) inline-field formats.
 - **[Link graph](https://github.com/aliasunder/vault-cortex#tools)** — backlinks, outgoing links, and orphan detection across the vault
-- **[Files](https://github.com/aliasunder/vault-cortex#files)** — read the vault's non-markdown files too: images arrive as actual images (shrunk to fit when needed), PDFs as structured text or rendered pages, canvases as readable outlines, data files as text
+- **[Files](https://github.com/aliasunder/vault-cortex#files)** — read the vault's non-markdown files too: images arrive as actual images (shrunk to fit when needed), PDFs as structured text or rendered pages, canvases as readable outlines, data files, HTML pages, and scripts as text
 - **[Obsidian-native](https://github.com/aliasunder/vault-cortex#properties)** — understands frontmatter, wikilinks, tags, headings, and daily notes
 - **[Guided workflows](https://github.com/aliasunder/vault-cortex#prompts)** — built-in prompts for vault health, memory review, and daily reconciliation — assembled from live vault data each time
 
@@ -61,22 +61,6 @@
 
 See the [full Quick Start guide](https://github.com/aliasunder/vault-cortex#quick-start) for local setup (2 minutes with Docker), one-click hosting on Render or Railway, remote deployment with Obsidian Sync, and MCP client configuration.
 
-## Files
-
-Your notes embed screenshots, reference architecture diagrams, and link out to canvases and data files — but to an agent reading markdown, `![[diagram.png]]` is just text. Vault Cortex treats files as part of the vault rather than clutter around it — linked, sized, and readable, each in the form an agent can use:
-
-- **Images** — the image itself, not the filename. Screenshots and diagrams are downscaled and recompressed server-side when they exceed what MCP clients accept, so even a phone session can look at a 5MB architecture diagram
-- **Canvases** — a [Canvas](https://help.obsidian.md/canvas) board arrives as a readable outline: its groups, each card's content in reading order, and the connections between them. Canvas content is full-text searchable, and file references on the board appear in the link graph — backlinks and outgoing links work just like note-to-note links. The exact JSON source is one flag away when full fidelity matters
-- **PDFs** — text is extracted with heading hierarchy, code blocks, and hyperlinks preserved; PDF content is full-text searchable alongside your notes. Set `raw: true` to render pages as images instead, showing layout, diagrams, and tables that text extraction can't preserve — scanned and image-only PDFs work in this mode
-- **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written; the first 100 KB of content is full-text searchable. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
-- **Browse** — list any visible folder's files with per-extension counts and file sizes; files a note links to report their size in the link graph too
-
-Set `FILE_TOOLS_ENABLED=false` to hide the file tools — useful when your remote vault syncs without attachments.
-
-See [ARCHITECTURE.md → Files](https://github.com/aliasunder/vault-cortex/blob/main/ARCHITECTURE.md#files) for the image pipeline and dispatch model.
-
----
-
 ## Tools
 
 | Category | Tool | Description |
diff --git a/README.md b/README.md
index 3458cf5b4..51985966b 100644
--- a/README.md
+++ b/README.md
@@ -43,7 +43,7 @@
 - **[Structured memory](#memory)** — dated, append-only entries accumulate into a personal knowledge layer, auto-initialized for AI personalization. Topic recall answers "what do I think about X?" with the current take and the dated history behind it — evolution included.
 - **[Tasks](#tasks)** — Kanban-aware task queries and updates: triage by status, dates, or priority, then complete, reprioritize, or move tasks between lanes in one call. Completing a recurring task spawns its next occurrence. Parses both [Tasks plugin](https://publish.obsidian.md/tasks/) emoji and [Dataview](https://blacksmithgu.github.io/obsidian-dataview/) inline-field formats.
 - **[Link graph](#tools)** — backlinks, outgoing links, and orphan detection across the vault
-- **[Files](#files)** — read the vault's non-markdown files too: images arrive as actual images (shrunk to fit when needed), PDFs as structured text or rendered pages, canvases as readable outlines, data files as text
+- **[Files](#files)** — read the vault's non-markdown files too: images arrive as actual images (shrunk to fit when needed), PDFs as structured text or rendered pages, canvases as readable outlines, data files, HTML pages, and scripts as text
 - **[Obsidian-native](#properties)** — understands frontmatter, wikilinks, tags, headings, and daily notes
 - **[Guided workflows](#prompts)** — built-in prompts for vault health, memory review, and daily reconciliation — assembled from live vault data each time
 
@@ -282,7 +282,8 @@ Your notes embed screenshots, reference architecture diagrams, and link out to c
 - **Images** — the image itself, not the filename. Screenshots and diagrams are downscaled and recompressed server-side when they exceed what MCP clients accept, so even a phone session can look at a 5MB architecture diagram
 - **Canvases** — a [Canvas](https://help.obsidian.md/canvas) board arrives as a readable outline: its groups, each card's content in reading order, and the connections between them. Canvas content is full-text searchable, and file references on the board appear in the link graph — backlinks and outgoing links work just like note-to-note links. The exact JSON source is one flag away when full fidelity matters
 - **PDFs** — text is extracted with heading hierarchy, code blocks, and hyperlinks preserved; PDF content is full-text searchable alongside your notes. Set `raw: true` to render pages as images instead, showing layout, diagrams, and tables that text extraction can't preserve — scanned and image-only PDFs work in this mode
-- **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written; the first 100 KB of content is full-text searchable. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
+- **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written, and their first 100 KB is full-text searchable. Any other UTF-8 text file reads back the same way. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
+- **HTML pages and scripts** — a saved page or generated report is searchable by the text a browser shows, never its tags or script code. Python, shell, and PowerShell scripts are searchable by keyword. Both read back as their source
 - **Browse** — list any visible folder's files with per-extension counts and file sizes; files a note links to report their size in the link graph too
 
 Set `FILE_TOOLS_ENABLED=false` to hide the file tools — useful when your remote vault syncs without attachments.
diff --git a/SECURITY.md b/SECURITY.md
index 10715a020..fddfa846c 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -90,8 +90,13 @@ mechanism-level detail.
   database stores refresh tokens keyed by an HMAC under `MCP_AUTH_TOKEN`,
   so a copy of it holds no usable credential.
   Hidden-path blocking does not cover a database relocated into a
-  _visible_ vault folder — there it is readable like any other vault
-  file.
+  _visible_ vault folder — there `vault_list_files` lists it like any
+  other vault file, and `vault_read_file` refuses it only because a
+  SQLite file holds binary data.
+- `vault_read_file` returns any visible file whose bytes are UTF-8 text,
+  whatever its extension, so a credential kept in a visible vault folder
+  (a `deploy.env` or `secrets.txt`) is readable by any signed-in client.
+  Hidden files such as `.env` stay refused by the hidden-path check above.
 - The hidden-path check is lexical: a visible symlink whose target is a
   hidden path is followed. Creating such a symlink requires direct
   filesystem access — no tool can create one, and anyone with that
diff --git a/cli/src/env.ts b/cli/src/env.ts
index 0e9496d1e..2b7be7fbb 100644
--- a/cli/src/env.ts
+++ b/cli/src/env.ts
@@ -369,9 +369,10 @@ SYNC_EXCLUDED_FOLDERS=
 # Sync → "Selective sync".
 #   Valid values: image | audio | video | pdf | unsupported
 #   Empty (default): image,audio,video,pdf
-# The text files Vault Cortex reads (CSV, JSON, TXT, XML, LOG, YAML) fall
-# under "unsupported", Obsidian Sync's name for its "Sync all other types"
-# category; SVG syncs as "image", and notes, canvases, and bases always sync.
+# The text files Vault Cortex reads (CSV, JSON, TXT, HTML, scripts and other
+# UTF-8 files) fall under "unsupported", Obsidian Sync's name for its "Sync
+# all other types" category; SVG syncs as "image", and notes, canvases, and
+# bases always sync.
 # To read those text files, set
 # SYNC_FILE_TYPES=image,audio,video,pdf,unsupported (the value replaces the
 # default list, so keep the four defaults) and turn on "Sync all other types"
diff --git a/deploy/railway/README.md b/deploy/railway/README.md
index c62529b88..63cfe4ca7 100644
--- a/deploy/railway/README.md
+++ b/deploy/railway/README.md
@@ -43,14 +43,14 @@ The button opens the template's page. Click **Deploy Now**, then
 
 ![Railway deploy form showing TZ, VAULT_NAME, VAULT_PASSWORD, SYNC_FILE_TYPES, OBSIDIAN_AUTH_TOKEN, and SYNC_EXCLUDED_FOLDERS fields](img/railway-configure.jpg)
 
-| Field                   | Value                                                                                                                                                                                                                                                                                                                                 |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TZ`                    | Your timezone as an [IANA name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) (`America/Toronto`) — decides what "today" means for daily notes, task due dates, and memory timestamps. Leave empty for UTC                                                                                                       |
-| `VAULT_NAME`            | Your vault's name, the same as it is in Obsidian                                                                                                                                                                                                                                                                                      |
-| `VAULT_PASSWORD`        | Only if your vault uses end-to-end encryption; otherwise leave empty                                                                                                                                                                                                                                                                  |
-| `SYNC_FILE_TYPES`       | Attachment types to sync, comma-separated. **Valid values:** `image`, `audio`, `video`, `pdf`, `unsupported`. **Leave empty for the default:** `image,audio,video,pdf`. To read CSV, JSON, TXT, XML, LOG, and YAML files, enter `image,audio,video,pdf,unsupported` and turn on **Sync all other types** for the device that has them |
-| `OBSIDIAN_AUTH_TOKEN`   | Leave empty — you sign in through the setup page after deploy (see [Sign in to Obsidian Sync](#sign-in-to-obsidian-sync)). Or paste a token from `npx vault-cortex@latest get-sync-token` to skip the setup page                                                                                                                      |
-| `SYNC_EXCLUDED_FOLDERS` | Folders to leave out of sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Leave empty to sync everything                                                                                                                                                                                                   |
+| Field                   | Value                                                                                                                                                                                                                                                                                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `TZ`                    | Your timezone as an [IANA name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) (`America/Toronto`) — decides what "today" means for daily notes, task due dates, and memory timestamps. Leave empty for UTC                                                                                                                  |
+| `VAULT_NAME`            | Your vault's name, the same as it is in Obsidian                                                                                                                                                                                                                                                                                                 |
+| `VAULT_PASSWORD`        | Only if your vault uses end-to-end encryption; otherwise leave empty                                                                                                                                                                                                                                                                             |
+| `SYNC_FILE_TYPES`       | Attachment types to sync, comma-separated. **Valid values:** `image`, `audio`, `video`, `pdf`, `unsupported`. **Leave empty for the default:** `image,audio,video,pdf`. To read text files such as CSV, JSON, TXT, HTML and scripts, enter `image,audio,video,pdf,unsupported` and turn on **Sync all other types** for the device that has them |
+| `OBSIDIAN_AUTH_TOKEN`   | Leave empty — you sign in through the setup page after deploy (see [Sign in to Obsidian Sync](#sign-in-to-obsidian-sync)). Or paste a token from `npx vault-cortex@latest get-sync-token` to skip the setup page                                                                                                                                 |
+| `SYNC_EXCLUDED_FOLDERS` | Folders to leave out of sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Leave empty to sync everything                                                                                                                                                                                                              |
 
 Fill in at least the vault name **before** the first deploy. Click
 **Deploy**. Railway creates the service and volume, pulls the image, and
@@ -270,27 +270,27 @@ release lists what changed since the last one, and an entry marked
 The template sets these; change them under the service's **Variables** tab
 (Railway stages the change and redeploys when you apply it):
 
-| Variable                          | Value           | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| --------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `STORAGE_ROOT`                    | `/persist`      | Where the volume is mounted — the vault, search index and its models, Sync device state, and logs live under it. Must not contain `*`, `?`, or `[`. Leave as is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `PORT`                            | `8000`          | The port the image listens on. Leave as is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `DEVICE_NAME`                     | `vault-cortex`  | The device name that labels this container's changes in Obsidian's sync log.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `TRUST_PROXY_HOPS`                | `2`             | Two Railway proxies sit between a visitor and the container; this lets the server see the visitor's real address in its logs and rate limits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `RAILWAY_HEALTHCHECK_TIMEOUT_SEC` | `900`           | How long Railway waits for the first health check — the first start downloads the vault and builds the index.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `MCP_AUTH_TOKEN`                  | generated       | Your MCP client's token. Change it here to rotate it — every connected client re-authorizes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `OBSIDIAN_AUTH_TOKEN`             | from setup page | Obsidian Sync login. Set by the setup page on first deploy (written to the volume). To sign in with a different account, set a new token here — it always overrides the file on the volume.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `VAULT_NAME`                      | yours           | The vault this container syncs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `VAULT_PASSWORD`                  | yours / empty   | End-to-end encryption password, if your vault has one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `TZ`                              | yours / empty   | Timezone for daily notes, task due dates, and memory timestamps. Empty means UTC.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `MEMORY_ENABLED`                  | `true`          | The About Me/ memory layer and its tools. Set `false` to hide them and skip creating the folder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `EMBEDDING_ENABLED`               | `true`          | Semantic search. Set `false` to skip the models and use keyword search only — the container fits in much less memory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `READONLY_MODE`                   | `false`         | Set `true` to hide every tool that changes the vault — clients can only read and search.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `FILE_TOOLS_ENABLED`              | `true`          | `vault_read_file` and `vault_list_files`. Set `false` when Obsidian Sync has attachment syncing off.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `SYNC_MODE`                       | `bidirectional` | Sync direction: `bidirectional`, `pull-only` (edits made on the server stay on the server and are never uploaded), or `mirror-remote` (Obsidian Sync overwrites edits made on the server, so the server always matches your vault). An invalid value stops the container at boot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `CONFLICT_STRATEGY`               | `merge`         | Obsidian Sync conflict resolution: `merge` integrates changes automatically; `conflict` writes a separate conflict file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `SYNC_EXCLUDED_FOLDERS`           | _(empty)_       | Folders to leave out of sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Empty excludes nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `SYNC_FILE_TYPES`                 | _(empty)_       | Attachment types to sync, comma-separated — the same toggles as Obsidian's Sync → Selective sync. **Valid values:** `image`, `audio`, `video`, `pdf`, `unsupported`. **Empty (default):** `image,audio,video,pdf`. The text files Vault Cortex reads (CSV, JSON, TXT, XML, LOG, YAML) fall under `unsupported`, Obsidian Sync's name for its **Sync all other types** category; SVG syncs as `image`, and notes, canvases, and bases always sync. To read those text files, set it to `image,audio,video,pdf,unsupported` (the value replaces the default list, so keep the four defaults) and turn on **Sync all other types** in Obsidian's Sync settings on the device that has them. An invalid value is skipped with a warning in the logs, and the default types sync instead. |
-| `LOG_DIR`                         | derived         | Log files, kept 90 days on the volume — the platform's own log viewer keeps only the last 7 days on Hobby plans. Set `none` to keep logs in the platform viewer only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Variable                          | Value           | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| --------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STORAGE_ROOT`                    | `/persist`      | Where the volume is mounted — the vault, search index and its models, Sync device state, and logs live under it. Must not contain `*`, `?`, or `[`. Leave as is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `PORT`                            | `8000`          | The port the image listens on. Leave as is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `DEVICE_NAME`                     | `vault-cortex`  | The device name that labels this container's changes in Obsidian's sync log.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `TRUST_PROXY_HOPS`                | `2`             | Two Railway proxies sit between a visitor and the container; this lets the server see the visitor's real address in its logs and rate limits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `RAILWAY_HEALTHCHECK_TIMEOUT_SEC` | `900`           | How long Railway waits for the first health check — the first start downloads the vault and builds the index.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `MCP_AUTH_TOKEN`                  | generated       | Your MCP client's token. Change it here to rotate it — every connected client re-authorizes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `OBSIDIAN_AUTH_TOKEN`             | from setup page | Obsidian Sync login. Set by the setup page on first deploy (written to the volume). To sign in with a different account, set a new token here — it always overrides the file on the volume.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `VAULT_NAME`                      | yours           | The vault this container syncs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `VAULT_PASSWORD`                  | yours / empty   | End-to-end encryption password, if your vault has one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `TZ`                              | yours / empty   | Timezone for daily notes, task due dates, and memory timestamps. Empty means UTC.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `MEMORY_ENABLED`                  | `true`          | The About Me/ memory layer and its tools. Set `false` to hide them and skip creating the folder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `EMBEDDING_ENABLED`               | `true`          | Semantic search. Set `false` to skip the models and use keyword search only — the container fits in much less memory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `READONLY_MODE`                   | `false`         | Set `true` to hide every tool that changes the vault — clients can only read and search.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `FILE_TOOLS_ENABLED`              | `true`          | `vault_read_file` and `vault_list_files`. Set `false` when Obsidian Sync has attachment syncing off.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `SYNC_MODE`                       | `bidirectional` | Sync direction: `bidirectional`, `pull-only` (edits made on the server stay on the server and are never uploaded), or `mirror-remote` (Obsidian Sync overwrites edits made on the server, so the server always matches your vault). An invalid value stops the container at boot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `CONFLICT_STRATEGY`               | `merge`         | Obsidian Sync conflict resolution: `merge` integrates changes automatically; `conflict` writes a separate conflict file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `SYNC_EXCLUDED_FOLDERS`           | _(empty)_       | Folders to leave out of sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Empty excludes nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `SYNC_FILE_TYPES`                 | _(empty)_       | Attachment types to sync, comma-separated — the same toggles as Obsidian's Sync → Selective sync. **Valid values:** `image`, `audio`, `video`, `pdf`, `unsupported`. **Empty (default):** `image,audio,video,pdf`. The text files Vault Cortex reads (CSV, JSON, TXT, HTML, scripts and other UTF-8 files) fall under `unsupported`, Obsidian Sync's name for its **Sync all other types** category; SVG syncs as `image`, and notes, canvases, and bases always sync. To read those text files, set it to `image,audio,video,pdf,unsupported` (the value replaces the default list, so keep the four defaults) and turn on **Sync all other types** in Obsidian's Sync settings on the device that has them. An invalid value is skipped with a warning in the logs, and the default types sync instead. |
+| `LOG_DIR`                         | derived         | Log files, kept 90 days on the volume — the platform's own log viewer keeps only the last 7 days on Hobby plans. Set `none` to keep logs in the platform viewer only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 `SYNC_MODE`, `CONFLICT_STRATEGY`, `SYNC_EXCLUDED_FOLDERS`, and
 `SYNC_FILE_TYPES` are the settings most worth changing on a hosted instance;
diff --git a/deploy/remote/.env.example b/deploy/remote/.env.example
index 24a18191a..1659f545d 100644
--- a/deploy/remote/.env.example
+++ b/deploy/remote/.env.example
@@ -200,9 +200,10 @@ SYNC_EXCLUDED_FOLDERS=
 # Sync → "Selective sync".
 #   Valid values: image | audio | video | pdf | unsupported
 #   Empty (default): image,audio,video,pdf
-# The text files Vault Cortex reads (CSV, JSON, TXT, XML, LOG, YAML) fall
-# under "unsupported", Obsidian Sync's name for its "Sync all other types"
-# category; SVG syncs as "image", and notes, canvases, and bases always sync.
+# The text files Vault Cortex reads (CSV, JSON, TXT, HTML, scripts and other
+# UTF-8 files) fall under "unsupported", Obsidian Sync's name for its "Sync
+# all other types" category; SVG syncs as "image", and notes, canvases, and
+# bases always sync.
 # To read those text files, set
 # SYNC_FILE_TYPES=image,audio,video,pdf,unsupported (the value replaces the
 # default list, so keep the four defaults) and turn on "Sync all other types"
diff --git a/deploy/remote/README.md b/deploy/remote/README.md
index dd03663e3..4fe09b88c 100644
--- a/deploy/remote/README.md
+++ b/deploy/remote/README.md
@@ -729,28 +729,28 @@ Only `MCP_AUTH_TOKEN`, `PUBLIC_URL`, and `VAULT_NAME` are required.
 `OBSIDIAN_AUTH_TOKEN` can be filled via the `/setup` page when left blank.
 These optional settings are worth knowing about:
 
-| Setting                 | Default                       | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ----------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `TZ`                    | `UTC`                         | Your IANA timezone (e.g. `America/New_York`) — affects daily note dates and timestamps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `VAULT_PASSWORD`        | —                             | Set this if your vault has end-to-end encryption enabled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `EMBEDDING_ENABLED`     | `true`                        | Set `false` to skip AI models (~59MB) and use keyword search only — saves memory on smaller instances                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `RERANK_MODE`           | `blended`                     | Set `none` to skip reranking for lower latency                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `MEMORY_ENABLED`        | `true`                        | Set `false` to disable the structured memory layer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `FILE_TOOLS_ENABLED`    | `true`                        | Set `false` to hide file tools when Obsidian Sync has attachment syncing disabled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `READONLY_MODE`         | `false`                       | Set `true` to hide every tool that changes the vault and skip memory folder auto-creation — read and search only                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `DISABLED_TOOLS`        | none hidden                   | Hide individual tools by name, comma-separated; names match the [README tools table](https://github.com/aliasunder/vault-cortex#tools)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `SYNC_CONFIGS`          | daily notes, plugins, and app | Obsidian settings categories synced to the server (see [Daily notes](#daily-notes)); `none` disables                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `INSTANCE_NAME`         | `vault-cortex`                | Names this install's container, Compose project and volumes. Set it before the first start to run another vault on the same server (see [Run more than one vault](#run-more-than-one-vault))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `DEVICE_NAME`           | `vault-cortex`                | The device name that labels this container's changes in Obsidian's sync log                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `SYNC_MODE`             | `bidirectional`               | Sync direction: `bidirectional`, `pull-only` (edits made on the server stay on the server and are never uploaded), or `mirror-remote` (Obsidian Sync overwrites edits made on the server, so the server always matches your vault). An invalid value stops the container at boot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `CONFLICT_STRATEGY`     | `merge`                       | Obsidian Sync conflict resolution: `merge` integrates changes automatically; `conflict` writes a separate conflict file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `SYNC_EXCLUDED_FOLDERS` | _(empty)_                     | Folders to leave out of sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Empty excludes nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `SYNC_FILE_TYPES`       | _(empty)_                     | Attachment types to sync, comma-separated — the same toggles as Obsidian's Sync → Selective sync. **Valid values:** `image`, `audio`, `video`, `pdf`, `unsupported`. **Empty (default):** `image,audio,video,pdf`. The text files Vault Cortex reads (CSV, JSON, TXT, XML, LOG, YAML) fall under `unsupported`, Obsidian Sync's name for its **Sync all other types** category; SVG syncs as `image`, and notes, canvases, and bases always sync. To read those text files, set it to `image,audio,video,pdf,unsupported` (the value replaces the default list, so keep the four defaults) and turn on **Sync all other types** in Obsidian's Sync settings on the device that has them. An invalid value is skipped with a warning in the logs, and the default types sync instead. |
-| `DAILY_NOTES_FOLDER`    | from vault config             | Sets the daily notes folder (see [Daily notes](#daily-notes))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `DAILY_NOTES_FORMAT`    | from vault config             | Sets the daily note filename format (see [Daily notes](#daily-notes))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `TRUST_PROXY_HOPS`      | `0`                           | Set `1` when a tunnel or reverse proxy fronts the server — OAuth rate limiting then buckets by the real client IP, not the proxy's                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `TRUST_FORWARDED_HOPS`  | `0`                           | How many trailing `for=` entries in the [RFC 7239](https://www.rfc-editor.org/rfc/rfc7239) `Forwarded` header belong to proxies you control. `0` ignores the header; `1` when the proxy in front writes it (e.g. AWS API Gateway); `2` when a CDN fronts that proxy and is the only way to reach it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `STORAGE_ROOT`          | —                             | One directory for everything that must persist, for hosting platforms that allow a single volume (see **Single persistent volume** under [Setup](#setup)). Must not contain `*`, `?`, or `[`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Setting                 | Default                       | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TZ`                    | `UTC`                         | Your IANA timezone (e.g. `America/New_York`) — affects daily note dates and timestamps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `VAULT_PASSWORD`        | —                             | Set this if your vault has end-to-end encryption enabled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `EMBEDDING_ENABLED`     | `true`                        | Set `false` to skip AI models (~59MB) and use keyword search only — saves memory on smaller instances                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `RERANK_MODE`           | `blended`                     | Set `none` to skip reranking for lower latency                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `MEMORY_ENABLED`        | `true`                        | Set `false` to disable the structured memory layer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `FILE_TOOLS_ENABLED`    | `true`                        | Set `false` to hide file tools when Obsidian Sync has attachment syncing disabled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `READONLY_MODE`         | `false`                       | Set `true` to hide every tool that changes the vault and skip memory folder auto-creation — read and search only                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `DISABLED_TOOLS`        | none hidden                   | Hide individual tools by name, comma-separated; names match the [README tools table](https://github.com/aliasunder/vault-cortex#tools)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `SYNC_CONFIGS`          | daily notes, plugins, and app | Obsidian settings categories synced to the server (see [Daily notes](#daily-notes)); `none` disables                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `INSTANCE_NAME`         | `vault-cortex`                | Names this install's container, Compose project and volumes. Set it before the first start to run another vault on the same server (see [Run more than one vault](#run-more-than-one-vault))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `DEVICE_NAME`           | `vault-cortex`                | The device name that labels this container's changes in Obsidian's sync log                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `SYNC_MODE`             | `bidirectional`               | Sync direction: `bidirectional`, `pull-only` (edits made on the server stay on the server and are never uploaded), or `mirror-remote` (Obsidian Sync overwrites edits made on the server, so the server always matches your vault). An invalid value stops the container at boot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `CONFLICT_STRATEGY`     | `merge`                       | Obsidian Sync conflict resolution: `merge` integrates changes automatically; `conflict` writes a separate conflict file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `SYNC_EXCLUDED_FOLDERS` | _(empty)_                     | Folders to leave out of sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Empty excludes nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `SYNC_FILE_TYPES`       | _(empty)_                     | Attachment types to sync, comma-separated — the same toggles as Obsidian's Sync → Selective sync. **Valid values:** `image`, `audio`, `video`, `pdf`, `unsupported`. **Empty (default):** `image,audio,video,pdf`. The text files Vault Cortex reads (CSV, JSON, TXT, HTML, scripts and other UTF-8 files) fall under `unsupported`, Obsidian Sync's name for its **Sync all other types** category; SVG syncs as `image`, and notes, canvases, and bases always sync. To read those text files, set it to `image,audio,video,pdf,unsupported` (the value replaces the default list, so keep the four defaults) and turn on **Sync all other types** in Obsidian's Sync settings on the device that has them. An invalid value is skipped with a warning in the logs, and the default types sync instead. |
+| `DAILY_NOTES_FOLDER`    | from vault config             | Sets the daily notes folder (see [Daily notes](#daily-notes))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `DAILY_NOTES_FORMAT`    | from vault config             | Sets the daily note filename format (see [Daily notes](#daily-notes))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `TRUST_PROXY_HOPS`      | `0`                           | Set `1` when a tunnel or reverse proxy fronts the server — OAuth rate limiting then buckets by the real client IP, not the proxy's                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `TRUST_FORWARDED_HOPS`  | `0`                           | How many trailing `for=` entries in the [RFC 7239](https://www.rfc-editor.org/rfc/rfc7239) `Forwarded` header belong to proxies you control. `0` ignores the header; `1` when the proxy in front writes it (e.g. AWS API Gateway); `2` when a CDN fronts that proxy and is the only way to reach it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `STORAGE_ROOT`          | —                             | One directory for everything that must persist, for hosting platforms that allow a single volume (see **Single persistent volume** under [Setup](#setup)). Must not contain `*`, `?`, or `[`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 
 All settings are documented in `.env.example` and in the
 [Configuration](../../README.md#configuration) section of the main README.
diff --git a/deploy/render/README.md b/deploy/render/README.md
index 9b4811c75..6dfbb2f8f 100644
--- a/deploy/render/README.md
+++ b/deploy/render/README.md
@@ -257,26 +257,26 @@ release lists what changed since the last one, and an entry marked
 The Blueprint sets these; change them under the service's **Environment**
 tab (each change triggers a redeploy):
 
-| Variable                | Value           | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `STORAGE_ROOT`          | `/persist`      | Where the disk is mounted — the vault, search index and its models, Sync device state, and logs live under it. Must not contain `*`, `?`, or `[`. Leave as is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `PORT`                  | `8000`          | The port the image listens on. Leave as is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `DEVICE_NAME`           | `vault-cortex`  | The device name that labels this container's changes in Obsidian's sync log.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `TRUST_PROXY_HOPS`      | `2`             | Render's network puts two proxies between a visitor and the container; this lets the server see the visitor's real address in its logs and rate limits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `MCP_AUTH_TOKEN`        | generated       | Your MCP client's token. Change it here to rotate it — every connected client re-authorizes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `OBSIDIAN_AUTH_TOKEN`   | from setup page | Obsidian Sync login. Set by the setup page on first deploy (written to the disk). To sign in with a different account, set a new token here — it always overrides the file on the disk.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `VAULT_NAME`            | yours           | The vault this container syncs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `VAULT_PASSWORD`        | yours / empty   | End-to-end encryption password, if your vault has one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `TZ`                    | yours / empty   | Timezone for daily notes, task due dates, and memory timestamps. Empty means UTC.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `MEMORY_ENABLED`        | `true`          | The About Me/ memory layer and its tools. Set `false` to hide them and skip creating the folder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `EMBEDDING_ENABLED`     | `true`          | Semantic search. Set `false` to skip the models and use keyword search only — the container fits in much less memory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `READONLY_MODE`         | `false`         | Set `true` to hide every tool that changes the vault — clients can only read and search.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `FILE_TOOLS_ENABLED`    | `true`          | `vault_read_file` and `vault_list_files`. Set `false` when Obsidian Sync has attachment syncing off.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `SYNC_MODE`             | `bidirectional` | Sync direction: `bidirectional`, `pull-only` (edits made on the server stay on the server and are never uploaded), or `mirror-remote` (Obsidian Sync overwrites edits made on the server, so the server always matches your vault). An invalid value stops the container at boot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `CONFLICT_STRATEGY`     | `merge`         | Obsidian Sync conflict resolution: `merge` integrates changes automatically; `conflict` writes a separate conflict file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `SYNC_EXCLUDED_FOLDERS` | _(empty)_       | Folders to leave out of sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Empty excludes nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `SYNC_FILE_TYPES`       | _(empty)_       | Attachment types to sync, comma-separated — the same toggles as Obsidian's Sync → Selective sync. **Valid values:** `image`, `audio`, `video`, `pdf`, `unsupported`. **Empty (default):** `image,audio,video,pdf`. The text files Vault Cortex reads (CSV, JSON, TXT, XML, LOG, YAML) fall under `unsupported`, Obsidian Sync's name for its **Sync all other types** category; SVG syncs as `image`, and notes, canvases, and bases always sync. To read those text files, set it to `image,audio,video,pdf,unsupported` (the value replaces the default list, so keep the four defaults) and turn on **Sync all other types** in Obsidian's Sync settings on the device that has them. An invalid value is skipped with a warning in the logs, and the default types sync instead. |
-| `LOG_DIR`               | derived         | Log files, kept 90 days on the disk — the platform's own log viewer keeps only the last 7 days on Hobby plans. Set `none` to keep logs in the platform viewer only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Variable                | Value           | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STORAGE_ROOT`          | `/persist`      | Where the disk is mounted — the vault, search index and its models, Sync device state, and logs live under it. Must not contain `*`, `?`, or `[`. Leave as is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `PORT`                  | `8000`          | The port the image listens on. Leave as is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `DEVICE_NAME`           | `vault-cortex`  | The device name that labels this container's changes in Obsidian's sync log.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `TRUST_PROXY_HOPS`      | `2`             | Render's network puts two proxies between a visitor and the container; this lets the server see the visitor's real address in its logs and rate limits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `MCP_AUTH_TOKEN`        | generated       | Your MCP client's token. Change it here to rotate it — every connected client re-authorizes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `OBSIDIAN_AUTH_TOKEN`   | from setup page | Obsidian Sync login. Set by the setup page on first deploy (written to the disk). To sign in with a different account, set a new token here — it always overrides the file on the disk.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `VAULT_NAME`            | yours           | The vault this container syncs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `VAULT_PASSWORD`        | yours / empty   | End-to-end encryption password, if your vault has one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `TZ`                    | yours / empty   | Timezone for daily notes, task due dates, and memory timestamps. Empty means UTC.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `MEMORY_ENABLED`        | `true`          | The About Me/ memory layer and its tools. Set `false` to hide them and skip creating the folder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `EMBEDDING_ENABLED`     | `true`          | Semantic search. Set `false` to skip the models and use keyword search only — the container fits in much less memory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `READONLY_MODE`         | `false`         | Set `true` to hide every tool that changes the vault — clients can only read and search.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `FILE_TOOLS_ENABLED`    | `true`          | `vault_read_file` and `vault_list_files`. Set `false` when Obsidian Sync has attachment syncing off.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `SYNC_MODE`             | `bidirectional` | Sync direction: `bidirectional`, `pull-only` (edits made on the server stay on the server and are never uploaded), or `mirror-remote` (Obsidian Sync overwrites edits made on the server, so the server always matches your vault). An invalid value stops the container at boot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `CONFLICT_STRATEGY`     | `merge`         | Obsidian Sync conflict resolution: `merge` integrates changes automatically; `conflict` writes a separate conflict file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `SYNC_EXCLUDED_FOLDERS` | _(empty)_       | Folders to leave out of sync, comma-separated — the same list as Obsidian's Sync → Excluded folders. Empty excludes nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `SYNC_FILE_TYPES`       | _(empty)_       | Attachment types to sync, comma-separated — the same toggles as Obsidian's Sync → Selective sync. **Valid values:** `image`, `audio`, `video`, `pdf`, `unsupported`. **Empty (default):** `image,audio,video,pdf`. The text files Vault Cortex reads (CSV, JSON, TXT, HTML, scripts and other UTF-8 files) fall under `unsupported`, Obsidian Sync's name for its **Sync all other types** category; SVG syncs as `image`, and notes, canvases, and bases always sync. To read those text files, set it to `image,audio,video,pdf,unsupported` (the value replaces the default list, so keep the four defaults) and turn on **Sync all other types** in Obsidian's Sync settings on the device that has them. An invalid value is skipped with a warning in the logs, and the default types sync instead. |
+| `LOG_DIR`               | derived         | Log files, kept 90 days on the disk — the platform's own log viewer keeps only the last 7 days on Hobby plans. Set `none` to keep logs in the platform viewer only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 
 `SYNC_MODE`, `CONFLICT_STRATEGY`, `SYNC_EXCLUDED_FOLDERS`, and
 `SYNC_FILE_TYPES` are the settings most worth changing on a hosted instance;
diff --git a/scripts/generate-dockerhub-readme.ts b/scripts/generate-dockerhub-readme.ts
index 55b35acc5..bb0b223b0 100644
--- a/scripts/generate-dockerhub-readme.ts
+++ b/scripts/generate-dockerhub-readme.ts
@@ -48,6 +48,7 @@ const EXCLUDED_H2 = new Set([
   "Hybrid Search",
   "Memory",
   "Tasks",
+  "Files",
   "Data Integrity",
   "Authentication",
   "Development",

From 46876fdcfba5aa16a92114b37d9e09f9e3fd4771 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 00:42:54 -0500
Subject: [PATCH 09/38] feat(tools): describe any-UTF-8 reads and HTML and
 script search

vault_read_file names any UTF-8 text file as readable, the binary-data
error, and search coverage of HTML pages and scripts; vault_list_files'
readable-types sentence drops its closing list; vault_search names HTML
pages and scripts among the file content it searches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../__snapshots__/tool-surface/default.json        |  8 ++++----
 .../__snapshots__/tool-surface/disabled-tools.json |  8 ++++----
 .../__snapshots__/tool-surface/embedding-off.json  |  8 ++++----
 .../tool-surface/memory-off+embedding-off.json     |  8 ++++----
 .../__snapshots__/tool-surface/memory-off.json     |  8 ++++----
 .../__snapshots__/tool-surface/obsidian-sync.json  |  8 ++++----
 .../tool-surface/readonly+embedding-off.json       |  8 ++++----
 .../readonly+memory-off+embedding-off.json         |  8 ++++----
 .../tool-surface/readonly+memory-off.json          |  8 ++++----
 .../__snapshots__/tool-surface/readonly.json       |  8 ++++----
 .../mcp-core/__tests__/tool-definitions.test.ts    |  7 ++++---
 src/vault-mcp/mcp-core/tools/asset-tools.ts        | 14 +++++++-------
 src/vault-mcp/mcp-core/tools/search-tools.ts       |  2 +-
 13 files changed, 52 insertions(+), 51 deletions(-)

diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
index b19b9b3d5..02c8ba3ac 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
@@ -486,7 +486,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1075,14 +1075,14 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, and text-format content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text format returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "path": {
             "type": "string",
             "minLength": 1,
-            "description": "Vault-relative path to the file, including its extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
+            "description": "Vault-relative path to the file, including any extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
           },
           "raw": {
             "description": "Return a canvas's or PDF's alternative form. Changes nothing for text formats.",
@@ -1313,7 +1313,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, and text files), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
index b223f92ee..7c879b127 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
@@ -488,7 +488,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1016,14 +1016,14 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, and text-format content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text format returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "path": {
             "type": "string",
             "minLength": 1,
-            "description": "Vault-relative path to the file, including its extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
+            "description": "Vault-relative path to the file, including any extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
           },
           "raw": {
             "description": "Return a canvas's or PDF's alternative form. Changes nothing for text formats.",
@@ -1254,7 +1254,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, and text files), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
index 98a9dd991..74c0daadd 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
@@ -488,7 +488,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1077,14 +1077,14 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, and text-format content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text format returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "path": {
             "type": "string",
             "minLength": 1,
-            "description": "Vault-relative path to the file, including its extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
+            "description": "Vault-relative path to the file, including any extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
           },
           "raw": {
             "description": "Return a canvas's or PDF's alternative form. Changes nothing for text formats.",
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, and text files), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
index c3b1eaca7..86a1b2038 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
@@ -406,7 +406,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -935,14 +935,14 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, and text-format content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text format returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "path": {
             "type": "string",
             "minLength": 1,
-            "description": "Vault-relative path to the file, including its extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
+            "description": "Vault-relative path to the file, including any extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
           },
           "raw": {
             "description": "Return a canvas's or PDF's alternative form. Changes nothing for text formats.",
@@ -1173,7 +1173,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, and text files), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
index d4a003225..af3714e8a 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
@@ -405,7 +405,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -934,14 +934,14 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, and text-format content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text format returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "path": {
             "type": "string",
             "minLength": 1,
-            "description": "Vault-relative path to the file, including its extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
+            "description": "Vault-relative path to the file, including any extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
           },
           "raw": {
             "description": "Return a canvas's or PDF's alternative form. Changes nothing for text formats.",
@@ -1172,7 +1172,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, and text files), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
index be12b400c..2de765651 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
@@ -488,7 +488,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1077,14 +1077,14 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, and text-format content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text format returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "path": {
             "type": "string",
             "minLength": 1,
-            "description": "Vault-relative path to the file, including its extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
+            "description": "Vault-relative path to the file, including any extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
           },
           "raw": {
             "description": "Return a canvas's or PDF's alternative form. Changes nothing for text formats.",
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, and text files), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
index 4eaeb73bb..8bd1b771f 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
@@ -165,7 +165,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -653,14 +653,14 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, and text-format content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text format returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "path": {
             "type": "string",
             "minLength": 1,
-            "description": "Vault-relative path to the file, including its extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
+            "description": "Vault-relative path to the file, including any extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
           },
           "raw": {
             "description": "Return a canvas's or PDF's alternative form. Changes nothing for text formats.",
@@ -795,7 +795,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, and text files), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
index 8d9cc6307..96bc9ed1a 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
@@ -130,7 +130,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -558,14 +558,14 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, and text-format content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text format returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "path": {
             "type": "string",
             "minLength": 1,
-            "description": "Vault-relative path to the file, including its extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
+            "description": "Vault-relative path to the file, including any extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
           },
           "raw": {
             "description": "Return a canvas's or PDF's alternative form. Changes nothing for text formats.",
@@ -700,7 +700,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, and text files), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
index 64e6a71d5..724736acc 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
@@ -129,7 +129,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -557,14 +557,14 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, and text-format content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text format returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "path": {
             "type": "string",
             "minLength": 1,
-            "description": "Vault-relative path to the file, including its extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
+            "description": "Vault-relative path to the file, including any extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
           },
           "raw": {
             "description": "Return a canvas's or PDF's alternative form. Changes nothing for text formats.",
@@ -699,7 +699,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, and text files), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
index 6a348a233..6e7cf1821 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
@@ -164,7 +164,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -652,14 +652,14 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, and text-format content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text format returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "path": {
             "type": "string",
             "minLength": 1,
-            "description": "Vault-relative path to the file, including its extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
+            "description": "Vault-relative path to the file, including any extension (e.g. \"attachments/photo.png\", \"Boards/Roadmap.canvas\"). Must NOT end in \".md\". Use the exact letter case."
           },
           "raw": {
             "description": "Return a canvas's or PDF's alternative form. Changes nothing for text formats.",
@@ -794,7 +794,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, and text files), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index c09bf4c4d..d558f3fe3 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1375,7 +1375,7 @@ describe("vault_search description reflects EMBEDDING_ENABLED", () => {
     const description = findSearchDescription(registerWithConfig({}))
     const openingSentence = description.slice(0, description.indexOf(". ") + 1)
     expect(openingSentence).toBe(
-      "Hybrid search across vault notes and file content (canvas, PDF, and text files), ranked by combined keyword and semantic relevance.",
+      "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance.",
     )
     expect(description).toContain("career aspirations")
     expect(description).toContain("search_mode")
@@ -1401,7 +1401,8 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   // off the description must not mention file content, the extension field,
   // or file results. Both embedding variants share this wording.
   const FILE_RESULT_WORDING = {
-    searchedScope: "search across vault notes and file content (canvas, PDF, and text files)",
+    searchedScope:
+      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts)",
     filtersLeadIn:
       "Filters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:",
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`,
@@ -3338,7 +3339,7 @@ describe("DISABLED_TOOLS", () => {
 
   it("vault_list_files contrasts itself with the note discovery tools while all three are served", () => {
     expect(listFilesWhenToUse("")).toBe(
-      "When to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.",
+      "When to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.",
     )
   })
 
diff --git a/src/vault-mcp/mcp-core/tools/asset-tools.ts b/src/vault-mcp/mcp-core/tools/asset-tools.ts
index 64b17c014..8e47a81fe 100644
--- a/src/vault-mcp/mcp-core/tools/asset-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/asset-tools.ts
@@ -95,7 +95,7 @@ export const registerAssetTools = ({
     TOOL_NAMES.VAULT_SEARCH,
   ].every(isToolEnabled)
   const listFilesContrastSentence = noteDiscoveryToolsServed
-    ? " vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, and text-format files, so this is the discovery surface for everything else."
+    ? " vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else."
     : " This is the discovery surface for every file that is not a markdown note."
 
   registerTool(
@@ -110,13 +110,13 @@ Example: vault_read_file({ path: "exports/data.json" }) — the file content as
 Example: vault_read_file({ path: "exports/big.csv", limit: 500 }) — the first 500 lines
 Example: vault_read_file({ path: "papers/research.pdf" }) — structured text with title, headings, and links
 
-When to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF.${whenToolEnabledText("vault_get_outgoing_links", " Find the files a note links to (with byte sizes) via vault_get_outgoing_links.")}${whenToolEnabledText("vault_list_files", " Browse a folder's files via vault_list_files.")}${whenToolEnabledText("vault_search", " vault_search also indexes canvas, PDF, and text-format content, but not images or other files.")}${whenToolEnabledText("vault_read_note", " For .md notes use vault_read_note.")} To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.
+When to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF.${whenToolEnabledText("vault_get_outgoing_links", " Find the files a note links to (with byte sizes) via vault_get_outgoing_links.")}${whenToolEnabledText("vault_list_files", " Browse a folder's files via vault_list_files.")}${whenToolEnabledText("vault_search", " vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files.")}${whenToolEnabledText("vault_read_note", " For .md notes use vault_read_note.")} To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.
 
 Parameters:
 - raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first ${config.maxPdfRenderPages} pages are rendered, and later pages are readable only as text, without raw.
 - start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.
 
-Behavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue ("data.csv — lines 51–100 of 400 (continue with start_line: 101)"); an unpaged read of a text format returns the file byte-exact.
+Behavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue ("data.csv — lines 51–100 of 400 (continue with start_line: 101)"); an unpaged read of a text file returns the file byte-exact.
 
 Errors:
 - "not a file: … is a markdown note" — the path ends in .md${whenToolEnabledText("vault_read_note", "; read notes with vault_read_note")}
@@ -136,19 +136,19 @@ ${PATH_SAFETY_ERROR_ENTRY}
 ${FILESYSTEM_ERROR_ENTRY}
 - "file changed while reading" — retry the read
 - "PDF reader could not start" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server
-- "unsupported file type …" — the type (audio, archives, …) is not readable; the error names the readable types plus the file's existence and size
+- "unsupported file type …" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text
 
 Returns: by file type:
 - Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (${config.maxImageOutputBytes} bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.
 - Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.
 - PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).
-- Text formats (.svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base): one text block holding the file content verbatim.`,
+- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.`,
       inputSchema: {
         path: z
           .string()
           .min(1)
           .describe(
-            'Vault-relative path to the file, including its extension (e.g. "attachments/photo.png", "Boards/Roadmap.canvas"). Must NOT end in ".md". Use the exact letter case.',
+            'Vault-relative path to the file, including any extension (e.g. "attachments/photo.png", "Boards/Roadmap.canvas"). Must NOT end in ".md". Use the exact letter case.',
           ),
         raw: z
           .boolean()
@@ -250,7 +250,7 @@ ${LISTING_FILESYSTEM_ERROR_ENTRY}.
 
 Returns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is "(none)" for a file without one), extension_counts (counts keyed by extension, e.g. { ".png": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).${whenToolEnabledText(
         "vault_read_file",
-        "\n\nReadable types: vault_read_file reads only images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and the text formats .svg/.json/.txt/.csv/.xml/.log/.yaml/.yml/.base.",
+        "\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       )}`,
       inputSchema: {
         folder: z
diff --git a/src/vault-mcp/mcp-core/tools/search-tools.ts b/src/vault-mcp/mcp-core/tools/search-tools.ts
index 7bfcf4995..a271e3cac 100644
--- a/src/vault-mcp/mcp-core/tools/search-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/search-tools.ts
@@ -84,7 +84,7 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   // File content is searched only while FILE_TOOLS_ENABLED is on, so the text
   // that mentions file results follows that setting, not any one tool
   const searchedContentText = config.fileToolsEnabled
-    ? "vault notes and file content (canvas, PDF, and text files)"
+    ? "vault notes and file content (canvas, PDF, text files, HTML pages, and scripts)"
     : "vault notes"
   const searchResultFieldsText = config.fileToolsEnabled
     ? `path, title, snippet, score, ${tagsFieldsText}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`

From 8507faa641683a730322fd87e0311aa08e980214 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 00:44:03 -0500
Subject: [PATCH 10/38] docs: list the file-kinds and html parsers in the
 AGENTS.md structure tree

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 3238d4d35..2639979b8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -88,7 +88,7 @@ src/
   __tests__/docker/ # :remote image boot tests (npm run test:remote-boot): docker-harness, and fixtures/ob, a stub of the obsidian-headless CLI
   vault-mcp/
     server.ts, config.ts # Entry point and env-var loader, the only loose files here
-    obsidian-markdown/ # Pure parsers and transforms with no I/O (pdf-engine excepted): lines, frontmatter, callouts, headings, links, tags, body-tags + obsidian-remark-parser + remark-ports/, tasks, recurrence, memory-entries, canvas, plaintext, pdf + pdf-engine, moment-format
+    obsidian-markdown/ # Pure parsers and transforms with no I/O (pdf-engine excepted): lines, frontmatter, callouts, headings, links, tags, body-tags + obsidian-remark-parser + remark-ports/, tasks, recurrence, memory-entries, canvas, file-kinds, html, plaintext, pdf + pdf-engine, moment-format
     vault-operations/ # Vault read, write, and patch: vault-filesystem (base I/O), vault-patcher, note-mover, memory-store, daily-notes, vault-folder-config, task-mutations, task-format-config, trash-config, trash-sweeper, asset-operations
     mcp-core/ # MCP protocol surface: mcp-router, tool-registry, tool-availability, tool-definitions, prompt-definitions, coded-error-remedy
       tools/ # One <domain>-tools module per data-layer domain (vault-crud, search, task, memory, daily-note, asset), plus tool-helpers

From ebb4b86e44370352d78d1d7f50a8861aa35ddb9f Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 01:25:34 -0500
Subject: [PATCH 11/38] fix(tools): name the searched file extensions and say
 scripts match by keyword

The file tools now name the extensions vault_search indexes, so 'text
format' has a referent once reads cover any UTF-8 file; the binary-data
error entry drops how the server detects binary data; vault_search says
scripts match by keyword only while semantic matching runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../__snapshots__/tool-surface/default.json      |  6 +++---
 .../tool-surface/disabled-tools.json             |  6 +++---
 .../tool-surface/embedding-off.json              |  4 ++--
 .../tool-surface/memory-off+embedding-off.json   |  4 ++--
 .../__snapshots__/tool-surface/memory-off.json   |  6 +++---
 .../tool-surface/obsidian-sync.json              |  6 +++---
 .../tool-surface/readonly+embedding-off.json     |  4 ++--
 .../readonly+memory-off+embedding-off.json       |  4 ++--
 .../tool-surface/readonly+memory-off.json        |  6 +++---
 .../__snapshots__/tool-surface/readonly.json     |  6 +++---
 .../mcp-core/__tests__/tool-definitions.test.ts  | 16 +++++++++++-----
 src/vault-mcp/mcp-core/tools/asset-tools.ts      |  6 +++---
 src/vault-mcp/mcp-core/tools/search-tools.ts     |  6 ++++--
 13 files changed, 44 insertions(+), 36 deletions(-)

diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
index 02c8ba3ac..4f37ee1df 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
@@ -486,7 +486,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1075,7 +1075,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1313,7 +1313,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
index 7c879b127..ba79cfba7 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
@@ -488,7 +488,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1016,7 +1016,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1254,7 +1254,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
index 74c0daadd..bac930cae 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
@@ -488,7 +488,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1077,7 +1077,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
index 86a1b2038..b4dc5e7fe 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
@@ -406,7 +406,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -935,7 +935,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
index af3714e8a..efd411799 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
@@ -405,7 +405,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -934,7 +934,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1172,7 +1172,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
index 2de765651..b4aeb7287 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
@@ -488,7 +488,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1077,7 +1077,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
index 8bd1b771f..db51ead4a 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
@@ -165,7 +165,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -653,7 +653,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
index 96bc9ed1a..36afa20c5 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
@@ -130,7 +130,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -558,7 +558,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
index 724736acc..2702f18a6 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
@@ -129,7 +129,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -557,7 +557,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -699,7 +699,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
index 6e7cf1821..eaa2af5ce 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
@@ -164,7 +164,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error.\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -652,7 +652,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -794,7 +794,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index d558f3fe3..af0c5a7a5 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1375,7 +1375,7 @@ describe("vault_search description reflects EMBEDDING_ENABLED", () => {
     const description = findSearchDescription(registerWithConfig({}))
     const openingSentence = description.slice(0, description.indexOf(". ") + 1)
     expect(openingSentence).toBe(
-      "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by combined keyword and semantic relevance.",
+      "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance.",
     )
     expect(description).toContain("career aspirations")
     expect(description).toContain("search_mode")
@@ -1399,10 +1399,11 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
 
   // Search indexes file content only while file tools are on, so with them
   // off the description must not mention file content, the extension field,
-  // or file results. Both embedding variants share this wording.
+  // or file results. Both embedding variants share this wording, except that
+  // only the hybrid variant says scripts match by keyword alone.
   const FILE_RESULT_WORDING = {
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts)",
+      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only)",
     filtersLeadIn:
       "Filters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:",
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`,
@@ -1415,6 +1416,11 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (top-level folder), type, kind, created, modified, bytes`,
     kindSentence: 'kind is always "note".',
   }
+  const KEYWORD_ONLY_FILE_RESULT_WORDING = {
+    ...FILE_RESULT_WORDING,
+    searchedScope:
+      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts)",
+  }
 
   it.each([
     {
@@ -1430,7 +1436,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
     {
       label: "advertises file results in the keyword-only variant while file tools are on",
       env: { EMBEDDING_ENABLED: "false" },
-      expectedWording: FILE_RESULT_WORDING,
+      expectedWording: KEYWORD_ONLY_FILE_RESULT_WORDING,
     },
     {
       label: "advertises notes only in the keyword-only variant when file tools are off",
@@ -3339,7 +3345,7 @@ describe("DISABLED_TOOLS", () => {
 
   it("vault_list_files contrasts itself with the note discovery tools while all three are served", () => {
     expect(listFilesWhenToUse("")).toBe(
-      "When to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.",
+      "When to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.",
     )
   })
 
diff --git a/src/vault-mcp/mcp-core/tools/asset-tools.ts b/src/vault-mcp/mcp-core/tools/asset-tools.ts
index 8e47a81fe..471174e37 100644
--- a/src/vault-mcp/mcp-core/tools/asset-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/asset-tools.ts
@@ -95,7 +95,7 @@ export const registerAssetTools = ({
     TOOL_NAMES.VAULT_SEARCH,
   ].every(isToolEnabled)
   const listFilesContrastSentence = noteDiscoveryToolsServed
-    ? " vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, text-format, HTML, and script files, so this is the discovery surface for everything else."
+    ? " vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else."
     : " This is the discovery surface for every file that is not a markdown note."
 
   registerTool(
@@ -110,7 +110,7 @@ Example: vault_read_file({ path: "exports/data.json" }) — the file content as
 Example: vault_read_file({ path: "exports/big.csv", limit: 500 }) — the first 500 lines
 Example: vault_read_file({ path: "papers/research.pdf" }) — structured text with title, headings, and links
 
-When to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF.${whenToolEnabledText("vault_get_outgoing_links", " Find the files a note links to (with byte sizes) via vault_get_outgoing_links.")}${whenToolEnabledText("vault_list_files", " Browse a folder's files via vault_list_files.")}${whenToolEnabledText("vault_search", " vault_search also indexes canvas, PDF, text-format, HTML, and script content, but not images or other files.")}${whenToolEnabledText("vault_read_note", " For .md notes use vault_read_note.")} To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.
+When to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF.${whenToolEnabledText("vault_get_outgoing_links", " Find the files a note links to (with byte sizes) via vault_get_outgoing_links.")}${whenToolEnabledText("vault_list_files", " Browse a folder's files via vault_list_files.")}${whenToolEnabledText("vault_search", " vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files.")}${whenToolEnabledText("vault_read_note", " For .md notes use vault_read_note.")} To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.
 
 Parameters:
 - raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first ${config.maxPdfRenderPages} pages are rendered, and later pages are readable only as text, without raw.
@@ -136,7 +136,7 @@ ${PATH_SAFETY_ERROR_ENTRY}
 ${FILESYSTEM_ERROR_ENTRY}
 - "file changed while reading" — retry the read
 - "PDF reader could not start" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server
-- "unsupported file type …" — the file holds binary data (audio, archives, UTF-16 text, …), found by a NUL byte in its first 8,000 bytes; the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text
+- "unsupported file type …" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text
 
 Returns: by file type:
 - Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (${config.maxImageOutputBytes} bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.
diff --git a/src/vault-mcp/mcp-core/tools/search-tools.ts b/src/vault-mcp/mcp-core/tools/search-tools.ts
index a271e3cac..92be50405 100644
--- a/src/vault-mcp/mcp-core/tools/search-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/search-tools.ts
@@ -82,9 +82,11 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   ])
 
   // File content is searched only while FILE_TOOLS_ENABLED is on, so the text
-  // that mentions file results follows that setting, not any one tool
+  // that mentions file results follows that setting, not any one tool. Scripts
+  // are never embedded, which matters to a caller only while semantic matching runs.
+  const scriptMatchClause = config.embeddingEnabled ? ", which match by keyword only" : ""
   const searchedContentText = config.fileToolsEnabled
-    ? "vault notes and file content (canvas, PDF, text files, HTML pages, and scripts)"
+    ? `vault notes and file content (canvas, PDF, text files, HTML pages, and scripts${scriptMatchClause})`
     : "vault notes"
   const searchResultFieldsText = config.fileToolsEnabled
     ? `path, title, snippet, score, ${tagsFieldsText}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`

From 8db118a16e62550ded78563ce88a78833640b91c Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 01:35:00 -0500
Subject: [PATCH 12/38] fix(tools): name scripts as the subject of the
 keyword-only clause

The searched-extension lists in the file tools now come from the
file-kind map, so they follow it when a type is added.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../__snapshots__/tool-surface/default.json         |  2 +-
 .../__snapshots__/tool-surface/disabled-tools.json  |  2 +-
 .../__snapshots__/tool-surface/memory-off.json      |  2 +-
 .../__snapshots__/tool-surface/obsidian-sync.json   |  2 +-
 .../tool-surface/readonly+memory-off.json           |  2 +-
 .../__snapshots__/tool-surface/readonly.json        |  2 +-
 .../mcp-core/__tests__/tool-definitions.test.ts     |  4 ++--
 src/vault-mcp/mcp-core/tools/asset-tools.ts         | 13 +++++++++++--
 src/vault-mcp/mcp-core/tools/search-tools.ts        |  2 +-
 9 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
index 4f37ee1df..efabf8363 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
@@ -1313,7 +1313,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
index ba79cfba7..672a2ba63 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
@@ -1254,7 +1254,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
index efd411799..7e4843515 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
@@ -1172,7 +1172,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
index b4aeb7287..2a159b59a 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
index 2702f18a6..01d3c48ab 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
@@ -699,7 +699,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
index eaa2af5ce..4d0750fee 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
@@ -794,7 +794,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index af0c5a7a5..bb1e767bb 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1375,7 +1375,7 @@ describe("vault_search description reflects EMBEDDING_ENABLED", () => {
     const description = findSearchDescription(registerWithConfig({}))
     const openingSentence = description.slice(0, description.indexOf(". ") + 1)
     expect(openingSentence).toBe(
-      "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only), ranked by combined keyword and semantic relevance.",
+      "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
     )
     expect(description).toContain("career aspirations")
     expect(description).toContain("search_mode")
@@ -1403,7 +1403,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   // only the hybrid variant says scripts match by keyword alone.
   const FILE_RESULT_WORDING = {
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts, which match by keyword only)",
+      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only)",
     filtersLeadIn:
       "Filters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:",
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`,
diff --git a/src/vault-mcp/mcp-core/tools/asset-tools.ts b/src/vault-mcp/mcp-core/tools/asset-tools.ts
index 471174e37..836673a94 100644
--- a/src/vault-mcp/mcp-core/tools/asset-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/asset-tools.ts
@@ -5,6 +5,8 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"
 import { assetOperations } from "../../vault-operations/asset-operations.js"
 import type { AssetReadResult } from "../../vault-operations/asset-operations.js"
 import type { FittedImage } from "../../../utils/fit-image-to-byte-budget.js"
+import { getExtensionsOfKind } from "../../obsidian-markdown/file-kinds.js"
+import type { FileKind } from "../../obsidian-markdown/file-kinds.js"
 import { TOOL_NAMES } from "../tool-registry.js"
 import type { ToolRegistrationContext } from "./tool-helpers.js"
 import {
@@ -77,6 +79,10 @@ const formatAssetReadResult = (result: AssetReadResult): CallToolResult["content
   }
 }
 
+/** A file kind's extensions as the tool text writes them (".html/.htm"), read
+ *  from the file-kind map so the text follows it when a type is added. */
+const formatExtensionsOfKind = (kind: FileKind): string => getExtensionsOfKind(kind).join("/")
+
 export const registerAssetTools = ({
   registerTool,
   safeHandler,
@@ -94,8 +100,11 @@ export const registerAssetTools = ({
     TOOL_NAMES.VAULT_SEARCH_BY_FOLDER,
     TOOL_NAMES.VAULT_SEARCH,
   ].every(isToolEnabled)
+  const htmlExtensions = formatExtensionsOfKind("html")
+  const scriptExtensions = formatExtensionsOfKind("script")
+  const textExtensions = formatExtensionsOfKind("text")
   const listFilesContrastSentence = noteDiscoveryToolsServed
-    ? " vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else."
+    ? ` vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (${htmlExtensions}), script (${scriptExtensions}), and ${textExtensions} files, so this is the discovery surface for everything else.`
     : " This is the discovery surface for every file that is not a markdown note."
 
   registerTool(
@@ -110,7 +119,7 @@ Example: vault_read_file({ path: "exports/data.json" }) — the file content as
 Example: vault_read_file({ path: "exports/big.csv", limit: 500 }) — the first 500 lines
 Example: vault_read_file({ path: "papers/research.pdf" }) — structured text with title, headings, and links
 
-When to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF.${whenToolEnabledText("vault_get_outgoing_links", " Find the files a note links to (with byte sizes) via vault_get_outgoing_links.")}${whenToolEnabledText("vault_list_files", " Browse a folder's files via vault_list_files.")}${whenToolEnabledText("vault_search", " vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files.")}${whenToolEnabledText("vault_read_note", " For .md notes use vault_read_note.")} To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.
+When to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF.${whenToolEnabledText("vault_get_outgoing_links", " Find the files a note links to (with byte sizes) via vault_get_outgoing_links.")}${whenToolEnabledText("vault_list_files", " Browse a folder's files via vault_list_files.")}${whenToolEnabledText("vault_search", ` vault_search also indexes the content of canvases, PDFs, HTML pages (${htmlExtensions}), scripts (${scriptExtensions}), and the text formats ${textExtensions}, but not images or other files.`)}${whenToolEnabledText("vault_read_note", " For .md notes use vault_read_note.")} To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.
 
 Parameters:
 - raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first ${config.maxPdfRenderPages} pages are rendered, and later pages are readable only as text, without raw.
diff --git a/src/vault-mcp/mcp-core/tools/search-tools.ts b/src/vault-mcp/mcp-core/tools/search-tools.ts
index 92be50405..17f519744 100644
--- a/src/vault-mcp/mcp-core/tools/search-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/search-tools.ts
@@ -84,7 +84,7 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   // File content is searched only while FILE_TOOLS_ENABLED is on, so the text
   // that mentions file results follows that setting, not any one tool. Scripts
   // are never embedded, which matters to a caller only while semantic matching runs.
-  const scriptMatchClause = config.embeddingEnabled ? ", which match by keyword only" : ""
+  const scriptMatchClause = config.embeddingEnabled ? "; scripts match by keyword only" : ""
   const searchedContentText = config.fileToolsEnabled
     ? `vault notes and file content (canvas, PDF, text files, HTML pages, and scripts${scriptMatchClause})`
     : "vault notes"

From b6895fff416b0272b314e7f18f3b92570bab48b6 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 01:47:59 -0500
Subject: [PATCH 13/38] fix(review): skip an undecodable page or script in the
 rebuild, scope the file-kind claim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The rebuild decoded an HTML page or script outside the try that skips an
unreadable file, so text past V8's string limit would fail the whole
rebuild. ARCHITECTURE.md said every extension check goes through
file-kinds.ts; the .md note checks do not.

Ship-Check: pr-review · claude-opus-5-5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                      | 2 +-
 src/vault-mcp/search/search-index.ts | 6 ++++--
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 891171f58..61a6d6a1d 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -345,7 +345,7 @@ Link queries use a `links` table populated during indexing:
 | `vault_read_file`  | `path, raw?, start_line?, limit?` | readOnlyHint |
 | `vault_list_files` | `folder?, extensions?, limit?`    | readOnlyHint |
 
-`vault_read_file` reads non-markdown vault files, dispatching on the file's kind to the most useful representation per type. `obsidian-markdown/file-kinds.ts` maps the lowercased extension to a kind, so `Report.PDF` is a PDF; every extension check in reads, indexing, the note mover and the link tools goes through it:
+`vault_read_file` reads non-markdown vault files, dispatching on the file's kind to the most useful representation per type. `obsidian-markdown/file-kinds.ts` maps the lowercased extension to a kind, so `Report.PDF` is a PDF; every file-kind check in reads, indexing, the note mover and the link tools goes through it:
 
 1. **Images** (`.png`/`.jpg`/`.jpeg`/`.gif`/`.webp`) return an MCP `image` content block plus a one-line metadata text block: the path, the delivered format, dimensions and bytes, and, when the image was recompressed, its original dimensions and bytes. A shared fit-to-byte-budget pipeline (`utils/fit-image-to-byte-budget.ts`, built on sharp) makes oversized images deliverable: EXIF auto-orient → resize long edge to ≤1568px → walk a fixed quality ladder (JPEG via mozjpeg for opaque images, WebP for alpha — PNG has no quality knob) → shrink dimensions by √(budget/actual) if the ladder floor still exceeds the budget. Deterministic and terminating (bounded attempts, 64px floor); sharp's default `limitInputPixels` stays active as the decompression-bomb guard. The budget (`MAX_IMAGE_OUTPUT_BYTES`, default 48 KiB binary) is sized for the tightest mainstream client cap.
 2. **Canvas** (`.canvas`) linearizes to markdown via the pure `obsidian-markdown/canvas.ts` parser ([JSON Canvas 1.0](https://jsoncanvas.org)): group membership by spatial rect containment (innermost group wins; equal rects tiebreak deterministically by id), nodes in reading order (y, then x), and an edge list with node ids resolved to display names. Lenient parsing — unknown properties ignored, malformed entries skipped. `raw: true` skips the linearizer and returns the JSON source verbatim for full structural fidelity. Canvas content is also FTS-indexed (linearized text in `file_content` + `file_content_fts` tables, gated behind `FILE_TOOLS_ENABLED`) so canvas files appear in `vault_search` results with `kind: "file"`. Canvas `file`-type node references are extracted unconditionally into the `links` table for graph queries regardless of the feature gate.
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index 8a681d91b..f9267515f 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -2434,13 +2434,15 @@ export const createSearchIndex = (
     const readDecodedSourceFile = async (
       file: RebuildFilePaths,
     ): Promise<RebuildFileContent | null> => {
+      // Decoding throws on text longer than V8's string limit, so it shares the
+      // read's try, and one such file is skipped rather than failing the rebuild.
       const readSource = async () => {
         try {
           const [buffer, fileStat] = await Promise.all([
             readFile(file.absolutePath),
             stat(file.absolutePath),
           ])
-          return { buffer, fileStat }
+          return { decodedSource: decodeTextBuffer(buffer), fileStat }
         } catch (error) {
           logger.warn("skipped unreadable file during rebuild", {
             path: file.relativePath,
@@ -2453,7 +2455,7 @@ export const createSearchIndex = (
 
       if (!source) return null
 
-      const decodedSource = decodeTextBuffer(source.buffer)
+      const { decodedSource } = source
 
       switch (decodedSource.status) {
         case "text":

From dd3b423491403c9d24d174a118e89b45d384e0e2 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 02:07:40 -0500
Subject: [PATCH 14/38] style: name the HTML and file-read state, correct stale
 and over-claimed comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- html.ts: name the leading and trailing whitespace gaps, state why emit
  can pause a tokenizer declared below it, and correct the end() comment
- asset-operations: one byte-cap check for whole and paged reads, one
  not-UTF-8 message, and the full read asset passed to the source reader
- search-index: fileTextToIndexedText, html/script reader names, the
  HTML size cap's rationale without an invented 2-second rule, and the
  stale or misplaced comments around file indexing
- file-watcher, hybrid-search, search-queries, note-mover: clearer
  constant, parameter and helper names, block bodies, and comment fixes
- asset-tools: image extensions and the text cap read from their sources
- generate-dockerhub-readme: drop the dead skip-level state and the
  no-op slash escape; name the size-warning margin
- ARCHITECTURE.md: scope the file-kind claim to non-markdown files, say
  text formats index leniently, and list HTML and scripts in pass 2

Ship-Check: code-quality · claude-opus-5-5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                               |  12 +-
 scripts/generate-dockerhub-readme.ts          |  95 +++++++-------
 src/vault-mcp/mcp-core/tools/asset-tools.ts   |   9 +-
 src/vault-mcp/obsidian-markdown/html.ts       |  19 ++-
 src/vault-mcp/search/file-watcher.ts          |  18 +--
 src/vault-mcp/search/hybrid-search.ts         |  18 +--
 src/vault-mcp/search/search-helpers.ts        |   2 +-
 src/vault-mcp/search/search-index.ts          | 107 ++++++++--------
 src/vault-mcp/search/search-queries.ts        |  26 ++--
 .../vault-operations/asset-operations.ts      |  66 +++++-----
 src/vault-mcp/vault-operations/note-mover.ts  | 119 ++++++++++--------
 11 files changed, 256 insertions(+), 235 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 61a6d6a1d..4324e6097 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -345,7 +345,7 @@ Link queries use a `links` table populated during indexing:
 | `vault_read_file`  | `path, raw?, start_line?, limit?` | readOnlyHint |
 | `vault_list_files` | `folder?, extensions?, limit?`    | readOnlyHint |
 
-`vault_read_file` reads non-markdown vault files, dispatching on the file's kind to the most useful representation per type. `obsidian-markdown/file-kinds.ts` maps the lowercased extension to a kind, so `Report.PDF` is a PDF; every file-kind check in reads, indexing, the note mover and the link tools goes through it:
+`vault_read_file` reads non-markdown vault files, dispatching on the file's kind to the most useful representation per type. `obsidian-markdown/file-kinds.ts` maps the lowercased extension to a kind, so `Report.PDF` is a PDF. Reads, indexing, the note mover and the link tools take every non-markdown file's kind from it:
 
 1. **Images** (`.png`/`.jpg`/`.jpeg`/`.gif`/`.webp`) return an MCP `image` content block plus a one-line metadata text block: the path, the delivered format, dimensions and bytes, and, when the image was recompressed, its original dimensions and bytes. A shared fit-to-byte-budget pipeline (`utils/fit-image-to-byte-budget.ts`, built on sharp) makes oversized images deliverable: EXIF auto-orient → resize long edge to ≤1568px → walk a fixed quality ladder (JPEG via mozjpeg for opaque images, WebP for alpha — PNG has no quality knob) → shrink dimensions by √(budget/actual) if the ladder floor still exceeds the budget. Deterministic and terminating (bounded attempts, 64px floor); sharp's default `limitInputPixels` stays active as the decompression-bomb guard. The budget (`MAX_IMAGE_OUTPUT_BYTES`, default 48 KiB binary) is sized for the tightest mainstream client cap.
 2. **Canvas** (`.canvas`) linearizes to markdown via the pure `obsidian-markdown/canvas.ts` parser ([JSON Canvas 1.0](https://jsoncanvas.org)): group membership by spatial rect containment (innermost group wins; equal rects tiebreak deterministically by id), nodes in reading order (y, then x), and an edge list with node ids resolved to display names. Lenient parsing — unknown properties ignored, malformed entries skipped. `raw: true` skips the linearizer and returns the JSON source verbatim for full structural fidelity. Canvas content is also FTS-indexed (linearized text in `file_content` + `file_content_fts` tables, gated behind `FILE_TOOLS_ENABLED`) so canvas files appear in `vault_search` results with `kind: "file"`. Canvas `file`-type node references are extracted unconditionally into the `links` table for graph queries regardless of the feature gate.
@@ -378,12 +378,12 @@ Search indexes file content in the `file_content` + `file_content_fts` tables, c
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
 | Canvas                       | Linearized outline; file cards also go to the link graph (see Canvas above)                                       | Yes      |
 | PDF                          | Text extracted by `obsidian-markdown/pdf.ts`; a scanned or image-only PDF has none and is found by file name only | Yes      |
-| Text formats (item 3)        | The file's UTF-8 content                                                                                          | Yes      |
+| Text formats (item 3)        | The file's content, with bytes that are not UTF-8 replaced rather than refused                                    | Yes      |
 | HTML (`.html`/`.htm`)        | The text a browser shows, from `obsidian-markdown/html.ts`; a page over 16 MiB is found by file name only         | Yes      |
 | Scripts (`.py`/`.sh`/`.ps1`) | The file's source                                                                                                 | No       |
 
-- **HTML extraction** runs htmlparser2's tokenizer, which keeps no element stack, so unclosed tags cost no more than closed ones. Hidden elements (script, style, noscript, template, and the fallback content of iframe, noembed and noframes) end only at a closing tag with their own name, so a stray closing tag never shows hidden text. Block elements become line breaks, other whitespace collapses, and reading stops at the 100 KiB cap. Extraction stays on the main thread; the 16 MiB page limit keeps its measured worst case under the 2-second bar for moving a parser to a worker.
-- **HTML pages and scripts are read as bytes** and indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds text a read refuses. When a watched page or script stops passing it, its stored content is removed and its file row stays.
+- **HTML extraction** runs htmlparser2's tokenizer, which keeps no element stack, so unclosed tags cost no more than closed ones. Hidden elements (script, style, noscript, template, and the fallback content of iframe, noembed and noframes) end only at a closing tag with their own name, so a stray closing tag never shows hidden text. Block elements become line breaks, other whitespace collapses, and reading stops at the 100 KiB cap. Extraction stays on the main thread, and the 16 MiB page limit keeps its measured worst case under 2 seconds.
+- **HTML pages and scripts are read as bytes** and indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds a page or script that a read refuses. When a watched page or script stops passing it, its stored content is removed and its file row stays.
 - **Scripts are searched by keyword only.** The markdown chunker reads a script's `# comment` lines as headings and turns `snake_case` names into one word, so embedding skips scripts before their text loads.
 
 **Opt-out:** File tools are opt-out: set `FILE_TOOLS_ENABLED=false` to hide `vault_read_file` and `vault_list_files`, and strip file tool references from server metadata and other tool descriptions. The `vault_get_outgoing_links` tool continues to report file links (it indexes from the links table, not the file tools). File config vars (`MAX_FILE_BYTES`, `MAX_IMAGE_OUTPUT_BYTES`, `MAX_PDF_RENDER_PAGES`) are still parsed when disabled.
@@ -536,7 +536,7 @@ When no embedder is configured (`EMBEDDING_ENABLED=false`), no vectors are index
 **Indexing flow:** `rebuildFromVault` runs passes 1 and 2, then returns while pass 3 and the body-tag pass run in the background:
 
 1. **Pass 1** — index notes (FTS5 + metadata), each with the body tags stored before the rebuild
-2. **Pass 2** — extract links (with the complete path list for resolution), then index file content (canvas, PDF, text → FTS5)
+2. **Pass 2** — extract links (with the complete path list for resolution), then index file content (canvas, PDF, text, HTML, scripts → FTS5)
 3. **Pass 3 (background)** — embed notes, then file content. Until a note's vectors exist, search finds it by keyword only
 4. **Body-tag pass (background)** — parse each note's body tags again in the body-tag worker thread and write the ones that changed (see **Body tags column**)
 
@@ -595,7 +595,7 @@ flowchart TD
     VF[Vault Files] --> RB[rebuildFromVault]
     RB --> P1[Pass 1: Index Notes\nFTS5 + metadata]
     P1 --> P2[Pass 2: Extract Links\nresolve with full path list]
-    P2 --> FC[Index File Content\ncanvas + PDF + text → FTS5]
+    P2 --> FC[Index File Content\ncanvas + PDF + text\n+ HTML + scripts → FTS5]
     FC --> P3[Pass 3: Embed Notes\nchunk → hash → embed → store]
     P3 --> P3F[Embed File Content\nchunk → hash → embed → store]
     FC --> BTP[Body-Tag Pass\nparse in worker → write changed tags]
diff --git a/scripts/generate-dockerhub-readme.ts b/scripts/generate-dockerhub-readme.ts
index bb0b223b0..482ea8e78 100644
--- a/scripts/generate-dockerhub-readme.ts
+++ b/scripts/generate-dockerhub-readme.ts
@@ -61,6 +61,13 @@ const EXCLUDED_H2 = new Set([
 
 const REPLACED_H2 = new Set(["License"])
 
+/** Docker Hub truncates a repository description past this many bytes. */
+const DOCKER_HUB_CAP_BYTES = 25_000
+
+/** The run warns 1,000 bytes before the cap, so a README edit that brings the
+ *  output close to it is flagged while there is still room to trim. */
+const SIZE_WARNING_BYTES = DOCKER_HUB_CAP_BYTES - 1_000
+
 // Sections where we keep only the heading, intro sentence, and tables — strip
 // verbose paragraphs that add bulk without adding Docker Hub value
 const COMPACT_H2 = new Set(["Properties", "Configuration", "Deployment Options"])
@@ -82,10 +89,7 @@ const rewriteUrls = (line: string): string => {
   result = result.replace(/\]\(\.\/assets\//g, `](${GITHUB_RAW}/assets/`)
 
   for (const dir of DIRECTORY_PATHS) {
-    result = result.replace(
-      new RegExp(`\\]\\(\\./${dir.replace("/", "\\/")}`, "g"),
-      `](${GITHUB_REPO}/tree/main/${dir}`,
-    )
+    result = result.replaceAll(`](./${dir}`, `](${GITHUB_REPO}/tree/main/${dir}`)
   }
 
   result = result.replace(/\]\(\.\//g, `](${GITHUB_REPO}/blob/main/`)
@@ -105,8 +109,7 @@ const compressTableRow = (line: string): string => {
   return cells.join(" | ").trim()
 }
 
-const isContentsLine = (line: string): boolean =>
-  line.startsWith("**Contents**") || line.startsWith("**Contents** —")
+const isContentsLine = (line: string): boolean => line.startsWith("**Contents**")
 
 /** DeepWiki documents the source repo, not the image, and the badge's raw
  *  GitHub URL would push DOCKERHUB.md past Docker Hub's 25000-byte cap. */
@@ -127,10 +130,9 @@ const generate = (): void => {
   let insideFence = false
   let insideDetails = false
   let skipSection = false
-  let skipLevel = 0
   let insertedNotice = false
   let compactSection = false
-  let compactTableDone = false
+  let droppingPostTableProse = false
 
   for (const line of lines) {
     if (line.startsWith("```")) {
@@ -159,62 +161,53 @@ const generate = (): void => {
 
     const heading = parseHeading(line)
 
-    if (heading) {
-      if (heading.level === 2) {
-        if (EXCLUDED_H2.has(heading.text)) {
-          skipSection = true
-          skipLevel = 2
-          if (heading.text === "Quick Start") {
-            output.push(...QUICKSTART_REDIRECT)
-          }
-          continue
-        }
-
-        if (REPLACED_H2.has(heading.text)) {
-          skipSection = true
-          skipLevel = 2
-          output.push(...LICENSE_REPLACEMENT)
-          continue
+    // An H2 decides whether its whole section, H3 subsections included, is
+    // skipped, and only the next H2 ends a skip
+    if (heading?.level === 2) {
+      if (EXCLUDED_H2.has(heading.text)) {
+        skipSection = true
+        if (heading.text === "Quick Start") {
+          output.push(...QUICKSTART_REDIRECT)
         }
-
-        skipSection = false
-        skipLevel = 0
-        compactSection = COMPACT_H2.has(heading.text)
-        compactTableDone = false
-      } else if (heading.level === 3) {
-        if (skipSection && skipLevel === 2) continue
-        // Compact sections keep only the heading, intro, and tables — an H3
-        // subsection's prose is already dropped below, so dropping the
-        // heading too avoids publishing an empty section title.
-        if (compactSection) continue
+        continue
       }
-    }
 
-    if (skipSection) {
-      if (heading && heading.level <= skipLevel) {
-        skipSection = false
-        skipLevel = 0
-      } else {
+      if (REPLACED_H2.has(heading.text)) {
+        skipSection = true
+        output.push(...LICENSE_REPLACEMENT)
         continue
       }
+
+      skipSection = false
+      compactSection = COMPACT_H2.has(heading.text)
+      droppingPostTableProse = false
     }
 
-    // In compact sections, keep heading + intro + tables, drop post-table prose
+    if (skipSection) continue
+
+    // Compact sections keep only the heading, intro, and tables — an H3
+    // subsection's prose is already dropped below, so dropping the
+    // heading too avoids publishing an empty section title.
+    if (heading?.level === 3 && compactSection) continue
+
+    // In compact sections, keep heading + intro + tables. The first non-blank
+    // line after a table starts dropping prose, until the next table row.
     if (compactSection && !heading) {
       const isTableRow = line.startsWith("|")
 
       if (isTableRow) {
-        compactTableDone = false
-      } else if (compactTableDone) {
+        droppingPostTableProse = false
+      } else if (droppingPostTableProse) {
         continue
       } else if (line.trim() !== "") {
-        const lastTableIdx = output.findLastIndex((outputLine) => outputLine.startsWith("|"))
-        const lastHeadingIdx = output.findLastIndex(
+        const lastTableIndex = output.findLastIndex((outputLine) => outputLine.startsWith("|"))
+        const lastHeadingIndex = output.findLastIndex(
           (outputLine) => parseHeading(outputLine) !== undefined,
         )
+        const followsSectionTable = lastTableIndex > lastHeadingIndex
 
-        if (lastTableIdx > lastHeadingIdx) {
-          compactTableDone = true
+        if (followsSectionTable) {
+          droppingPostTableProse = true
           continue
         }
       }
@@ -255,8 +248,10 @@ const generate = (): void => {
   writeFileSync(resolvePath("DOCKERHUB.md"), content, "utf-8")
 
   console.log(`generated DOCKERHUB.md (${byteCount} bytes)`)
-  if (byteCount > 24_000) {
-    console.warn(`warning: output is ${byteCount} bytes — Docker Hub truncates at 25000`)
+  if (byteCount > SIZE_WARNING_BYTES) {
+    console.warn(
+      `warning: output is ${byteCount} bytes — Docker Hub truncates at ${DOCKER_HUB_CAP_BYTES}`,
+    )
   }
 }
 
diff --git a/src/vault-mcp/mcp-core/tools/asset-tools.ts b/src/vault-mcp/mcp-core/tools/asset-tools.ts
index 836673a94..49fb47d22 100644
--- a/src/vault-mcp/mcp-core/tools/asset-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/asset-tools.ts
@@ -2,7 +2,7 @@
 
 import { z } from "zod"
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"
-import { assetOperations } from "../../vault-operations/asset-operations.js"
+import { assetOperations, MAX_TEXT_OUTPUT_BYTES } from "../../vault-operations/asset-operations.js"
 import type { AssetReadResult } from "../../vault-operations/asset-operations.js"
 import type { FittedImage } from "../../../utils/fit-image-to-byte-budget.js"
 import { getExtensionsOfKind } from "../../obsidian-markdown/file-kinds.js"
@@ -100,6 +100,7 @@ export const registerAssetTools = ({
     TOOL_NAMES.VAULT_SEARCH_BY_FOLDER,
     TOOL_NAMES.VAULT_SEARCH,
   ].every(isToolEnabled)
+  const imageExtensions = formatExtensionsOfKind("image")
   const htmlExtensions = formatExtensionsOfKind("html")
   const scriptExtensions = formatExtensionsOfKind("script")
   const textExtensions = formatExtensionsOfKind("text")
@@ -123,7 +124,7 @@ When to use: whenever a note references a file you need to actually see or read
 
 Parameters:
 - raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first ${config.maxPdfRenderPages} pages are rendered, and later pages are readable only as text, without raw.
-- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.
+- start_line and limit page any text result as a line window. The text output cap (a fixed ${MAX_TEXT_OUTPUT_BYTES / 1024} KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.
 
 Behavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue ("data.csv — lines 51–100 of 400 (continue with start_line: 101)"); an unpaged read of a text file returns the file byte-exact.
 
@@ -148,7 +149,7 @@ ${FILESYSTEM_ERROR_ENTRY}
 - "unsupported file type …" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text
 
 Returns: by file type:
-- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (${config.maxImageOutputBytes} bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.
+- Images (${imageExtensions}): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (${config.maxImageOutputBytes} bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.
 - Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.
 - PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).
 - Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.`,
@@ -259,7 +260,7 @@ ${LISTING_FILESYSTEM_ERROR_ENTRY}.
 
 Returns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is "(none)" for a file without one), extension_counts (counts keyed by extension, e.g. { ".png": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).${whenToolEnabledText(
         "vault_read_file",
-        "\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+        `\n\nReadable types: vault_read_file reads images (${imageExtensions}), .canvas, .pdf, and any UTF-8 text file.`,
       )}`,
       inputSchema: {
         folder: z
diff --git a/src/vault-mcp/obsidian-markdown/html.ts b/src/vault-mcp/obsidian-markdown/html.ts
index 66bf24df7..02e9eddd0 100644
--- a/src/vault-mcp/obsidian-markdown/html.ts
+++ b/src/vault-mcp/obsidian-markdown/html.ts
@@ -72,7 +72,7 @@ const ignoreToken = (): void => {}
  * comments dropped, entities decoded, one line per block element, and every
  * other run of whitespace collapsed to one space.
  * - Reading stops once the text reaches `maxBytes` of UTF-8, so the result can
- *   run past it by up to one text section; the caller cuts it to size.
+ *   run past it by up to the text between two tags; the caller cuts it to size.
  * - The tokenizer keeps no element stack, so unclosed tags cost no more than
  *   closed ones and the time stays linear in the page's size.
  * - A hidden element ends only at a closing tag with its own name, so a stray
@@ -94,6 +94,7 @@ export const extractHtmlVisibleText = (params: { html: string; maxBytes: number
     textParts.push(text)
     textBytes += Buffer.byteLength(text, "utf8")
 
+    // emit runs only inside tokenizer.write below, so `tokenizer` exists by then
     if (textBytes >= maxBytes) tokenizer.pause()
   }
 
@@ -102,15 +103,21 @@ export const extractHtmlVisibleText = (params: { html: string; maxBytes: number
 
     const collapsedText = text.replace(WHITESPACE_RUN, " ")
     const words = collapsedText.trim()
+    const hasLeadingGap = collapsedText.startsWith(" ")
+    const hasTrailingGap = collapsedText.endsWith(" ")
 
     if (!words) {
-      spaceOwed = spaceOwed || collapsedText === " "
+      // Text that is only whitespace still separates the words around it
+      if (hasLeadingGap) spaceOwed = true
       return
     }
-    if (!atLineStart && (spaceOwed || collapsedText.startsWith(" "))) emit(" ")
+
+    const needsSpaceBefore = !atLineStart && (spaceOwed || hasLeadingGap)
+
+    if (needsSpaceBefore) emit(" ")
     emit(words)
     atLineStart = false
-    spaceOwed = collapsedText.endsWith(" ")
+    spaceOwed = hasTrailingGap
   }
 
   const breakLine = (): void => {
@@ -168,8 +175,8 @@ export const extractHtmlVisibleText = (params: { html: string; maxBytes: number
 
   tokenizer.write(html)
 
-  // A paused tokenizer has stopped reading at the cap, and ending it would
-  // read on through the rest of the page.
+  // pause() clears `running`, so only a page read to its end is ended. Ending
+  // emits the text the tokenizer still holds there, such as an unfinished entity.
   if (tokenizer.running) tokenizer.end()
   return textParts.join("").trimEnd()
 }
diff --git a/src/vault-mcp/search/file-watcher.ts b/src/vault-mcp/search/file-watcher.ts
index be09ba768..0a009dfd4 100644
--- a/src/vault-mcp/search/file-watcher.ts
+++ b/src/vault-mcp/search/file-watcher.ts
@@ -34,13 +34,13 @@ import { mapWithConcurrency } from "../../utils/map-with-concurrency.js"
  *  100ms, which stat()s the whole tree 10×/sec; 300ms meaningfully cuts CPU, and
  *  re-index latency is already governed by the 2000ms awaitWriteFinish window, so
  *  the perceived cost is negligible. */
-const POLLING_INTERVAL_MS = 300
+const FILESYSTEM_POLLING_INTERVAL_MS = 300
 
 /** Default for FileWatcherOptions.stabilityThreshold (see its doc). */
 const DEFAULT_STABILITY_THRESHOLD_MS = 2000
 
 /** Default for FileWatcherOptions.pollInterval. */
-const DEFAULT_POLL_INTERVAL_MS = 100
+const DEFAULT_WRITE_FINISH_POLL_INTERVAL_MS = 100
 
 /**
  * Default for FileWatcherOptions.heldChangesDeadline. The server starts
@@ -182,7 +182,8 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
   let watcherState: WatcherState = { mode: "holding", heldPaths: new Map() }
 
   /** Indexes an added or modified non-md file: its asset-table row, plus its
-   *  content when it is a canvas or an indexable text or PDF file. */
+   *  content when it is a canvas or, with file content indexing on, a PDF,
+   *  text file, HTML page or script. */
   const indexChangedNonMdFile = async (params: {
     filePath: string
     relativePath: string
@@ -254,6 +255,9 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
               if (decodedSource.status !== "text") return null
               return decodedSource.text
             }
+            // Canvases and text formats decode leniently, so a stray invalid byte
+            // or NUL padding keeps them in search. Images and other files never
+            // reach this switch: the guard above reads only the kinds search indexes.
             case "canvas":
             case "text":
             case "image":
@@ -387,8 +391,8 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
 
       // Parsed before the second token check, with no await between that check
       // and the write, so a delete or newer event that lands during a slow parse wins.
-      // An aborted parse resolves "dropped", but every abort comes with such an
-      // event, so that check discards it
+      // An aborted parse resolves with outcome "dropped", but every abort comes
+      // with such an event, so that check discards it
       const parseResult = await parseNoteBodyTags(content)
 
       if (currentEvents.get(relativePath) !== eventToken) return { status: "superseded" }
@@ -617,12 +621,12 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
     // interval only drives chokidar's polling backend. Pass it only when
     // polling, so we never depend on how chokidar treats an interval set
     // without usePolling (today it's ignored — a future release needn't be).
-    ...(watcherOptions?.usePolling ? { interval: POLLING_INTERVAL_MS } : {}),
+    ...(watcherOptions?.usePolling ? { interval: FILESYSTEM_POLLING_INTERVAL_MS } : {}),
     // Obsidian Sync writes files in chunks — wait for write stability before
     // indexing to avoid reading partial content
     awaitWriteFinish: {
       stabilityThreshold,
-      pollInterval: watcherOptions?.pollInterval ?? DEFAULT_POLL_INTERVAL_MS,
+      pollInterval: watcherOptions?.pollInterval ?? DEFAULT_WRITE_FINISH_POLL_INTERVAL_MS,
     },
   })
 
diff --git a/src/vault-mcp/search/hybrid-search.ts b/src/vault-mcp/search/hybrid-search.ts
index 63fe95447..623a9167b 100644
--- a/src/vault-mcp/search/hybrid-search.ts
+++ b/src/vault-mcp/search/hybrid-search.ts
@@ -91,7 +91,7 @@ const vectorSearch = (
   params: {
     query: string
     queryEmbeddingBuffer: Buffer
-    limit: number
+    chunkLimit: number
     folderPathPattern: string | undefined
     noteFilterSql: NoteFilterSql
   },
@@ -102,8 +102,8 @@ const vectorSearch = (
   if (!knnSearchStmt || !knnSearchInFolderStmt) return []
 
   // sqlite-vec picks its k rows before ORDER BY sorts them. With k at twice the limit, ties at
-  // `slice(0, params.limit)` below sort by path. A tie that runs past row k keeps scan order.
-  const overFetchedK = params.limit * 2
+  // `slice(0, params.chunkLimit)` below sort by path. A tie that runs past row k keeps scan order.
+  const overFetchedK = params.chunkLimit * 2
 
   const readNoteVectorRows = (): VectorHitRow[] => {
     // KNN sees only chunks of notes that pass every filter, so excluded notes can't take all k
@@ -145,7 +145,7 @@ const vectorSearch = (
 
   try {
     const overFetchedNoteRows = readNoteVectorRows()
-    const noteKnnRows = overFetchedNoteRows.slice(0, params.limit)
+    const noteKnnRows = overFetchedNoteRows.slice(0, params.chunkLimit)
 
     // Deduplicate to best chunk per note — rows are ordered by distance
     // ascending, so the first occurrence of each path is the closest match.
@@ -182,7 +182,7 @@ const fileContentVectorSearch = (
   params: {
     query: string
     queryEmbeddingBuffer: Buffer
-    limit: number
+    chunkLimit: number
     folderPathPattern: string | undefined
   },
   logger: Logger,
@@ -192,7 +192,7 @@ const fileContentVectorSearch = (
 
   try {
     // Fetch twice the limit so ties sort by path, as in vectorSearch.
-    const overFetchedK = params.limit * 2
+    const overFetchedK = params.chunkLimit * 2
     const overFetchedFileRows = params.folderPathPattern
       ? knnSearchInFolderStmt.all(
           params.queryEmbeddingBuffer,
@@ -200,7 +200,7 @@ const fileContentVectorSearch = (
           params.folderPathPattern,
         )
       : knnSearchStmt.all(params.queryEmbeddingBuffer, overFetchedK)
-    const fileKnnRows = overFetchedFileRows.slice(0, params.limit)
+    const fileKnnRows = overFetchedFileRows.slice(0, params.chunkLimit)
 
     const bestChunkPerFile = new Map<string, VectorHit>()
     for (const knnRow of fileKnnRows) {
@@ -427,7 +427,7 @@ export const hybridSearch = async (
         {
           query: params.query,
           queryEmbeddingBuffer,
-          limit: candidateLimit,
+          chunkLimit: candidateLimit,
           folderPathPattern,
           noteFilterSql,
         },
@@ -444,7 +444,7 @@ export const hybridSearch = async (
           {
             query: params.query,
             queryEmbeddingBuffer,
-            limit: candidateLimit,
+            chunkLimit: candidateLimit,
             folderPathPattern,
           },
           logger,
diff --git a/src/vault-mcp/search/search-helpers.ts b/src/vault-mcp/search/search-helpers.ts
index 20306be71..8ca632ccc 100644
--- a/src/vault-mcp/search/search-helpers.ts
+++ b/src/vault-mcp/search/search-helpers.ts
@@ -321,7 +321,7 @@ export const fileContentRowToSearchResult = (
   folder: row.folder,
   type: null,
   kind: "file",
-  // Lowercased, as vault_list_files reports it
+  // Lowercased like vault_list_files' extension, and absent for a file with none
   extension: posix.extname(row.path).toLowerCase() || undefined,
   modified: storedMtimeToIso(row.mtime),
   bytes: row.bytes,
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index f9267515f..a42a8da2b 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -86,26 +86,27 @@ const EMBEDDED_FILE_KINDS: ReadonlySet<FileKind> = new Set(["canvas", "pdf", "te
 const MAX_INDEXED_CONTENT_BYTES = 102_400
 
 /** An HTML page larger than this is indexed by its name only, like a scanned
- *  PDF. Extracting its text runs on the main thread, and attribute-heavy pages
- *  at 16 MiB already took up to 1.7 s, close to the 2-second point at which
- *  this server moves a parser to a worker thread. */
+ *  PDF. Extracting its text runs on the main thread, which answers no request
+ *  meanwhile, and attribute-heavy pages at 16 MiB already took up to 1.7 s. */
 const MAX_INDEXED_HTML_PAGE_BYTES = 16 * 1024 * 1024
 
-/** The text file_content_fts holds for a file, from the file's own text: a
- *  canvas's outline, an HTML page's visible text, and every other kind as
- *  it arrives. */
-const rawContentToIndexedText = (params: {
+/** The text file_content_fts holds for a file, built from the text its reader
+ *  supplies:
+ *  - a canvas's JSON becomes its outline;
+ *  - an HTML page's source becomes its visible text;
+ *  - every other kind, a PDF's extracted text included, is indexed as supplied. */
+const fileTextToIndexedText = (params: {
   filePath: string
-  rawContent: string
+  fileText: string
   fileBytes: number
 }): string => {
   switch (getFileKind(params.filePath)) {
     case "canvas":
-      return linearizeCanvas(params.rawContent)
+      return linearizeCanvas(params.fileText)
     case "html":
       if (params.fileBytes > MAX_INDEXED_HTML_PAGE_BYTES) return ""
       return extractHtmlVisibleText({
-        html: params.rawContent,
+        html: params.fileText,
         maxBytes: MAX_INDEXED_CONTENT_BYTES,
       })
     case "image":
@@ -113,7 +114,7 @@ const rawContentToIndexedText = (params: {
     case "text":
     case "script":
     case "other":
-      return params.rawContent
+      return params.fileText
   }
 }
 
@@ -503,6 +504,7 @@ export const createSearchIndex = (
       body_tags   TEXT NOT NULL DEFAULT '[]'
     );
 
+    -- path UNINDEXED: stored for JOIN/DELETE but not searchable, saves index space
     CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
       path UNINDEXED, title, content, metadata, tokenize='porter unicode61'
     );
@@ -569,7 +571,6 @@ export const createSearchIndex = (
       file_identity  TEXT
     );
   `)
-  // path UNINDEXED: stored for JOIN/DELETE but not searchable, saves index space
 
   // ── Vector tables (embedding pipeline) ────────────────────────
   // Created only when an embedder is provided — otherwise the search index
@@ -1208,20 +1209,21 @@ export const createSearchIndex = (
    *  links.resolve's three-tier strategy but checks against non_md_files
    *  instead of the notes table.
    *
-   *  Resolution tiers are grouped into two families by what they match
-   *  against: the full-filename family queries the path column as-is, and
-   *  the stem family queries the extension-stripped base_path/basename
-   *  columns. The full-filename family runs first. The families are
-   *  NOT disjoint: a multi-dot filename's stem retains its inner dots
-   *  ("photo.png.canvas" → base_path "photo.png"), so a with-extension target
-   *  can stem-match a different file. Family ordering makes the full-filename
-   *  match win ("photo.png" prefers a/photo.png), while the stem tiers remain
-   *  the fallback so [[photo.png]] with only photo.png.canvas in the vault
-   *  still resolves — mirroring Obsidian's [[Trip Route]] → Trip Route.canvas
-   *  stem matching. An extensionless target can match in both families: the
-   *  full-filename tiers hit an extensionless file (LICENSE, Dockerfile) by
-   *  exact path or path suffix, and the stem tiers hit any file whose
-   *  extension-stripped name matches. */
+   *  Resolution tiers fall into two families by what they match against, and
+   *  the full-filename family runs first:
+   *  - The full-filename family queries the path column as-is.
+   *  - The stem family queries the extension-stripped base_path/basename
+   *    columns.
+   *  - One target can match in both families. A multi-dot filename's stem
+   *    keeps its inner dots ("photo.png.canvas" → base_path "photo.png"), so
+   *    [[photo.png]] can stem-match a different file. Running full-filename
+   *    first makes it prefer a/photo.png, and the stem tiers still resolve it
+   *    when only photo.png.canvas exists, as Obsidian's
+   *    [[Trip Route]] → Trip Route.canvas stem matching does.
+   *  - An extensionless target can match in both too: the full-filename tiers
+   *    hit an extensionless file (LICENSE, Dockerfile) by exact path or path
+   *    suffix, and the stem tiers hit any file whose extension-stripped name
+   *    matches. */
   const resolveNonMarkdownFile = (params: {
     target: string
     sourcePath?: string
@@ -1310,8 +1312,9 @@ export const createSearchIndex = (
       const relativeTarget = posix.join(posix.dirname(link.source), link.target)
       const targetSuffix = `/${link.target.toLowerCase()}`
 
-      // This broad suffix check includes SQLite LIKE's ASCII case folding;
-      // the resolver remains authoritative for match ordering and exact case.
+      // toLowerCase folds every letter, while SQLite's LIKE folds only ASCII
+      // letters, so this suffix check keeps every link the resolver's LIKE
+      // queries could match. The resolver then decides the match and its case.
       const matchesFullFilename =
         filePath === link.target ||
         filePath === relativeTarget ||
@@ -1364,15 +1367,12 @@ export const createSearchIndex = (
   ): symbol => {
     const extension = posix.extname(params.filePath)
     const isCanvas = isCanvasPath(params.filePath)
-    const contentToIndex = rawContentToIndexedText({
+    const contentToIndex = fileTextToIndexedText({
       filePath: params.filePath,
-      rawContent: params.rawContent,
+      fileText: params.rawContent,
       fileBytes: params.fileStat.size,
     })
 
-    // Truncate content exceeding the FTS cap — iterates Unicode code points
-    // and accumulates UTF-8 byte length so the cap is enforced in bytes
-    // without splitting multi-byte characters at the boundary.
     const contentBytes = Buffer.byteLength(contentToIndex, "utf8")
     const needsTruncation = contentBytes > MAX_INDEXED_CONTENT_BYTES
     const truncatedContent = needsTruncation
@@ -2339,15 +2339,15 @@ export const createSearchIndex = (
     })
     const nonMarkdownFileSizes = nonMarkdownFileSizeResults.filter((entry) => entry !== null)
     const canvasFiles = allNonMdFiles.filter((file) => isCanvasPath(file.relativePath))
-    // PDF and text files are only read when file content FTS is enabled —
-    // without the tables, the extraction is wasted I/O.
+    // PDF, text, HTML and script files are only read when file content FTS is
+    // enabled — without the tables, the extraction is wasted I/O.
     const pdfFiles = fileToolsEnabled
       ? allNonMdFiles.filter((file) => getFileKind(file.relativePath) === "pdf")
       : []
     const textFiles = fileToolsEnabled
       ? allNonMdFiles.filter((file) => getFileKind(file.relativePath) === "text")
       : []
-    const sourceFiles = fileToolsEnabled
+    const htmlAndScriptFiles = fileToolsEnabled
       ? allNonMdFiles.filter((file) => {
           const fileKind = getFileKind(file.relativePath)
           return fileKind === "html" || fileKind === "script"
@@ -2420,7 +2420,8 @@ export const createSearchIndex = (
     })
     const pdfContents = pdfResults.filter((entry) => entry !== null)
 
-    // Read text files for content indexing (raw UTF-8).
+    // Text formats decode leniently, so a text file with a stray invalid byte
+    // or NUL padding still indexes; HTML pages and scripts get the strict check below.
     const textFileContentResults = await mapWithConcurrency({
       items: textFiles,
       concurrency: INDEXING_FILE_READ_CONCURRENCY,
@@ -2431,18 +2432,18 @@ export const createSearchIndex = (
     /** Reads an HTML page or script as bytes and keeps it only when the bytes
      *  are UTF-8 with no NUL byte early on, the test vault_read_file applies,
      *  so search never holds text that a read refuses. */
-    const readDecodedSourceFile = async (
+    const readHtmlOrScriptFile = async (
       file: RebuildFilePaths,
     ): Promise<RebuildFileContent | null> => {
       // Decoding throws on text longer than V8's string limit, so it shares the
       // read's try, and one such file is skipped rather than failing the rebuild.
-      const readSource = async () => {
+      const readDecodedFile = async () => {
         try {
           const [buffer, fileStat] = await Promise.all([
             readFile(file.absolutePath),
             stat(file.absolutePath),
           ])
-          return { decodedSource: decodeTextBuffer(buffer), fileStat }
+          return { decodedText: decodeTextBuffer(buffer), fileStat }
         } catch (error) {
           logger.warn("skipped unreadable file during rebuild", {
             path: file.relativePath,
@@ -2451,35 +2452,35 @@ export const createSearchIndex = (
           return null
         }
       }
-      const source = await readSource()
+      const decodedFile = await readDecodedFile()
 
-      if (!source) return null
+      if (!decodedFile) return null
 
-      const { decodedSource } = source
+      const { decodedText, fileStat } = decodedFile
 
-      switch (decodedSource.status) {
+      switch (decodedText.status) {
         case "text":
           return {
             relativePath: file.relativePath,
-            content: decodedSource.text,
-            modifiedAtMs: source.fileStat.mtimeMs,
-            sizeBytes: source.fileStat.size,
+            content: decodedText.text,
+            modifiedAtMs: fileStat.mtimeMs,
+            sizeBytes: fileStat.size,
           }
         case "binary":
         case "invalid-utf8":
           logger.debug("left a file that is not UTF-8 text out of the index", {
             path: file.relativePath,
-            decodeStatus: decodedSource.status,
+            decodeStatus: decodedText.status,
           })
           return null
       }
     }
-    const sourceContentResults = await mapWithConcurrency({
-      items: sourceFiles,
+    const htmlAndScriptContentResults = await mapWithConcurrency({
+      items: htmlAndScriptFiles,
       concurrency: INDEXING_FILE_READ_CONCURRENCY,
-      mapper: readDecodedSourceFile,
+      mapper: readHtmlOrScriptFile,
     })
-    const sourceContents = sourceContentResults.filter((entry) => entry !== null)
+    const htmlAndScriptContents = htmlAndScriptContentResults.filter((entry) => entry !== null)
 
     const noteContentResults = await mapWithConcurrency({
       items: markdownFiles,
@@ -2625,7 +2626,7 @@ export const createSearchIndex = (
           ...canvasContents,
           ...pdfContents,
           ...textFileContents,
-          ...sourceContents,
+          ...htmlAndScriptContents,
         ]
         for (const fileEntry of allFileContents) {
           try {
diff --git a/src/vault-mcp/search/search-queries.ts b/src/vault-mcp/search/search-queries.ts
index 09d8cf526..f9ab411f7 100644
--- a/src/vault-mcp/search/search-queries.ts
+++ b/src/vault-mcp/search/search-queries.ts
@@ -534,8 +534,11 @@ const tryRerankMemoryCandidates = async (
       }),
     )
 
-    const probabilityOf = (candidate: MemoryRecallCandidate): number =>
-      probabilityByEntryId.get(candidate.row.id) ?? 0
+    // Missing probability (a scores/candidates length mismatch that cannot
+    // normally happen) sorts as least relevant, not as an error.
+    const getRerankProbability = (candidate: MemoryRecallCandidate): number => {
+      return probabilityByEntryId.get(candidate.row.id) ?? 0
+    }
 
     // Adaptive floor: FTS hits always survive (lexical match = strong
     // evidence), so the floor only governs vector-only candidates. Find
@@ -546,7 +549,7 @@ const tryRerankMemoryCandidates = async (
     const vectorOnlyCandidates = candidates.filter((candidate) => !candidate.ftsHit)
     const bestProbability =
       vectorOnlyCandidates.length > 0
-        ? Math.max(...vectorOnlyCandidates.map(probabilityOf))
+        ? Math.max(...vectorOnlyCandidates.map(getRerankProbability))
         : MEMORY_RECALL_MAX_FLOOR
     const scaledFloor = bestProbability * MEMORY_RECALL_RELATIVE_RATIO
     const effectiveFloor = Math.min(
@@ -555,17 +558,12 @@ const tryRerankMemoryCandidates = async (
     )
 
     const kept = candidates.filter(
-      (candidate) => candidate.ftsHit || probabilityOf(candidate) >= effectiveFloor,
+      (candidate) => candidate.ftsHit || getRerankProbability(candidate) >= effectiveFloor,
     )
 
     logger.info("memory recall rerank", { bestProbability, effectiveFloor })
 
-    return {
-      kept,
-      // Missing probability (a scores/candidates length mismatch that cannot
-      // normally happen) sorts as least relevant, not as an error.
-      relevance: (candidate) => probabilityByEntryId.get(candidate.row.id) ?? 0,
-    }
+    return { kept, relevance: getRerankProbability }
   } catch (error) {
     logger.warn("memory recall rerank failed, using distance margin", {
       error: describeError(error),
@@ -586,8 +584,9 @@ const compareMemoryEntriesChronologically = (a: MemoryEntryRow, b: MemoryEntryRo
  *  Rowids are reassigned when the index is rebuilt, and computeRrfScores
  *  breaks equal-score ties by identifier — a rowid key would let a rebuild
  *  reorder tied entries. NUL cannot appear in file names, so the key never
- *  collides across files; the index is zero-padded so the identifier's
- *  byte order equals numeric entry order past nine entries. */
+ *  collides across files. The index is zero-padded to six digits so the
+ *  identifier's byte order equals numeric entry order (unpadded, entry 10
+ *  would sort before entry 9) for up to 999,999 entries in a file. */
 const memoryEntryFusionKey = (row: MemoryEntryRow): string =>
   `${row.file}\u0000${String(row.entry_index).padStart(6, "0")}`
 
@@ -1469,7 +1468,8 @@ export const searchByProperty = (
 // ── Link queries ───────────────────────────────────────────────
 
 /** A link query takes a note, whose ".md" must be lowercase, or a canvas in
- *  any letter case. */
+ *  any letter case. A canvas returns before the check, so ".canvas" in its
+ *  list only names the accepted extensions in the refusal. */
 const assertLinkQueryPath = (path: string): void => {
   if (isCanvasPath(path)) return
   assertPathHasExtension(path, [".md", ".canvas"])
diff --git a/src/vault-mcp/vault-operations/asset-operations.ts b/src/vault-mcp/vault-operations/asset-operations.ts
index 94ec860e5..b4264741f 100644
--- a/src/vault-mcp/vault-operations/asset-operations.ts
+++ b/src/vault-mcp/vault-operations/asset-operations.ts
@@ -40,7 +40,7 @@ import type { Logger } from "../../logger.js"
  *  limit. Deliberately not an env var — the image budget is the tunable
  *  surface; text past this size is read in line windows, not raised into a
  *  bigger blob. */
-const MAX_TEXT_OUTPUT_BYTES = 102_400
+export const MAX_TEXT_OUTPUT_BYTES = 102_400
 
 type RenderedPdfPage = Readonly<{
   fitted: FittedImage
@@ -88,16 +88,29 @@ const requestsLineWindow = (params: {
 
 /** Rejects text output past the fixed cap — an explicit error beats silent
  *  truncation, and states the actual size so the caller knows what exists. */
-const assertTextWithinCap = (params: { text: string; path: string }): void => {
-  const textBytes = Buffer.byteLength(params.text, "utf8")
+const assertTextWithinCap = (params: {
+  text: string
+  path: string
+  lineWindow?: LineWindow | undefined
+}): void => {
+  const { text, path, lineWindow } = params
+  const textBytes = Buffer.byteLength(text, "utf8")
 
   if (textBytes <= MAX_TEXT_OUTPUT_BYTES) return
+
+  const renderedSubject = lineWindow
+    ? `"${path}" lines ${lineWindow.startLine}–${lineWindow.endLine} render`
+    : `"${path}" renders`
   throw new Error(
-    `text output too large: "${params.path}" renders to ${textBytes} bytes ` +
+    `text output too large: ${renderedSubject} to ${textBytes} bytes ` +
       `(cap ${MAX_TEXT_OUTPUT_BYTES} bytes)`,
   )
 }
 
+const notValidUtf8Message = (path: string): string => {
+  return `not valid UTF-8: "${path}" cannot be returned as text`
+}
+
 /**
  * Builds the text result for a rendition — whole or paged. Without paging
  * params the full text returns byte-identical, within the text output cap. With
@@ -126,59 +139,49 @@ const buildTextResult = (params: {
     limit,
   })
 
-  const windowBytes = Buffer.byteLength(windowText, "utf8")
-  const exceedsByteCap = windowBytes > MAX_TEXT_OUTPUT_BYTES
-
-  if (exceedsByteCap) {
-    throw new Error(
-      `text output too large: "${path}" lines ${lineWindow.startLine}–${lineWindow.endLine} ` +
-        `render to ${windowBytes} bytes (cap ${MAX_TEXT_OUTPUT_BYTES} bytes)`,
-    )
-  }
-
+  assertTextWithinCap({ text: windowText, path, lineWindow })
   return { kind: "text", text: windowText, path, lineWindow }
 }
 
 /** Decodes an asset buffer as UTF-8, rejecting invalid byte sequences — text
  *  is promised verbatim, and the default decoder would silently substitute
- *  U+FFFD for every undecodable byte instead. */
+ *  U+FFFD for every undecodable byte instead. Unlike decodeTextBuffer, it
+ *  accepts NUL bytes. */
 const decodeUtf8Strict = (params: { buffer: Buffer; path: string }): string => {
   try {
     return new TextDecoder("utf-8", { fatal: true }).decode(params.buffer)
   } catch (error) {
-    throw new Error(`not valid UTF-8: "${params.path}" cannot be returned as text`, {
-      cause: error,
-    })
+    throw new Error(notValidUtf8Message(params.path), { cause: error })
   }
 }
 
+type ReadAsset = Readonly<{ buffer: Buffer; bytes: number; extension: string }>
+
 /** Builds the text result for a file outside the dedicated types (HTML pages,
  *  scripts, files with no extension), refusing binary data and bytes that are
  *  not UTF-8. */
 const buildUtf8SourceResult = (params: {
-  buffer: Buffer
-  bytes: number
-  extension: string
+  asset: ReadAsset
   path: string
   startLine?: number | undefined
   limit?: number | undefined
 }): AssetReadResult => {
-  const { path, startLine, limit } = params
-  const decodedSource = decodeTextBuffer(params.buffer)
+  const { asset, path, startLine, limit } = params
+  const decodedSource = decodeTextBuffer(asset.buffer)
 
   switch (decodedSource.status) {
     case "text":
       return buildTextResult({ text: decodedSource.text, path, startLine, limit })
     case "binary":
       throw new Error(
-        `unsupported file type "${params.extension}": "${path}" exists ` +
-          `(${params.bytes} bytes) and holds a NUL byte in its first ` +
+        `unsupported file type "${asset.extension}": "${path}" exists ` +
+          `(${asset.bytes} bytes) and holds a NUL byte in its first ` +
           `${NUL_SEARCH_WINDOW_BYTES.toLocaleString("en-US")} bytes (binary data or UTF-16 text). ` +
           `Readable types: images (${getExtensionsOfKind("image").join("/")}), .canvas, .pdf, ` +
           `and UTF-8 text files`,
       )
     case "invalid-utf8":
-      throw new Error(`not valid UTF-8: "${path}" cannot be returned as text`)
+      throw new Error(notValidUtf8Message(path))
   }
 }
 
@@ -342,8 +345,6 @@ const readPdfPages = async (
   }
 }
 
-type ReadAsset = Readonly<{ buffer: Buffer; bytes: number }>
-
 /** Images have no raw source or line range, because the fitted image block is
  *  the only form delivered. */
 const readImageAsset = async (params: {
@@ -500,14 +501,7 @@ const readAssetContent = async (
     case "html":
     case "script":
     case "other":
-      return buildUtf8SourceResult({
-        buffer: asset.buffer,
-        bytes: asset.bytes,
-        extension: asset.extension,
-        path,
-        startLine,
-        limit,
-      })
+      return buildUtf8SourceResult({ asset, path, startLine, limit })
   }
 }
 
diff --git a/src/vault-mcp/vault-operations/note-mover.ts b/src/vault-mcp/vault-operations/note-mover.ts
index 7b13604c5..e02a0cc85 100644
--- a/src/vault-mcp/vault-operations/note-mover.ts
+++ b/src/vault-mcp/vault-operations/note-mover.ts
@@ -121,7 +121,8 @@ const classifyLinkForm = (params: {
   // The resolved path carries the file's real extension — ".md" for notes,
   // the asset's own otherwise — so one rule covers both kinds (a stem-form
   // asset link gets its extension appended, exactly like an extensionless
-  // wikilink to a note).
+  // wikilink to a note). An extensionless file gives "", which every target
+  // ends with, so nothing is appended.
   const extension = posix.extname(resolvedTarget)
   const targetWithExtension = rawTarget.endsWith(extension) ? rawTarget : `${rawTarget}${extension}`
 
@@ -147,8 +148,9 @@ const buildReplacementTarget = (params: {
   const { form, desiredTarget, newSourcePath, keepExtension, resolveFromNewSource } = params
   const absoluteForm = keepExtension ? desiredTarget : links.stripExtension(desiredTarget)
 
-  const resolvesToDesired = (candidate: string): boolean =>
-    resolveFromNewSource(candidate) === desiredTarget
+  const resolvesToDesired = (candidate: string): boolean => {
+    return resolveFromNewSource(candidate) === desiredTarget
+  }
 
   if (form === "basename") {
     const basename = posix.basename(absoluteForm)
@@ -205,18 +207,20 @@ const rewriteTarget = (
 
   // Resolves against the post-move vault from the source's new location —
   // shared by the "already resolves" check and the candidate verifier.
-  const resolveFromNewSource = (candidate: string): string | null =>
-    targetKind === "note"
-      ? links.resolve({
-          target: candidate,
-          allPaths: context.allNotePathsAfter,
-          sourcePath: context.newSourcePath,
-        })
-      : links.resolveAsset({
-          target: candidate,
-          allAssetPaths: context.allAssetPaths,
-          sourcePath: context.newSourcePath,
-        })
+  const resolveFromNewSource = (candidate: string): string | null => {
+    if (targetKind === "note") {
+      return links.resolve({
+        target: candidate,
+        allPaths: context.allNotePathsAfter,
+        sourcePath: context.newSourcePath,
+      })
+    }
+    return links.resolveAsset({
+      target: candidate,
+      allAssetPaths: context.allAssetPaths,
+      sourcePath: context.newSourcePath,
+    })
+  }
 
   // Already resolves correctly from the new location — leave it alone.
   const resolvedAfter = resolveFromNewSource(rawTarget)
@@ -227,9 +231,9 @@ const rewriteTarget = (
   // extension is kept only when the original carried the resolved file's
   // real extension (markdown links always keep theirs; a wikilink to a note
   // never carries ".md"; a stem-form asset link stays extensionless).
-  const resolvedExtension = posix.extname(desiredTarget)
-  const keepExtension =
-    (targetKind === "asset" || grammar === "markdown") && originalExtension === resolvedExtension
+  const grammarWritesExtension = targetKind === "asset" || grammar === "markdown"
+  const carriesResolvedExtension = originalExtension === posix.extname(desiredTarget)
+  const keepExtension = grammarWritesExtension && carriesResolvedExtension
 
   return buildReplacementTarget({
     form: classifyLinkForm({
@@ -249,11 +253,12 @@ const rewriteTarget = (
 /** Percent-encodes a markdown link path segment-by-segment. Parentheses are
  *  encoded explicitly because encodeURIComponent skips them and an unencoded ")"
  *  would close the link early. */
-const encodeMarkdownLinkPath = (path: string): string =>
-  path
+const encodeMarkdownLinkPath = (path: string): string => {
+  return path
     .split("/")
     .map((segment) => encodeURIComponent(segment).replace(/\(/g, "%28").replace(/\)/g, "%29"))
     .join("/")
+}
 
 type LinkEdit = { start: number; end: number; replacement: string }
 
@@ -380,8 +385,9 @@ const rewriteBody = (
 type FrontmatterRewrite = { value: unknown; linksRewritten: number }
 
 /** Total links rewritten across a set of child results. */
-const totalLinksRewritten = (rewrites: ReadonlyArray<FrontmatterRewrite>): number =>
-  rewrites.reduce((runningTotal, child) => runningTotal + child.linksRewritten, 0)
+const totalLinksRewritten = (rewrites: ReadonlyArray<FrontmatterRewrite>): number => {
+  return rewrites.reduce((runningTotal, child) => runningTotal + child.linksRewritten, 0)
+}
 
 /** Rewrites wikilinks inside a frontmatter value, recursing into arrays and
  *  objects. Markdown links are body-only and left untouched. */
@@ -453,10 +459,11 @@ const rewriteNoteContent = (
     }
   }
 
-  // Called only for the error it throws. A link inside the block changed, so
-  // the block reads as key-value properties: an unreadable, list or
-  // single-value block reads as none, and the function returned above.
-  // stringifyNote below would still drop an explicit YAML tag on any value.
+  // Called only for the error it throws on a value with an explicit YAML tag,
+  // which stringifyNote below would drop. Its other refusals cannot fire here:
+  // a link inside the block changed, so the block reads as key-value
+  // properties, and an unreadable, list or single-value block reads as none,
+  // which returned above.
   parseNoteForRewrite(rawContent)
 
   const rewrittenData = frontmatterResult.value
@@ -607,24 +614,9 @@ const extractLinkTargets = (params: { path: string; content: string }): string[]
   return links.extractAll(parsed.content, frontmatter)
 }
 
-/** Scans vault notes and Canvas files for links that resolve to targetPath,
- *  returning paths the caller didn't already know about. The index records
- *  only a Canvas's file cards, so a Canvas linking the note from a text card
- *  is found here. Pre-filters by basename substring before parsing. Read
- *  failures on individual files are logged and skipped. */
-const discoverBacklinksFromFilesystem = async (
-  params: {
-    vaultPath: string
-    targetPath: string
-    allNotePaths: readonly string[]
-    /** Read only to pick out the Canvas files to scan; links resolve against
-     *  allNotePaths alone. */
-    allAssetPaths: readonly string[]
-    knownPaths: ReadonlySet<string>
-  },
-  logger: Logger,
-): Promise<string[]> => {
-  const targetStem = posix.basename(params.targetPath, ".md")
+/** Every lowercased spelling a link to a note named `targetStem` can take in a
+ *  note's or Canvas's text, for a substring pre-filter before the full parse. */
+const listLowercaseStemSpellings = (targetStem: string): string[] => {
   // Pre-filter stems are lowercased so a case-mismatched link is never
   // skipped before the resolver runs. Encode the original-case stem FIRST,
   // then lowercase — encodeURIComponent is codepoint-sensitive, so encoding
@@ -652,6 +644,36 @@ const discoverBacklinksFromFilesystem = async (
     })
     .toLowerCase()
 
+  return [
+    lowercaseStem,
+    lowercaseEncodedStem,
+    lowercaseParenEncodedStem,
+    lowercaseJsonEscapedStem,
+    lowercaseAsciiEscapedStem,
+  ]
+}
+
+/** Scans vault notes and Canvas files for links that resolve to targetPath,
+ *  returning paths the caller didn't already know about. The index records
+ *  only a Canvas's file cards, so a Canvas linking the note from a text card
+ *  is found here. Pre-filters by basename substring before parsing. Read
+ *  failures on individual files are logged and skipped. */
+const discoverBacklinksFromFilesystem = async (
+  params: {
+    vaultPath: string
+    targetPath: string
+    allNotePaths: readonly string[]
+    /** Read only to pick out the Canvas files to scan; links resolve against
+     *  allNotePaths alone. */
+    allAssetPaths: readonly string[]
+    knownPaths: ReadonlySet<string>
+  },
+  logger: Logger,
+): Promise<string[]> => {
+  const lowercaseStemSpellings = listLowercaseStemSpellings(
+    posix.basename(params.targetPath, ".md"),
+  )
+
   const candidatePaths = [...params.allNotePaths, ...params.allAssetPaths.filter(isCanvasPath)]
   // The target itself is never its own backlink source: moveNote rewrites the
   // moved note's own links separately.
@@ -670,12 +692,9 @@ const discoverBacklinksFromFilesystem = async (
         // Skip files whose text can't contain a link — a cheap substring
         // pre-filter before the full parse below.
         const lowercaseContent = content.toLowerCase()
-        const couldContainLink =
-          lowercaseContent.includes(lowercaseStem) ||
-          lowercaseContent.includes(lowercaseEncodedStem) ||
-          lowercaseContent.includes(lowercaseParenEncodedStem) ||
-          lowercaseContent.includes(lowercaseJsonEscapedStem) ||
-          lowercaseContent.includes(lowercaseAsciiEscapedStem)
+        const couldContainLink = lowercaseStemSpellings.some((spelling) => {
+          return lowercaseContent.includes(spelling)
+        })
 
         if (!couldContainLink) return null
 

From a8b9f7d94cf106254d5345423d09e69c360c194b Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 02:14:36 -0500
Subject: [PATCH 15/38] fix(search): find a file's FTS row by rowid so a
 rebuild over many files stays linear

FTS5 cannot index the path column, so deleting a file's FTS row by path
scanned the whole table. A rebuild over 16,000 scripts took 1,171 s against
42 s without them. Each FTS row now shares its file_content row's rowid,
and the upsert updates in place so the rowid holds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../search/__tests__/search-index.test.ts     | 67 ++++++++++++++++++-
 src/vault-mcp/search/search-index.ts          | 45 +++++++++----
 2 files changed, 96 insertions(+), 16 deletions(-)

diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index 95c025814..1feab13dc 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -201,8 +201,9 @@ const isoFromMillis = (mtimeMs: number): string => {
 }
 
 /** Poisons one factory-prepared statement, identified by an SQL fragment: a
- *  prototype-level prepare spy patches the matching statement's .run to throw
- *  while armed. Must be installed BEFORE createSearchIndex — every write
+ *  prototype-level prepare spy patches the matching statement's .run and .get
+ *  (a write with RETURNING runs through .get) to throw while armed. Must be
+ *  installed BEFORE createSearchIndex — every write
  *  statement is prepared at factory scope — and stays disarmed so factory
  *  setup and seeding writes succeed until a test arms it. */
 const installStatementPoison = (sqlFragment: string) => {
@@ -211,7 +212,7 @@ const installStatementPoison = (sqlFragment: string) => {
   // so a concrete function type pins the default instantiation explicitly.
   const realPrepare: (this: Database.Database, source: string) => Database.Statement =
     Database.prototype.prepare
-  // The patched .run closes over this mutable flag so tests can trigger the
+  // The patched methods close over this mutable flag so tests can trigger the
   // failure long after the statement was prepared.
   const poisonState = { armed: false }
   const prepareSpy = vi.spyOn(Database.prototype, "prepare").mockImplementation(function (
@@ -222,10 +223,15 @@ const installStatementPoison = (sqlFragment: string) => {
 
     if (source.includes(sqlFragment)) {
       const realRun = statement.run.bind(statement)
+      const realGet = statement.get.bind(statement)
       statement.run = (...runParams: unknown[]) => {
         if (poisonState.armed) throw new Error(message)
         return realRun(...runParams)
       }
+      statement.get = (...getParams: unknown[]) => {
+        if (poisonState.armed) throw new Error(message)
+        return realGet(...getParams)
+      }
     }
     return statement
   })
@@ -7767,6 +7773,61 @@ describe("canvas file content and links", () => {
       )
       expect(afterResults).toHaveLength(0)
     })
+
+    it("keeps only a file's latest text searchable across repeated updates", async () => {
+      const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
+        fileToolsEnabled: true,
+      })
+      const upsertText = (filePath: string, rawContent: string): void => {
+        fileIndex.upsertNonMdFile(filePath, rawContent.length)
+        fileIndex.upsertFileContent(
+          { filePath, rawContent, fileStat: testStat(1000, rawContent.length) },
+          logger,
+        )
+      }
+      const searchPaths = async (query: string): Promise<string[]> => {
+        const { results } = await fileIndex.hybridSearch({ query }, logger)
+        return results.map((result) => result.path)
+      }
+
+      // The third version catches an FTS row left behind by the second, which
+      // a single update cannot show.
+      upsertText("logs/a.log", "amberwick lantern")
+      upsertText("logs/b.log", "copperfen meadow")
+      upsertText("logs/a.log", "slatebrook harbor")
+      upsertText("logs/a.log", "thistledown quarry")
+
+      expect(await searchPaths("amberwick")).toEqual([])
+      expect(await searchPaths("slatebrook")).toEqual([])
+      expect(await searchPaths("thistledown")).toEqual(["logs/a.log"])
+      expect(await searchPaths("copperfen")).toEqual(["logs/b.log"])
+    })
+
+    it("removeFileContent leaves other files' text searchable", async () => {
+      const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
+        fileToolsEnabled: true,
+      })
+      for (const [filePath, rawContent] of [
+        ["logs/a.log", "amberwick lantern"],
+        ["logs/b.log", "copperfen meadow"],
+      ] as const) {
+        fileIndex.upsertNonMdFile(filePath, rawContent.length)
+        fileIndex.upsertFileContent(
+          { filePath, rawContent, fileStat: testStat(1000, rawContent.length) },
+          logger,
+        )
+      }
+
+      fileIndex.removeFileContent({ filePath: "logs/a.log" }, logger)
+
+      const { results: removedResults } = await fileIndex.hybridSearch(
+        { query: "amberwick" },
+        logger,
+      )
+      const { results: keptResults } = await fileIndex.hybridSearch({ query: "copperfen" }, logger)
+      expect(removedResults.map((result) => result.path)).toEqual([])
+      expect(keptResults.map((result) => result.path)).toEqual(["logs/b.log"])
+    })
   })
 
   describe("note-specific filter suppression", () => {
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index a42a8da2b..f4e79a99d 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -835,20 +835,36 @@ export const createSearchIndex = (
     `SELECT path FROM non_md_files WHERE path LIKE '%/' || ? ESCAPE '\\' ORDER BY length(path), path LIMIT 1`,
   )
   // ── File content prepared statements (conditional on fileToolsEnabled) ──
+  // Each file_content_fts row has its file_content row's rowid, so a write finds
+  // the FTS row by rowid.
+  // - FTS5 cannot index path. Finding the row by path scans the whole table, so
+  //   a rebuild over thousands of files would take time quadratic in their count.
+  // - The rowids stay paired because the rebuild empties both tables together
+  //   and every other write goes through these statements.
+  // - The upsert updates a row in place. INSERT OR REPLACE would give it a new
+  //   rowid.
   const upsertFileContentStmt = fileToolsEnabled
-    ? db.prepare(
-        `INSERT OR REPLACE INTO file_content (path, title, content, folder, mtime, bytes)
-         VALUES (?, ?, ?, ?, ?, ?)`,
+    ? db.prepare<[string, string, string, string, number, number], { rowid: number }>(
+        `INSERT INTO file_content (path, title, content, folder, mtime, bytes)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT (path) DO UPDATE SET
+           title = excluded.title, content = excluded.content, folder = excluded.folder,
+           mtime = excluded.mtime, bytes = excluded.bytes
+         RETURNING rowid`,
       )
     : null
   const deleteFileContentStmt = fileToolsEnabled
-    ? db.prepare(`DELETE FROM file_content WHERE path = ?`)
+    ? db.prepare<[string], { rowid: number }>(
+        `DELETE FROM file_content WHERE path = ? RETURNING rowid`,
+      )
     : null
   const deleteFileContentFtsStmt = fileToolsEnabled
-    ? db.prepare(`DELETE FROM file_content_fts WHERE path = ?`)
+    ? db.prepare<[number]>(`DELETE FROM file_content_fts WHERE rowid = ?`)
     : null
   const insertFileContentFtsStmt = fileToolsEnabled
-    ? db.prepare(`INSERT INTO file_content_fts (path, title, content) VALUES (?, ?, ?)`)
+    ? db.prepare<[number, string, string, string]>(
+        `INSERT INTO file_content_fts (rowid, path, title, content) VALUES (?, ?, ?, ?)`,
+      )
     : null
   // The folder predicate runs before ORDER BY/LIMIT so a folder-scoped search
   // sees every in-folder match, not just those that rank inside the candidate
@@ -1394,7 +1410,7 @@ export const createSearchIndex = (
       if (upsertFileContentStmt && deleteFileContentFtsStmt && insertFileContentFtsStmt) {
         const title = basename(params.filePath, extension)
         const folder = posix.dirname(params.filePath)
-        upsertFileContentStmt.run(
+        const upsertedRow = upsertFileContentStmt.get(
           params.filePath,
           title,
           truncatedContent,
@@ -1402,8 +1418,11 @@ export const createSearchIndex = (
           Math.round(params.fileStat.mtimeMs),
           params.fileStat.size,
         )
-        deleteFileContentFtsStmt.run(params.filePath)
-        insertFileContentFtsStmt.run(params.filePath, title, truncatedContent)
+
+        // RETURNING yields the inserted or updated row on every upsert.
+        if (!upsertedRow) throw new Error(`file content upsert returned no row: ${params.filePath}`)
+        deleteFileContentFtsStmt.run(upsertedRow.rowid)
+        insertFileContentFtsStmt.run(upsertedRow.rowid, params.filePath, title, truncatedContent)
       }
 
       // Link extraction — canvas only, unconditional (graph integrity)
@@ -1439,10 +1458,10 @@ export const createSearchIndex = (
   /** Removes a file's FTS content, graph links, chunks and vectors, invalidating pending embeds. */
   const removeFileContent = (params: { filePath: string }, logger: Logger): void => {
     db.transaction(() => {
-      if (deleteFileContentStmt && deleteFileContentFtsStmt) {
-        deleteFileContentFtsStmt.run(params.filePath)
-        deleteFileContentStmt.run(params.filePath)
-      }
+      const deletedRow = deleteFileContentStmt?.get(params.filePath)
+
+      if (deletedRow) deleteFileContentFtsStmt?.run(deletedRow.rowid)
+
       if (deleteFileVectorsForPathStmt && deleteFileChunksForPathStmt) {
         deleteFileVectorsForPathStmt.run(params.filePath)
         deleteFileChunksForPathStmt.run(params.filePath)

From 14f360de909e4829540311e5cbda265c9d57b423 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 02:30:53 -0500
Subject: [PATCH 16/38] test: cover rebuild read and decode failures, uppercase
 dispatch and HTML embedding
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- The rebuild skips an HTML page or script that fails to read or to decode,
  and keeps indexing the rest (decoding was moved inside the read's try).
- removeFileContent leaves no keyword row behind for a file re-added at the
  same path.
- An HTML page's visible text, not its source, is embedded; the rebuild's
  embedding pass never queues scripts.
- vault_read_file dispatches a canvas and an image by kind when the path's
  extension is uppercase; the reranker labels an uppercase .PDF a PDF file.
- The HTML extractor keeps a space that ends an inline tag's text and breaks
  no line for a block element inside a hidden one.
- The backlink scan's plain and JSON-escaped stem spellings each have a case
  only they match.

Ship-Check: test-audit · claude-opus-5-5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../obsidian-markdown/__tests__/html.test.ts  |   8 +
 .../search/__tests__/hybrid-search.test.ts    |  16 +-
 .../search/__tests__/search-index.test.ts     | 140 +++++++++++++++++-
 .../__tests__/asset-operations.test.ts        |  50 +++++++
 .../__tests__/note-mover.test.ts              |  54 +++++++
 5 files changed, 257 insertions(+), 11 deletions(-)

diff --git a/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts b/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
index e068de862..97d85a1e8 100644
--- a/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
+++ b/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
@@ -56,6 +56,10 @@ describe("extractHtmlVisibleText", () => {
     )
   })
 
+  it("breaks no line for a block element inside a hidden element", () => {
+    expect(extractAll("<p>one <template><div>inert</div></template>two</p>")).toBe("one two")
+  })
+
   it("hides everything after a template that never closes", () => {
     expect(extractAll("<p>shown</p><template><p>never shown</p>")).toBe("shown")
   })
@@ -78,6 +82,10 @@ describe("extractHtmlVisibleText", () => {
     )
   })
 
+  it("keeps a space that ends the text inside an inline tag", () => {
+    expect(extractAll("<p><b>one </b>two</p>")).toBe("one two")
+  })
+
   it("joins words that inline tags split with no whitespace", () => {
     expect(extractAll("<p>un<b>broken</b></p>")).toBe("unbroken")
   })
diff --git a/src/vault-mcp/search/__tests__/hybrid-search.test.ts b/src/vault-mcp/search/__tests__/hybrid-search.test.ts
index 07fefb8e5..5e0f41014 100644
--- a/src/vault-mcp/search/__tests__/hybrid-search.test.ts
+++ b/src/vault-mcp/search/__tests__/hybrid-search.test.ts
@@ -2269,7 +2269,10 @@ describe("hybridSearch — ranking tuning", () => {
     ])
   })
 
-  it("uses 'PDF file' kind label for .pdf file results", async () => {
+  it.each([
+    { label: ".pdf", filePath: "docs/report.pdf", title: "report" },
+    { label: "uppercase .PDF", filePath: "docs/Report.PDF", title: "Report" },
+  ])("uses 'PDF file' kind label for $label file results", async ({ filePath, title }) => {
     const pdfContent = "quarterly earnings report for fiscal year"
     const capturingReranker = {
       rerankPairs: vi.fn().mockImplementation((_query: string, documents: string[]) => {
@@ -2297,25 +2300,22 @@ describe("hybridSearch — ranking tuning", () => {
       },
       logger,
     )
-    index.upsertNonMdFile("docs/report.pdf", 100)
+    index.upsertNonMdFile(filePath, 100)
     const reportFileSourceVersion = index.upsertFileContent(
       {
-        filePath: "docs/report.pdf",
+        filePath,
         rawContent: pdfContent,
         fileStat: testStat(1000, 100),
       },
       logger,
     )
-    await index.embedFileContent(
-      { sourceVersion: reportFileSourceVersion, filePath: "docs/report.pdf" },
-      logger,
-    )
+    await index.embedFileContent({ sourceVersion: reportFileSourceVersion, filePath }, logger)
 
     await index.hybridSearch({ query: "quarterly earnings" }, logger)
 
     expect(capturingReranker.rerankPairs).toHaveBeenCalledTimes(1)
     expect(capturingReranker.rerankPairs).toHaveBeenCalledWith("quarterly earnings", [
-      `PDF file: report\n\n${pdfContent}`,
+      `PDF file: ${title}\n\n${pdfContent}`,
       "Career\n\n\nCareer goals and aspirations.",
     ])
   })
diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index 1feab13dc..a582cc659 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -12,6 +12,7 @@ import type { NoteMetadata, OutgoingLinkEntry, SearchIndex, TaskEntry } from "..
 import type { StatusClassification } from "../../obsidian-markdown/tasks.js"
 import { logger } from "../../../logger.js"
 import { statOrNull } from "../../../utils/fs.js"
+import { decodeTextBuffer } from "../../../utils/decode-text-buffer.js"
 import { extractPdfText } from "../../obsidian-markdown/pdf.js"
 import { buildPdf } from "../../obsidian-markdown/__tests__/pdf-fixture.js"
 import type { BodyTagParser, BodyTagParseResult } from "../body-tag-parser.js"
@@ -19,6 +20,7 @@ import { inProcessBodyTagParser, withBodyTags } from "./body-tag-test-helpers.js
 
 vi.mock("node:fs/promises", { spy: true })
 vi.mock("../../../utils/fs.js", { spy: true })
+vi.mock("../../../utils/decode-text-buffer.js", { spy: true })
 vi.mock("../../obsidian-markdown/pdf.js", { spy: true })
 
 const realSqliteVec = await vi.importActual<typeof sqliteVec>("sqlite-vec")
@@ -4055,6 +4057,83 @@ describe("rebuildFromVault filesystem failures", () => {
     },
   )
 
+  it.each([
+    { label: "HTML page", fileName: "broken.html" },
+    { label: "script", fileName: "broken.py" },
+  ])("warns and skips an unreadable $label while indexing healthy files", async ({ fileName }) => {
+    const { vaultPath, search } = await createRebuildVault()
+    const filePath = join(vaultPath, fileName)
+    await writeFile(filePath, "brokenquartz")
+    const actualFs = await vi.importActual<typeof import("node:fs/promises")>("node:fs/promises")
+    const readSpy = vi.mocked(readFile).mockImplementation(async (requestedPath, options) => {
+      if (requestedPath === filePath) throw new Error("controlled read failure")
+      return actualFs.readFile(requestedPath, options)
+    })
+    const warnSpy = vi.spyOn(logger, "warn")
+    onTestFinished(() => {
+      readSpy.mockRestore()
+      warnSpy.mockRestore()
+    })
+    const rebuilt = await search.rebuildFromVault(
+      { vaultPath, bodyTagParser: inProcessBodyTagParser },
+      logger,
+    )
+    await rebuilt.embedding
+
+    expect(rebuilt.count).toBe(1)
+    // Read as bytes, so the strict UTF-8 check sees them
+    expect(readSpy).toHaveBeenCalledWith(filePath)
+    expect(warnSpy).toHaveBeenCalledExactlyOnceWith("skipped unreadable file during rebuild", {
+      path: fileName,
+      error: "[Error]: controlled read failure",
+    })
+    expect(
+      (await search.hybridSearch({ query: "healthyamber" }, logger)).results.map(
+        (entry) => entry.path,
+      ),
+    ).toEqual(["healthy.md"])
+    expect((await search.hybridSearch({ query: "brokenquartz" }, logger)).results).toEqual([])
+  })
+
+  it("warns and skips a page whose text fails to decode, and indexes the other pages", async () => {
+    const { vaultPath, search } = await createRebuildVault()
+    await writeFile(join(vaultPath, "huge.html"), "<p>brokenquartz</p>")
+    await writeFile(join(vaultPath, "plain.html"), "<p>plainopal</p>")
+    const actualDecoder = await vi.importActual<
+      typeof import("../../../utils/decode-text-buffer.js")
+    >("../../../utils/decode-text-buffer.js")
+    // Stands in for the error V8 throws on text past its string length limit,
+    // which a test cannot allocate
+    const decodeSpy = vi.mocked(decodeTextBuffer).mockImplementation((buffer) => {
+      if (Buffer.from(buffer).toString("utf8") === "<p>brokenquartz</p>") {
+        throw new Error("controlled decode failure")
+      }
+      return actualDecoder.decodeTextBuffer(buffer)
+    })
+    const warnSpy = vi.spyOn(logger, "warn")
+    onTestFinished(() => {
+      decodeSpy.mockRestore()
+      warnSpy.mockRestore()
+    })
+    const rebuilt = await search.rebuildFromVault(
+      { vaultPath, bodyTagParser: inProcessBodyTagParser },
+      logger,
+    )
+    await rebuilt.embedding
+
+    expect(warnSpy).toHaveBeenCalledExactlyOnceWith("skipped unreadable file during rebuild", {
+      path: "huge.html",
+      error: "[Error]: controlled decode failure",
+    })
+    const searchPaths = async (query: string): Promise<string[]> => {
+      const { results } = await search.hybridSearch({ query }, logger)
+      return results.map((result) => result.path)
+    }
+    expect(await searchPaths("plainopal")).toEqual(["plain.html"])
+    expect(await searchPaths("brokenquartz")).toEqual([])
+    expect(await searchPaths("healthyamber")).toEqual(["healthy.md"])
+  })
+
   it("contains a rebuild PDF extraction failure and indexes its next valid extraction", async () => {
     const { vaultPath, search } = await createRebuildVault()
     await writeFile(join(vaultPath, "broken.pdf"), "controlled bytes")
@@ -7828,6 +7907,34 @@ describe("canvas file content and links", () => {
       expect(removedResults.map((result) => result.path)).toEqual([])
       expect(keptResults.map((result) => result.path)).toEqual(["logs/b.log"])
     })
+
+    it("removeFileContent leaves none of a file's text for a later file at its path to bring back", async () => {
+      const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
+        fileToolsEnabled: true,
+      })
+      const upsertText = (filePath: string, rawContent: string): void => {
+        fileIndex.upsertNonMdFile(filePath, rawContent.length)
+        fileIndex.upsertFileContent(
+          { filePath, rawContent, fileStat: testStat(1000, rawContent.length) },
+          logger,
+        )
+      }
+      const searchPaths = async (query: string): Promise<string[]> => {
+        const { results } = await fileIndex.hybridSearch({ query }, logger)
+        return results.map((result) => result.path)
+      }
+
+      // b.log holds a later row id, so the re-added a.log takes a new one
+      // instead of reusing the removed row's id
+      upsertText("logs/a.log", "amberwick lantern")
+      upsertText("logs/b.log", "copperfen meadow")
+      fileIndex.removeFileContent({ filePath: "logs/a.log" }, logger)
+      upsertText("logs/a.log", "slatebrook harbor")
+
+      expect(await searchPaths("amberwick")).toEqual([])
+      expect(await searchPaths("slatebrook")).toEqual(["logs/a.log"])
+      expect(await searchPaths("copperfen")).toEqual(["logs/b.log"])
+    })
   })
 
   describe("note-specific filter suppression", () => {
@@ -8008,9 +8115,11 @@ describe("files with an uppercase extension", { timeout: 15_000 }, () => {
 })
 
 describe("HTML pages", () => {
-  /** Rebuilds an index over a vault holding the given files. */
+  /** Rebuilds an index over a vault holding the given files, waiting for the
+   *  embedding pass when an embedder is given. */
   const rebuildVaultOf = async (
     files: ReadonlyArray<{ path: string; content: string | Buffer }>,
+    embedder?: Parameters<typeof createSearchIndex>[1],
   ): Promise<SearchIndex> => {
     const vaultDir = await mkdtemp(join(tmpdir(), "html-pages-"))
     onTestFinished(() => rm(vaultDir, { recursive: true }))
@@ -8018,13 +8127,14 @@ describe("HTML pages", () => {
       await writeFile(join(vaultDir, file.path), file.content)
     }
 
-    const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
+    const fileIndex = createSearchIndex(":memory:", embedder, undefined, {
       fileToolsEnabled: true,
     })
-    await fileIndex.rebuildFromVault(
+    const rebuilt = await fileIndex.rebuildFromVault(
       { vaultPath: vaultDir, bodyTagParser: inProcessBodyTagParser },
       logger,
     )
+    await rebuilt.embedding
     return fileIndex
   }
 
@@ -8050,6 +8160,21 @@ describe("HTML pages", () => {
     expect(await searchEach(fileIndex, queries)).toEqual([["runbook.html"], [], ["report.htm"], []])
   })
 
+  it("embeds a page's visible text, not its source, for semantic search", async () => {
+    const vector = new Float32Array(384).fill(0.1)
+    const embedder = {
+      embedText: vi.fn().mockResolvedValue(vector),
+      embedBatch: vi.fn(async (texts: readonly string[]) => texts.map(() => vector)),
+    }
+
+    await rebuildVaultOf(
+      [{ path: "runbook.html", content: "<p>visiblequartz</p><script>scriptquartz()</script>" }],
+      embedder,
+    )
+
+    expect(embedder.embedText).toHaveBeenCalledExactlyOnceWith("runbook\n\nvisiblequartz")
+  })
+
   it("indexes a page's last paragraph when its markup passes the 100 KiB cap but its text does not", async () => {
     // About 140 KB of markup around about 2 KB of text
     const styledWords = '<span style="color: red; font-weight: bold; padding: 2px">a</span>'.repeat(
@@ -8170,6 +8295,10 @@ describe("scripts", () => {
       embedText: vi.fn().mockResolvedValue(vector),
       embedBatch: vi.fn(async (texts: readonly string[]) => texts.map(() => vector)),
     }
+    const infoSpy = vi.spyOn(logger, "info")
+    onTestFinished(() => {
+      infoSpy.mockRestore()
+    })
     const { database } = await rebuildVaultOf({
       files: [...SCRIPT_FILES, { path: "notes.txt", content: "plain text control\n" }],
       embedder,
@@ -8196,6 +8325,11 @@ describe("scripts", () => {
       count: 1,
     })
     expect(embedder.embedText).toHaveBeenCalledExactlyOnceWith("notes\n\nplain text control")
+    // The embedding pass never queues the scripts, so it counts the text file alone
+    expect(infoSpy).toHaveBeenCalledWith("file content embedding pass complete", {
+      files: 1,
+      fileChunksEmbedded: 1,
+    })
   })
 
   it("leaves a script holding a NUL byte out of search", async () => {
diff --git a/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts b/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
index d476c3f38..286ba6864 100644
--- a/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
+++ b/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
@@ -1116,6 +1116,56 @@ describe("readAssetContent — UTF-8 files outside the dedicated types", () => {
   })
 })
 
+// Each stub reports the extension lowercased, as readAsset does, while the path
+// keeps the caller's uppercase extension
+describe("readAssetContent — uppercase extensions", () => {
+  it("returns the outline of a canvas whose extension is uppercase", async () => {
+    const canvasSource = JSON.stringify({
+      nodes: [{ id: "t1", type: "text", text: "Launch plan", x: 0, y: 0, width: 200, height: 100 }],
+      edges: [],
+    })
+    mockedReadAsset.mockResolvedValue({
+      buffer: Buffer.from(canvasSource, "utf8"),
+      bytes: Buffer.byteLength(canvasSource, "utf8"),
+      extension: ".canvas",
+    })
+
+    const result = await assetOperations.readAssetContent(
+      { ...defaultParams, path: "Boards/Roadmap.CANVAS" },
+      logger,
+    )
+
+    expect(result).toEqual({
+      kind: "text",
+      text: "# Canvas: 1 node, 0 edges\n\n[text]\nLaunch plan",
+      path: "Boards/Roadmap.CANVAS",
+    })
+  })
+
+  it("fits an image whose extension is uppercase to the image budget", async () => {
+    const imageBuffer = Buffer.from("fake-png-bytes")
+    const fitted = buildFittedImage()
+    mockedReadAsset.mockResolvedValue({ buffer: imageBuffer, bytes: 14, extension: ".png" })
+    mockedFitImage.mockResolvedValue(fitted)
+
+    const result = await assetOperations.readAssetContent(
+      { ...defaultParams, path: "Scans/Receipt.PNG" },
+      logger,
+    )
+
+    expect(result).toEqual({
+      kind: "image",
+      fitted,
+      originalBytes: 14,
+      path: "Scans/Receipt.PNG",
+    })
+    expect(mockedFitImage).toHaveBeenCalledExactlyOnceWith({
+      buffer: imageBuffer,
+      budgetBytes: defaultParams.maxImageOutputBytes,
+    })
+  })
+})
+
 describe("readAssetContent — line paging", () => {
   /** Stubs readAsset with a UTF-8 text file of the given extension. */
   const stubReadAsset = (content: string, extension: string): void => {
diff --git a/src/vault-mcp/vault-operations/__tests__/note-mover.test.ts b/src/vault-mcp/vault-operations/__tests__/note-mover.test.ts
index 21113552a..ac00495e5 100644
--- a/src/vault-mcp/vault-operations/__tests__/note-mover.test.ts
+++ b/src/vault-mcp/vault-operations/__tests__/note-mover.test.ts
@@ -1126,6 +1126,38 @@ describe("moveNote — Canvas sources", () => {
     )
   })
 
+  it("finds a Canvas that escapes a double quote in the note's name but keeps its accented letters", async () => {
+    const { writeFixture, moveNote, readNote, logger } = setupVault()
+    await writeFixture('Café "Menu".md', "# Menu\n")
+    // The file holds Café \"Menu\", as Obsidian writes it, so of the scan's
+    // substring checks only the JSON-escaped one can match it: the plain stem
+    // lacks the backslashes, and the fully escaped one writes é as é.
+    await writeFixture(
+      "Board.canvas",
+      obsidianCanvas([
+        '{"id":"t1","type":"text","text":"See [[Café \\"Menu\\"]]","x":0,"y":0,"width":250,"height":60}',
+      ]),
+    )
+
+    const result = await moveNote({ oldPath: 'Café "Menu".md', newPath: "Menu.md" })
+
+    expect(await readNote("Board.canvas")).toBe(
+      obsidianCanvas([
+        '{"id":"t1","type":"text","text":"See [[Menu]]","x":0,"y":0,"width":250,"height":60}',
+      ]),
+    )
+    expect(result).toEqual({
+      moved_to: "Menu.md",
+      links_updated: 1,
+      updated_notes: ["Board.canvas"],
+      pruned_empty_folders: 0,
+    })
+    expect(vi.mocked(logger.info)).toHaveBeenCalledWith(
+      "backlink verification discovered sources the index missed",
+      { from: 'Café "Menu".md', to: "Menu.md", additionalSources: ["Board.canvas"], attempt: 0 },
+    )
+  })
+
   it("finds a Canvas whose JSON escapes the accented letters in the note's name", async () => {
     const { writeFixture, moveNote, readNote, logger } = setupVault()
     await writeFixture("École.md", "# École\n")
@@ -3049,4 +3081,26 @@ describe("moveNote — filesystem backlink verification", () => {
     })
     expect(await readNote("Hub.md")).toBe("See [x](Finished.md).\n")
   })
+
+  it("discovers a wikilink backlink to a note whose name holds a double quote", async () => {
+    const { writeFixture, moveNote, readNote } = setupVault()
+    await writeFixture('Say "Hi".md', "# Hi\n")
+    // A note's text holds the quote unescaped, so only the pre-filter's plain
+    // stem check matches it
+    await writeFixture("Linker.md", 'See [[Say "Hi"]].\n')
+
+    const result = await moveNote({
+      oldPath: 'Say "Hi".md',
+      newPath: "Greeting.md",
+      backlinkSources: [],
+    })
+
+    expect(result).toEqual({
+      moved_to: "Greeting.md",
+      links_updated: 1,
+      updated_notes: ["Linker.md"],
+      pruned_empty_folders: 0,
+    })
+    expect(await readNote("Linker.md")).toBe("See [[Greeting]].\n")
+  })
 })

From 83d1db44932876c1abb4b34161a6bf9b16ca8887 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 02:31:50 -0500
Subject: [PATCH 17/38] test: assert whole results in the HTML,
 uppercase-extension and script tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- The HTML extractor's speed test asserts the whole extracted text, not its
  first five characters.
- The uppercase-canvas link tests assert each outgoing link and backlink
  entry whole, not one or two fields of it.
- The script watcher test waits for the exact files embedded, not a count.

Ship-Check: test-audit · claude-opus-5-5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../obsidian-markdown/__tests__/html.test.ts  |  6 ++--
 .../search/__tests__/file-watcher.test.ts     | 17 +++++++++--
 .../search/__tests__/search-index.test.ts     | 29 ++++++++++++++++---
 3 files changed, 43 insertions(+), 9 deletions(-)

diff --git a/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts b/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
index 97d85a1e8..5b0c16f6b 100644
--- a/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
+++ b/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
@@ -117,13 +117,15 @@ describe("extractHtmlVisibleText", () => {
   })
 
   it("extracts 1 MB of unclosed nested tags within a second", () => {
-    const unclosedTags = "<div><span><b>x".repeat(Math.ceil(1_000_000 / 15))
+    const repeatCount = Math.ceil(1_000_000 / 15)
+    const unclosedTags = "<div><span><b>x".repeat(repeatCount)
 
     const startedAt = DateTime.now()
     const text = extractAll(unclosedTags)
     const elapsedMs = DateTime.now().diff(startedAt).as("milliseconds")
 
-    expect(text.slice(0, 5)).toBe("x\nx\nx")
+    // Each <div> starts a line of its own, so every "x" sits on its own line
+    expect(text).toBe(Array.from({ length: repeatCount }, () => "x").join("\n"))
     expect(elapsedMs).toBeLessThan(1_000)
   })
 })
diff --git a/src/vault-mcp/search/__tests__/file-watcher.test.ts b/src/vault-mcp/search/__tests__/file-watcher.test.ts
index a69639f69..984a273c3 100644
--- a/src/vault-mcp/search/__tests__/file-watcher.test.ts
+++ b/src/vault-mcp/search/__tests__/file-watcher.test.ts
@@ -598,8 +598,17 @@ describe("file-watcher — file content indexing", () => {
       await writeFile(join(vault, "Board.Canvas"), canvasSource, "utf8")
       await waitFor(() => upsertSpy.mock.calls.length > 0)
 
-      const linkedTargets = fileIndex.getOutgoingLinks({ path: "Board.Canvas" }, logger)
-      expect(linkedTargets.map((link) => link.path)).toEqual(["Plan.md"])
+      // Plan.md is never written, so the card is a link to a missing note
+      expect(fileIndex.getOutgoingLinks({ path: "Board.Canvas" }, logger)).toEqual([
+        {
+          path: "Plan.md",
+          title: null,
+          exists: false,
+          kind: "note",
+          bytes: null,
+          daily_note_forward_ref: false,
+        },
+      ])
 
       await unlink(join(vault, "Board.Canvas"))
       await waitFor(() => removeSpy.mock.calls.length > 0)
@@ -1634,7 +1643,9 @@ describe("file watcher — obsolete events and embedding queues", () => {
 
     await writeFile(join(testVault, "report.py"), "def get_order_total():\n    pass\n", "utf8")
     await fire("change", "report.py")
-    await vi.waitFor(() => expect(settledEmbeds).toHaveLength(3))
+    await vi.waitFor(() => {
+      expect(settledEmbeds.toSorted()).toEqual(["control.txt", "report.py", "report.py"])
+    })
 
     expect(keywordPaths("get order total")).toEqual(["report.py"])
     expect(keywordPaths("get user name")).toEqual([])
diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index a582cc659..0d1596c41 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -8092,8 +8092,15 @@ describe("files with an uppercase extension", { timeout: 15_000 }, () => {
 
     const outgoingLinks = fileIndex.getOutgoingLinks({ path: "files/Board.Canvas" }, logger)
 
-    expect(outgoingLinks.map(({ path, exists }) => ({ path, exists }))).toEqual([
-      { path: "Notes/Plan.md", exists: true },
+    expect(outgoingLinks).toEqual([
+      {
+        path: "Notes/Plan.md",
+        title: "Plan",
+        exists: true,
+        kind: "note",
+        bytes: Buffer.byteLength("# Plan\n"),
+        daily_note_forward_ref: false,
+      },
     ])
   })
 
@@ -8102,7 +8109,15 @@ describe("files with an uppercase extension", { timeout: 15_000 }, () => {
 
     const backlinks = fileIndex.getBacklinks({ path: "Notes/Plan.md" }, logger)
 
-    expect(backlinks.map((backlink) => backlink.path)).toEqual(["files/Board.Canvas"])
+    expect(backlinks).toEqual([
+      {
+        path: "files/Board.Canvas",
+        title: "Board",
+        bytes: Buffer.byteLength(
+          buildCanvasWithFileCard({ cardPath: "Notes/Plan.md", text: "indigo board" }),
+        ),
+      },
+    ])
   })
 
   it("lists the notes linking to a canvas with an uppercase extension", async () => {
@@ -8110,7 +8125,13 @@ describe("files with an uppercase extension", { timeout: 15_000 }, () => {
 
     const backlinks = fileIndex.getBacklinks({ path: "files/Board.Canvas" }, logger)
 
-    expect(backlinks.map((backlink) => backlink.path)).toEqual(["Notes/Index.md"])
+    expect(backlinks).toEqual([
+      {
+        path: "Notes/Index.md",
+        title: "Index",
+        bytes: Buffer.byteLength("See [[files/Board.Canvas]].\n"),
+      },
+    ])
   })
 })
 

From 282a7cf2c88bc5e0986ab75b4ba7cffb3069b780 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 02:37:00 -0500
Subject: [PATCH 18/38] fix(search): pair each note's FTS row with its notes
 rowid, and name the rebuild's reader per file kind

Deleting a note's FTS row by its unindexed path scanned the whole table,
so a rebuild grew quadratically with the note count: 8,000 notes spent
about 48 s in upserts. Notes now use the same rowid pairing as file
content. The rebuild picks each file's reader with one switch over every
file kind, so a new kind does not compile until it has one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../search/__tests__/search-index.test.ts     |  45 ++++++++
 src/vault-mcp/search/search-index.ts          | 108 +++++++++++-------
 2 files changed, 114 insertions(+), 39 deletions(-)

diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index 0d1596c41..e1eeb3412 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -1525,6 +1525,51 @@ describe("removeNote", () => {
   it("does not throw for non-existent path", () => {
     expect(() => index.removeNote("ghost.md")).not.toThrow()
   })
+
+  it("leaves other notes' text searchable", () => {
+    const upsertText = (filePath: string, body: string): void => {
+      index.upsertNote(
+        withBodyTags({ filePath, rawContent: `${body}\n`, fileStat: testStat(1000) }),
+        logger,
+      )
+    }
+    upsertText("a.md", "amberwick lantern")
+    upsertText("b.md", "copperfen meadow")
+
+    index.removeNote("a.md")
+
+    const searchPaths = (query: string): string[] => {
+      return index.fullTextSearch({ query }, logger).map((result) => result.path)
+    }
+    expect(searchPaths("amberwick")).toEqual([])
+    expect(searchPaths("copperfen")).toEqual(["b.md"])
+  })
+})
+
+describe("note text across repeated updates", () => {
+  it("keeps only a note's latest text searchable", () => {
+    const upsertText = (filePath: string, body: string): void => {
+      index.upsertNote(
+        withBodyTags({ filePath, rawContent: `${body}\n`, fileStat: testStat(1000) }),
+        logger,
+      )
+    }
+    const searchPaths = (query: string): string[] => {
+      return index.fullTextSearch({ query }, logger).map((result) => result.path)
+    }
+
+    // The third version catches an FTS row left behind by the second, which
+    // a single update cannot show.
+    upsertText("a.md", "amberwick lantern")
+    upsertText("b.md", "copperfen meadow")
+    upsertText("a.md", "slatebrook harbor")
+    upsertText("a.md", "thistledown quarry")
+
+    expect(searchPaths("amberwick")).toEqual([])
+    expect(searchPaths("slatebrook")).toEqual([])
+    expect(searchPaths("thistledown")).toEqual(["a.md"])
+    expect(searchPaths("copperfen")).toEqual(["b.md"])
+  })
 })
 
 describe("removeNote atomicity", () => {
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index f4e79a99d..f533120b2 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -742,15 +742,34 @@ export const createSearchIndex = (
   // Prepared statements are compiled once here and reused across all calls.
   // Each returned statement retains its compiled SQL; preparing inside an
   // operation would compile it again on every invocation.
-  const upsertNotesStmt = db.prepare(`
-    INSERT OR REPLACE INTO notes (path, title, content, tags, related, folder, type, created, mtime, properties, leading_callout, bytes, kanban_done_lanes, body_tags)
+
+  // Each notes_fts row has its notes row's rowid, so a write finds the FTS row
+  // by rowid. The file_content tables below are paired the same way.
+  // - FTS5 cannot index path. Finding the row by path scans the whole table, so
+  //   a rebuild over thousands of notes or files would take time quadratic in
+  //   their count.
+  // - The rowids stay paired because the rebuild empties each pair of tables
+  //   together and every other write goes through these statements.
+  // - The upsert updates a row in place. INSERT OR REPLACE would give it a new
+  //   rowid.
+  const upsertNotesStmt = db.prepare<unknown[], { rowid: number }>(`
+    INSERT INTO notes (path, title, content, tags, related, folder, type, created, mtime, properties, leading_callout, bytes, kanban_done_lanes, body_tags)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (path) DO UPDATE SET
+      title = excluded.title, content = excluded.content, tags = excluded.tags,
+      related = excluded.related, folder = excluded.folder, type = excluded.type,
+      created = excluded.created, mtime = excluded.mtime, properties = excluded.properties,
+      leading_callout = excluded.leading_callout, bytes = excluded.bytes,
+      kanban_done_lanes = excluded.kanban_done_lanes, body_tags = excluded.body_tags
+    RETURNING rowid
   `)
-  const deleteFtsStmt = db.prepare(`DELETE FROM notes_fts WHERE path = ?`)
-  const insertFtsStmt = db.prepare(
-    `INSERT INTO notes_fts (path, title, content, metadata) VALUES (?, ?, ?, ?)`,
+  const deleteFtsStmt = db.prepare<[number]>(`DELETE FROM notes_fts WHERE rowid = ?`)
+  const insertFtsStmt = db.prepare<[number, string, string, string, string]>(
+    `INSERT INTO notes_fts (rowid, path, title, content, metadata) VALUES (?, ?, ?, ?, ?)`,
+  )
+  const removeNotesStmt = db.prepare<[string], { rowid: number }>(
+    `DELETE FROM notes WHERE path = ? RETURNING rowid`,
   )
-  const removeNotesStmt = db.prepare(`DELETE FROM notes WHERE path = ?`)
   const deleteTasksStmt = db.prepare(`DELETE FROM tasks WHERE note_path = ?`)
   const insertTaskStmt = db.prepare(`
     INSERT INTO tasks (note_path, line, status_char, status, description,
@@ -835,14 +854,8 @@ export const createSearchIndex = (
     `SELECT path FROM non_md_files WHERE path LIKE '%/' || ? ESCAPE '\\' ORDER BY length(path), path LIMIT 1`,
   )
   // ── File content prepared statements (conditional on fileToolsEnabled) ──
-  // Each file_content_fts row has its file_content row's rowid, so a write finds
-  // the FTS row by rowid.
-  // - FTS5 cannot index path. Finding the row by path scans the whole table, so
-  //   a rebuild over thousands of files would take time quadratic in their count.
-  // - The rowids stay paired because the rebuild empties both tables together
-  //   and every other write goes through these statements.
-  // - The upsert updates a row in place. INSERT OR REPLACE would give it a new
-  //   rowid.
+  // Each file_content_fts row has its file_content row's rowid, as the notes
+  // statements above explain.
   const upsertFileContentStmt = fileToolsEnabled
     ? db.prepare<[string, string, string, string, number, number], { rowid: number }>(
         `INSERT INTO file_content (path, title, content, folder, mtime, bytes)
@@ -1376,6 +1389,7 @@ export const createSearchIndex = (
   const upsertFileContent = (
     params: {
       filePath: string
+      /** The file's own text, or a PDF's extracted text. */
       rawContent: string
       fileStat: { mtimeMs: number; size: number }
     },
@@ -1694,8 +1708,7 @@ export const createSearchIndex = (
     // throw rolls back), so code after the wrap's `)()` runs on both paths
     // — no link-phase work may live there.
     db.transaction(() => {
-      deleteFtsStmt.run(note.path)
-      upsertNotesStmt.run(
+      const upsertedNoteRow = upsertNotesStmt.get(
         note.path,
         note.title,
         note.content,
@@ -1711,7 +1724,11 @@ export const createSearchIndex = (
         note.kanban_done_lanes,
         note.body_tags,
       )
-      insertFtsStmt.run(note.path, note.title, note.content, metadataText)
+
+      // RETURNING yields the inserted or updated row on every upsert.
+      if (!upsertedNoteRow) throw new Error(`note upsert returned no row: ${note.path}`)
+      deleteFtsStmt.run(upsertedNoteRow.rowid)
+      insertFtsStmt.run(upsertedNoteRow.rowid, note.path, note.title, note.content, metadataText)
 
       deleteTasksStmt.run(note.path)
       // Line→blockId lookup so each child can resolve its parent's
@@ -2185,11 +2202,11 @@ export const createSearchIndex = (
     return embeddedCount
   }
 
-  /** Embed a file's rendered content into vector storage. Reads the processed
-   *  content from the file_content table (already linearized/truncated by
-   *  upsertFileContent). No-op when the embedding pipeline or file tools are
-   *  disabled, the file is a script, or the file is not in the FTS index.
-   *  Safe to call unconditionally. */
+  /** The watcher's entry point for embedding a file. It drops
+   *  embedAndStoreFileChunks' chunk count, so the watcher's queue of pending
+   *  embeds holds one promise type for notes and files. Safe to call for any
+   *  file: it does nothing when embedding or file tools are off, for a kind
+   *  search does not embed, or for a file not in the index. */
   const embedFileContent = async (
     params: { filePath: string; sourceVersion: symbol },
     logger: Logger,
@@ -2207,8 +2224,9 @@ export const createSearchIndex = (
     // All deletes commit or roll back together — a mid-sequence throw must
     // not leave the note half-removed across notes/FTS/tasks/links.
     db.transaction(() => {
-      deleteFtsStmt.run(filePath)
-      removeNotesStmt.run(filePath)
+      const removedNoteRow = removeNotesStmt.get(filePath)
+
+      if (removedNoteRow) deleteFtsStmt.run(removedNoteRow.rowid)
       deleteLinksStmt.run(filePath)
       deleteTasksStmt.run(filePath)
       if (deleteVectorsForNoteStmt && deleteChunksForNoteStmt) {
@@ -2357,21 +2375,33 @@ export const createSearchIndex = (
       mapper: readFileSize,
     })
     const nonMarkdownFileSizes = nonMarkdownFileSizeResults.filter((entry) => entry !== null)
-    const canvasFiles = allNonMdFiles.filter((file) => isCanvasPath(file.relativePath))
-    // PDF, text, HTML and script files are only read when file content FTS is
-    // enabled — without the tables, the extraction is wasted I/O.
-    const pdfFiles = fileToolsEnabled
-      ? allNonMdFiles.filter((file) => getFileKind(file.relativePath) === "pdf")
-      : []
-    const textFiles = fileToolsEnabled
-      ? allNonMdFiles.filter((file) => getFileKind(file.relativePath) === "text")
-      : []
-    const htmlAndScriptFiles = fileToolsEnabled
-      ? allNonMdFiles.filter((file) => {
-          const fileKind = getFileKind(file.relativePath)
-          return fileKind === "html" || fileKind === "script"
-        })
-      : []
+    // A canvas is read for its links whether or not file tools are on. PDF,
+    // text, HTML and script content is read only when the file content tables
+    // exist, because without them the extraction is wasted I/O. The switch
+    // names every kind, so a new kind does not compile until it has a reader.
+    const rebuildReaderFor = (fileKind: FileKind): "canvas" | "pdf" | "text" | "decoded" | null => {
+      switch (fileKind) {
+        case "canvas":
+          return "canvas"
+        case "pdf":
+          return fileToolsEnabled ? "pdf" : null
+        case "text":
+          return fileToolsEnabled ? "text" : null
+        case "html":
+        case "script":
+          return fileToolsEnabled ? "decoded" : null
+        case "image":
+        case "other":
+          return null
+      }
+    }
+    const nonMdFilesByReader = Map.groupBy(allNonMdFiles, (file) => {
+      return rebuildReaderFor(getFileKind(file.relativePath))
+    })
+    const canvasFiles = nonMdFilesByReader.get("canvas") ?? []
+    const pdfFiles = nonMdFilesByReader.get("pdf") ?? []
+    const textFiles = nonMdFilesByReader.get("text") ?? []
+    const htmlAndScriptFiles = nonMdFilesByReader.get("decoded") ?? []
 
     const readRebuildFileContent = async (params: {
       file: RebuildFilePaths

From e937e216a0a7c8e139c8a279fa21fb9659080e4f Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 02:37:04 -0500
Subject: [PATCH 19/38] fix(files): name a binary file with no extension as
 type (none)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../__tests__/asset-operations.test.ts             | 14 ++++++++++++++
 src/vault-mcp/vault-operations/asset-operations.ts |  7 +++++--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts b/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
index 286ba6864..e3b7fba8c 100644
--- a/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
+++ b/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
@@ -1082,6 +1082,20 @@ describe("readAssetContent — UTF-8 files outside the dedicated types", () => {
     )
   })
 
+  it("names a binary file with no extension as type (none)", async () => {
+    stubReadAsset({ buffer: buildBufferWithNulAt({ length: 40, nulIndex: 0 }), extension: "" })
+
+    await expect(
+      assetOperations.readAssetContent({ ...defaultParams, path: "bin/firmware" }, logger),
+    ).rejects.toThrow(
+      new Error(
+        'unsupported file type (none): "bin/firmware" exists (40 bytes) and holds a NUL ' +
+          "byte in its first 8,000 bytes (binary data or UTF-16 text). Readable types: images " +
+          "(.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and UTF-8 text files",
+      ),
+    )
+  })
+
   it("reads an HTML page whose first NUL byte sits just past the first 8,000 bytes", async () => {
     const buffer = buildBufferWithNulAt({ length: 8_001, nulIndex: 8_000 })
     stubReadAsset({ buffer, extension: ".html" })
diff --git a/src/vault-mcp/vault-operations/asset-operations.ts b/src/vault-mcp/vault-operations/asset-operations.ts
index b4264741f..35c4d8f54 100644
--- a/src/vault-mcp/vault-operations/asset-operations.ts
+++ b/src/vault-mcp/vault-operations/asset-operations.ts
@@ -172,14 +172,17 @@ const buildUtf8SourceResult = (params: {
   switch (decodedSource.status) {
     case "text":
       return buildTextResult({ text: decodedSource.text, path, startLine, limit })
-    case "binary":
+    case "binary": {
+      // "(none)" matches the listing's label for a file with no extension.
+      const fileType = asset.extension ? `"${asset.extension}"` : "(none)"
       throw new Error(
-        `unsupported file type "${asset.extension}": "${path}" exists ` +
+        `unsupported file type ${fileType}: "${path}" exists ` +
           `(${asset.bytes} bytes) and holds a NUL byte in its first ` +
           `${NUL_SEARCH_WINDOW_BYTES.toLocaleString("en-US")} bytes (binary data or UTF-16 text). ` +
           `Readable types: images (${getExtensionsOfKind("image").join("/")}), .canvas, .pdf, ` +
           `and UTF-8 text files`,
       )
+    }
     case "invalid-utf8":
       throw new Error(notValidUtf8Message(path))
   }

From ac11186ca02efbae89aa482eb05cf5e48620302d Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 03:06:14 -0500
Subject: [PATCH 20/38] docs: say HTML pages and scripts must be UTF-8 to read
 or search
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README's HTML and scripts bullet stated reading and search without the UTF-8 condition both apply: a page or script that holds a NUL byte early on or is not UTF-8, such as UTF-16 output, is refused by vault_read_file and left out of search. The sibling bullet already names UTF-8 for other text files.

Ship-Check: bug-check · claude-opus-5-5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 51985966b..91a7d6c9d 100644
--- a/README.md
+++ b/README.md
@@ -283,7 +283,7 @@ Your notes embed screenshots, reference architecture diagrams, and link out to c
 - **Canvases** — a [Canvas](https://help.obsidian.md/canvas) board arrives as a readable outline: its groups, each card's content in reading order, and the connections between them. Canvas content is full-text searchable, and file references on the board appear in the link graph — backlinks and outgoing links work just like note-to-note links. The exact JSON source is one flag away when full fidelity matters
 - **PDFs** — text is extracted with heading hierarchy, code blocks, and hyperlinks preserved; PDF content is full-text searchable alongside your notes. Set `raw: true` to render pages as images instead, showing layout, diagrams, and tables that text extraction can't preserve — scanned and image-only PDFs work in this mode
 - **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written, and their first 100 KB is full-text searchable. Any other UTF-8 text file reads back the same way. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
-- **HTML pages and scripts** — a saved page or generated report is searchable by the text a browser shows, never its tags or script code. Python, shell, and PowerShell scripts are searchable by keyword. Both read back as their source
+- **HTML pages and scripts** — a saved page or generated report is searchable by the text a browser shows, never its tags or script code. Python, shell, and PowerShell scripts are searchable by keyword. Both must be UTF-8 text, and both read back as their source
 - **Browse** — list any visible folder's files with per-extension counts and file sizes; files a note links to report their size in the link graph too
 
 Set `FILE_TOOLS_ENABLED=false` to hide the file tools — useful when your remote vault syncs without attachments.

From c1cdf918423f1308b12eb3c67dbf20806164e361 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 03:08:49 -0500
Subject: [PATCH 21/38] fix(tools): name the script extensions vault_search
 indexes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../__tests__/__snapshots__/tool-surface/default.json       | 2 +-
 .../__snapshots__/tool-surface/disabled-tools.json          | 2 +-
 .../__tests__/__snapshots__/tool-surface/embedding-off.json | 2 +-
 .../tool-surface/memory-off+embedding-off.json              | 2 +-
 .../__tests__/__snapshots__/tool-surface/memory-off.json    | 2 +-
 .../__tests__/__snapshots__/tool-surface/obsidian-sync.json | 2 +-
 .../__snapshots__/tool-surface/readonly+embedding-off.json  | 2 +-
 .../tool-surface/readonly+memory-off+embedding-off.json     | 2 +-
 .../__snapshots__/tool-surface/readonly+memory-off.json     | 2 +-
 .../__tests__/__snapshots__/tool-surface/readonly.json      | 2 +-
 src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts   | 6 +++---
 src/vault-mcp/mcp-core/tools/search-tools.ts                | 4 +++-
 12 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
index efabf8363..555f74d89 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
@@ -1313,7 +1313,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
index 672a2ba63..af3731b5e 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
@@ -1254,7 +1254,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
index bac930cae..8c4903c05 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
index b4dc5e7fe..67d244792 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
@@ -1173,7 +1173,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
index 7e4843515..431be1d3f 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
@@ -1172,7 +1172,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
index 2a159b59a..a12d7a757 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
index db51ead4a..3ec652e98 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
@@ -795,7 +795,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
index 36afa20c5..a92e5450b 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
@@ -700,7 +700,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
index 01d3c48ab..f99dbb170 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
@@ -699,7 +699,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
index 4d0750fee..e11aafebf 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
@@ -794,7 +794,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index bb1e767bb..e18812713 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1375,7 +1375,7 @@ describe("vault_search description reflects EMBEDDING_ENABLED", () => {
     const description = findSearchDescription(registerWithConfig({}))
     const openingSentence = description.slice(0, description.indexOf(". ") + 1)
     expect(openingSentence).toBe(
-      "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
+      "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
     )
     expect(description).toContain("career aspirations")
     expect(description).toContain("search_mode")
@@ -1403,7 +1403,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   // only the hybrid variant says scripts match by keyword alone.
   const FILE_RESULT_WORDING = {
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts; scripts match by keyword only)",
+      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only)",
     filtersLeadIn:
       "Filters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:",
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`,
@@ -1419,7 +1419,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   const KEYWORD_ONLY_FILE_RESULT_WORDING = {
     ...FILE_RESULT_WORDING,
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and scripts)",
+      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts)",
   }
 
   it.each([
diff --git a/src/vault-mcp/mcp-core/tools/search-tools.ts b/src/vault-mcp/mcp-core/tools/search-tools.ts
index 17f519744..88b4ecf25 100644
--- a/src/vault-mcp/mcp-core/tools/search-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/search-tools.ts
@@ -5,6 +5,7 @@ import { TOOL_NAMES } from "../tool-registry.js"
 import type { ToolRegistrationContext } from "./tool-helpers.js"
 import { readEffectiveOrphanExcludeFolders } from "../../vault-operations/vault-folder-config.js"
 import { readDailyNotesConfig } from "../../vault-operations/daily-notes.js"
+import { getExtensionsOfKind } from "../../obsidian-markdown/file-kinds.js"
 import {
   createStrictInputObject,
   describeNoteMetadataResult,
@@ -85,8 +86,9 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   // that mentions file results follows that setting, not any one tool. Scripts
   // are never embedded, which matters to a caller only while semantic matching runs.
   const scriptMatchClause = config.embeddingEnabled ? "; scripts match by keyword only" : ""
+  const scriptExtensions = getExtensionsOfKind("script").join("/")
   const searchedContentText = config.fileToolsEnabled
-    ? `vault notes and file content (canvas, PDF, text files, HTML pages, and scripts${scriptMatchClause})`
+    ? `vault notes and file content (canvas, PDF, text files, HTML pages, and ${scriptExtensions} scripts${scriptMatchClause})`
     : "vault notes"
   const searchResultFieldsText = config.fileToolsEnabled
     ? `path, title, snippet, score, ${tagsFieldsText}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`

From 8b96e15f9cdfa07124590454efec295c2e27311a Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 03:08:57 -0500
Subject: [PATCH 22/38] docs: scope the search-read agreement to the decode
 check, list web pages and scripts on the CLI page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md | 2 +-
 cli/README.md   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 4324e6097..907c9e87f 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -383,7 +383,7 @@ Search indexes file content in the `file_content` + `file_content_fts` tables, c
 | Scripts (`.py`/`.sh`/`.ps1`) | The file's source                                                                                                 | No       |
 
 - **HTML extraction** runs htmlparser2's tokenizer, which keeps no element stack, so unclosed tags cost no more than closed ones. Hidden elements (script, style, noscript, template, and the fallback content of iframe, noembed and noframes) end only at a closing tag with their own name, so a stray closing tag never shows hidden text. Block elements become line breaks, other whitespace collapses, and reading stops at the 100 KiB cap. Extraction stays on the main thread, and the 16 MiB page limit keeps its measured worst case under 2 seconds.
-- **HTML pages and scripts are read as bytes** and indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds a page or script that a read refuses. When a watched page or script stops passing it, its stored content is removed and its file row stays.
+- **HTML pages and scripts are read as bytes** and indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds a page or script that a read refuses as binary or as not UTF-8. When a watched page or script stops passing it, its stored content is removed and its file row stays.
 - **Scripts are searched by keyword only.** The markdown chunker reads a script's `# comment` lines as headings and turns `snake_case` names into one word, so embedding skips scripts before their text loads.
 
 **Opt-out:** File tools are opt-out: set `FILE_TOOLS_ENABLED=false` to hide `vault_read_file` and `vault_list_files`, and strip file tool references from server metadata and other tool descriptions. The `vault_get_outgoing_links` tool continues to report file links (it indexes from the links table, not the file tools). File config vars (`MAX_FILE_BYTES`, `MAX_IMAGE_OUTPUT_BYTES`, `MAX_PDF_RENDER_PAGES`) are still parsed when disabled.
diff --git a/cli/README.md b/cli/README.md
index 5b8543820..3a81e1e2f 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -10,7 +10,7 @@ npx vault-cortex@latest init
 Vault Cortex is a standalone, remote-capable MCP server that gives any AI
 agent hybrid search, task management, structured memory, and read/write
 access to your Obsidian vault — including its images, PDFs, canvases,
-and data files — see the
+web pages, scripts, and data files — see the
 [full feature overview](https://github.com/aliasunder/vault-cortex#what-you-get).
 The server runs as a Docker container; this CLI scaffolds the config and
 manages the container so you don't have to.

From 344f76359622134b9199a10ee214baa1617bd69e Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 03:09:03 -0500
Subject: [PATCH 23/38] test: prove vault_read_file's not-UTF-8 error over the
 transport

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../server-error-contracts.test.ts            | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/src/__tests__/integration/server-error-contracts.test.ts b/src/__tests__/integration/server-error-contracts.test.ts
index 59d63e498..6618f5783 100644
--- a/src/__tests__/integration/server-error-contracts.test.ts
+++ b/src/__tests__/integration/server-error-contracts.test.ts
@@ -2250,6 +2250,25 @@ describe("binary file", () => {
       isError: true,
     })
   })
+
+  it("vault_read_file on a file whose bytes are not UTF-8", async () => {
+    const filePath = "Latin1.html"
+    const fileFullPath = join(serverVaultPath, filePath)
+    // 0xE9 is "é" in Latin-1 and never a complete UTF-8 sequence
+    await writeFile(fileFullPath, Buffer.from([0x3c, 0x70, 0x3e, 0xe9]))
+    onTestFinished(() => rm(fileFullPath))
+
+    const result = await callTool({ client, name: "vault_read_file", args: { path: filePath } })
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: '[Error]: not valid UTF-8: "Latin1.html" cannot be returned as text',
+        },
+      ],
+      isError: true,
+    })
+  })
 })
 
 // ── Whitespace-only task text ────────────────────────────────

From 2962e60ae594379b5ba1ce8ade8a38f121fb04b9 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 03:21:01 -0500
Subject: [PATCH 24/38] refactor(search): list files to embed from the
 rebuild's own versions, point the listing comment at getFileKind

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/vault-mcp/search/search-index.ts               | 14 +++++++-------
 src/vault-mcp/vault-operations/asset-operations.ts |  5 ++---
 2 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index f533120b2..38bea1571 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -2720,14 +2720,14 @@ export const createSearchIndex = (
     // Files of an embedded kind whose text this rebuild indexed. Each file's
     // text loads from file_content only when the embedding pass reaches it,
     // so the pass holds one file's text at a time.
-    const withFileSourceVersion = (file: { path: string }) => {
-      const sourceVersion = fileVersionsForEmbedding.get(file.path)
-      const isEmbeddedKind = EMBEDDED_FILE_KINDS.has(getFileKind(file.path))
-
-      return sourceVersion && isEmbeddedKind ? [{ path: file.path, sourceVersion }] : []
+    const isEmbeddedFilePath = ([filePath]: [string, symbol]): boolean => {
+      return EMBEDDED_FILE_KINDS.has(getFileKind(filePath))
     }
-    const filesForEmbedding =
-      selectAllFileContentPathsStmt?.all().flatMap(withFileSourceVersion) ?? []
+    const filesForEmbedding = fileContentVectorEnabled
+      ? [...fileVersionsForEmbedding]
+          .filter(isEmbeddedFilePath)
+          .map(([path, sourceVersion]) => ({ path, sourceVersion }))
+      : []
     // Every note read from disk, including notes that failed to index, unlike indexedNotes
     const readableNotePaths = new Set(noteContents.map((note) => note.relativePath))
 
diff --git a/src/vault-mcp/vault-operations/asset-operations.ts b/src/vault-mcp/vault-operations/asset-operations.ts
index 35c4d8f54..3399cc55c 100644
--- a/src/vault-mcp/vault-operations/asset-operations.ts
+++ b/src/vault-mcp/vault-operations/asset-operations.ts
@@ -511,9 +511,8 @@ const readAssetContent = async (
 // ── Browsing ────────────────────────────────────────────────────
 
 /** The extension a listing shows, lowercased with its dot, or "(none)" for an
- *  extensionless file. It splits the name with posix.extname, as
- *  vaultFs.readAsset does, so a listed extension is the one a read dispatches
- *  on. */
+ *  extensionless file. It splits the name with posix.extname, as getFileKind
+ *  does, so a listed extension is the one a read dispatches on. */
 const getListingExtension = (assetPath: string): string => {
   return posix.extname(assetPath).toLowerCase() || "(none)"
 }

From ab918315e53df6ad01fdd7e1124eee893d19d567 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 03:41:07 -0500
Subject: [PATCH 25/38] fix(search): skip reading an HTML page that search
 finds by name only, correct the UNINDEXED comment

The rebuild and the watcher read and decoded a page over 16 MiB in full,
then discarded its text. They now check its size first and skip the read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../search/__tests__/file-watcher.test.ts     | 17 +++++++++++++
 .../search/__tests__/search-index.test.ts     |  5 +++-
 src/vault-mcp/search/file-watcher.ts          |  7 ++++++
 src/vault-mcp/search/search-index.ts          | 25 ++++++++++++++-----
 4 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/src/vault-mcp/search/__tests__/file-watcher.test.ts b/src/vault-mcp/search/__tests__/file-watcher.test.ts
index 984a273c3..f58ed5dd4 100644
--- a/src/vault-mcp/search/__tests__/file-watcher.test.ts
+++ b/src/vault-mcp/search/__tests__/file-watcher.test.ts
@@ -1589,6 +1589,23 @@ describe("file watcher — obsolete events and embedding queues", () => {
     },
   )
 
+  it("finds a page over 16 MiB by its name without reading it", async () => {
+    const { testVault, search, fire } = await createControlledWatcher()
+    const filler = "<p>filler</p>".repeat(Math.ceil((16 * 1024 * 1024) / 13) + 1)
+    const pagePath = join(testVault, "giganticpage.html")
+    await writeFile(pagePath, `<p>buriedcobalt</p>${filler}`, "utf8")
+    const searchPaths = async (query: string) => {
+      const { results } = await search.hybridSearch({ query }, logger)
+      return results.map((result) => result.path)
+    }
+
+    await fire("add", "giganticpage.html")
+
+    expect(await searchPaths("giganticpage")).toEqual(["giganticpage.html"])
+    expect(await searchPaths("buriedcobalt")).toEqual([])
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(pagePath)
+  })
+
   it("leaves a page that is not UTF-8 out of search", async () => {
     const { testVault, database, fire } = await createControlledWatcher()
     // 0xE9 is "é" in Latin-1 and never a complete UTF-8 sequence
diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index e1eeb3412..e30aa72fe 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -8253,7 +8253,7 @@ describe("HTML pages", () => {
     expect(await searchEach(fileIndex, ["closingamber"])).toEqual([["styled.html"]])
   })
 
-  it("finds a page over 16 MiB by its name and not by its text", async () => {
+  it("finds a page over 16 MiB by its name without reading it", async () => {
     const filler = "<p>filler</p>".repeat(Math.ceil((16 * 1024 * 1024) / 13) + 1)
     const fileIndex = await rebuildVaultOf([
       { path: "giganticpage.html", content: `<p>buriedcobalt</p>${filler}` },
@@ -8263,6 +8263,9 @@ describe("HTML pages", () => {
       ["giganticpage.html"],
       [],
     ])
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
+      expect.stringMatching(/giganticpage\.html$/),
+    )
   })
 
   it("leaves out a page that is not UTF-8 or holds a NUL byte, and keeps the rest", async () => {
diff --git a/src/vault-mcp/search/file-watcher.ts b/src/vault-mcp/search/file-watcher.ts
index 0a009dfd4..3eff7dec6 100644
--- a/src/vault-mcp/search/file-watcher.ts
+++ b/src/vault-mcp/search/file-watcher.ts
@@ -11,6 +11,7 @@ import { join, relative, resolve as resolvePath, sep } from "node:path"
 import {
   CONTENT_INDEXED_FILE_KINDS,
   INDEXING_FILE_READ_CONCURRENCY,
+  isHtmlPageIndexedByNameOnly,
   PDF_EXTRACTION_CONCURRENCY,
 } from "./search-index.js"
 import type { RebuildResult, SearchIndex } from "./search-index.js"
@@ -250,6 +251,12 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
             }
             case "html":
             case "script": {
+              const indexedByNameOnly = isHtmlPageIndexedByNameOnly({
+                filePath: relativePath,
+                fileBytes: fileStat.size,
+              })
+
+              if (indexedByNameOnly) return ""
               const decodedSource = decodeTextBuffer(await readFile(filePath))
 
               if (decodedSource.status !== "text") return null
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index 38bea1571..e742732ce 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -90,6 +90,15 @@ const MAX_INDEXED_CONTENT_BYTES = 102_400
  *  meanwhile, and attribute-heavy pages at 16 MiB already took up to 1.7 s. */
 const MAX_INDEXED_HTML_PAGE_BYTES = 16 * 1024 * 1024
 
+/** True for an HTML page that search finds by its name only, which its reader
+ *  then skips reading. */
+export const isHtmlPageIndexedByNameOnly = (params: {
+  filePath: string
+  fileBytes: number
+}): boolean => {
+  return getFileKind(params.filePath) === "html" && params.fileBytes > MAX_INDEXED_HTML_PAGE_BYTES
+}
+
 /** The text file_content_fts holds for a file, built from the text its reader
  *  supplies:
  *  - a canvas's JSON becomes its outline;
@@ -504,7 +513,7 @@ export const createSearchIndex = (
       body_tags   TEXT NOT NULL DEFAULT '[]'
     );
 
-    -- path UNINDEXED: stored for JOIN/DELETE but not searchable, saves index space
+    -- path UNINDEXED: stored so a match joins back to its note; not searchable, saves index space
     CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
       path UNINDEXED, title, content, metadata, tokenize='porter unicode61'
     );
@@ -2488,11 +2497,15 @@ export const createSearchIndex = (
       // read's try, and one such file is skipped rather than failing the rebuild.
       const readDecodedFile = async () => {
         try {
-          const [buffer, fileStat] = await Promise.all([
-            readFile(file.absolutePath),
-            stat(file.absolutePath),
-          ])
-          return { decodedText: decodeTextBuffer(buffer), fileStat }
+          const fileStat = await stat(file.absolutePath)
+          const indexedByNameOnly = isHtmlPageIndexedByNameOnly({
+            filePath: file.relativePath,
+            fileBytes: fileStat.size,
+          })
+
+          if (indexedByNameOnly)
+            return { decodedText: { status: "text", text: "" } as const, fileStat }
+          return { decodedText: decodeTextBuffer(await readFile(file.absolutePath)), fileStat }
         } catch (error) {
           logger.warn("skipped unreadable file during rebuild", {
             path: file.relativePath,

From dca8acbabfa3075287855c95d0604e8cfe8c5429 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 03:42:19 -0500
Subject: [PATCH 26/38] docs: say search holds no text from a refused page, and
 an oversized page is never read

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 907c9e87f..c352fb7e3 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -383,7 +383,7 @@ Search indexes file content in the `file_content` + `file_content_fts` tables, c
 | Scripts (`.py`/`.sh`/`.ps1`) | The file's source                                                                                                 | No       |
 
 - **HTML extraction** runs htmlparser2's tokenizer, which keeps no element stack, so unclosed tags cost no more than closed ones. Hidden elements (script, style, noscript, template, and the fallback content of iframe, noembed and noframes) end only at a closing tag with their own name, so a stray closing tag never shows hidden text. Block elements become line breaks, other whitespace collapses, and reading stops at the 100 KiB cap. Extraction stays on the main thread, and the 16 MiB page limit keeps its measured worst case under 2 seconds.
-- **HTML pages and scripts are read as bytes** and indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds a page or script that a read refuses as binary or as not UTF-8. When a watched page or script stops passing it, its stored content is removed and its file row stays.
+- **HTML pages and scripts are read as bytes** and indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds text from a page or script that a read refuses as binary or as not UTF-8. A page over 16 MiB is never read for indexing. When a watched page or script stops passing it, its stored content is removed and its file row stays.
 - **Scripts are searched by keyword only.** The markdown chunker reads a script's `# comment` lines as headings and turns `snake_case` names into one word, so embedding skips scripts before their text loads.
 
 **Opt-out:** File tools are opt-out: set `FILE_TOOLS_ENABLED=false` to hide `vault_read_file` and `vault_list_files`, and strip file tool references from server metadata and other tool descriptions. The `vault_get_outgoing_links` tool continues to report file links (it indexes from the links table, not the file tools). File config vars (`MAX_FILE_BYTES`, `MAX_IMAGE_OUTPUT_BYTES`, `MAX_PDF_RENDER_PAGES`) are still parsed when disabled.

From bd58e2eceba0583ad9539192d18c01134567f83b Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 03:55:03 -0500
Subject: [PATCH 27/38] docs: name pdf-engine as the parser layer's filesystem
 exception in the DeepWiki purpose; test: add a passing control page to the
 watcher's non-UTF-8 test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .devin/wiki.json                                    | 2 +-
 src/vault-mcp/search/__tests__/file-watcher.test.ts | 9 +++++++--
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/.devin/wiki.json b/.devin/wiki.json
index 2549eb9b4..fe4f10ae2 100644
--- a/.devin/wiki.json
+++ b/.devin/wiki.json
@@ -40,7 +40,7 @@
     },
     {
       "title": "Obsidian Markdown Parsing",
-      "purpose": "The pure parser layer in obsidian-markdown/ — no filesystem I/O: links.ts, lines.ts, frontmatter.ts, tags.ts, body-tags.ts with obsidian-remark-parser.ts and remark-ports/ (body tags on remark-parse 8, the parser Obsidian forked), callouts.ts, headings.ts, tasks.ts, recurrence.ts, memory-entries.ts, canvas.ts, file-kinds.ts, html.ts, plaintext.ts, pdf.ts, pdf-engine.ts, moment-format.ts. This layer encodes the Obsidian-parity behavior (every link form and 'New link format' mode Obsidian recognizes; both Tasks-plugin formats) that distinguishes Vault Cortex from simpler file-based integrations.",
+      "purpose": "The pure parser layer in obsidian-markdown/ — no filesystem I/O except pdf-engine.ts, which resolves pdfjs package paths from disk: links.ts, lines.ts, frontmatter.ts, tags.ts, body-tags.ts with obsidian-remark-parser.ts and remark-ports/ (body tags on remark-parse 8, the parser Obsidian forked), callouts.ts, headings.ts, tasks.ts, recurrence.ts, memory-entries.ts, canvas.ts, file-kinds.ts, html.ts, plaintext.ts, pdf.ts, pdf-engine.ts, moment-format.ts. This layer encodes the Obsidian-parity behavior (every link form and 'New link format' mode Obsidian recognizes; both Tasks-plugin formats) that distinguishes Vault Cortex from simpler file-based integrations.",
       "parent": "Architecture"
     },
     {
diff --git a/src/vault-mcp/search/__tests__/file-watcher.test.ts b/src/vault-mcp/search/__tests__/file-watcher.test.ts
index f58ed5dd4..1a17fa63c 100644
--- a/src/vault-mcp/search/__tests__/file-watcher.test.ts
+++ b/src/vault-mcp/search/__tests__/file-watcher.test.ts
@@ -1615,12 +1615,17 @@ describe("file watcher — obsolete events and embedding queues", () => {
       Buffer.from(" latinword</p>"),
     ])
     await writeFile(join(testVault, "latin1.html"), latin1Page)
+    await writeFile(join(testVault, "plain.html"), "<p>plainword</p>", "utf8")
 
     await fire("add", "latin1.html")
+    await fire("add", "plain.html")
 
-    expect(database.prepare("SELECT path FROM file_content").all()).toEqual([])
-    expect(database.prepare("SELECT path FROM non_md_files").all()).toEqual([
+    expect(database.prepare("SELECT path FROM file_content").all()).toEqual([
+      { path: "plain.html" },
+    ])
+    expect(database.prepare("SELECT path FROM non_md_files ORDER BY path").all()).toEqual([
       { path: "latin1.html" },
+      { path: "plain.html" },
     ])
   })
 

From 1683ac2ff2c7dfd3537d6138edc0a4458d07e500 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 04:05:28 -0500
Subject: [PATCH 28/38] fix(tools): name the text formats vault_search indexes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../__tests__/__snapshots__/tool-surface/default.json       | 2 +-
 .../__snapshots__/tool-surface/disabled-tools.json          | 2 +-
 .../__tests__/__snapshots__/tool-surface/embedding-off.json | 2 +-
 .../tool-surface/memory-off+embedding-off.json              | 2 +-
 .../__tests__/__snapshots__/tool-surface/memory-off.json    | 2 +-
 .../__tests__/__snapshots__/tool-surface/obsidian-sync.json | 2 +-
 .../__snapshots__/tool-surface/readonly+embedding-off.json  | 2 +-
 .../tool-surface/readonly+memory-off+embedding-off.json     | 2 +-
 .../__snapshots__/tool-surface/readonly+memory-off.json     | 2 +-
 .../__tests__/__snapshots__/tool-surface/readonly.json      | 2 +-
 src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts   | 6 +++---
 src/vault-mcp/mcp-core/tools/search-tools.ts                | 3 ++-
 12 files changed, 15 insertions(+), 14 deletions(-)

diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
index 555f74d89..f87c357e0 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
@@ -1313,7 +1313,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
index af3731b5e..f9485424f 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
@@ -1254,7 +1254,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
index 8c4903c05..b22cec1d0 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
index 67d244792..bb5ffc0d7 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
@@ -1173,7 +1173,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
index 431be1d3f..9e03a7957 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
@@ -1172,7 +1172,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
index a12d7a757..021d7925a 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
index 3ec652e98..376bb9fb6 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
@@ -795,7 +795,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
index a92e5450b..d18a50788 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
@@ -700,7 +700,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
index f99dbb170..3043dc190 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
@@ -699,7 +699,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
index e11aafebf..63da55f39 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
@@ -794,7 +794,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index e18812713..039d6ac92 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1375,7 +1375,7 @@ describe("vault_search description reflects EMBEDDING_ENABLED", () => {
     const description = findSearchDescription(registerWithConfig({}))
     const openingSentence = description.slice(0, description.indexOf(". ") + 1)
     expect(openingSentence).toBe(
-      "Hybrid search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
+      "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
     )
     expect(description).toContain("career aspirations")
     expect(description).toContain("search_mode")
@@ -1403,7 +1403,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   // only the hybrid variant says scripts match by keyword alone.
   const FILE_RESULT_WORDING = {
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only)",
+      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only)",
     filtersLeadIn:
       "Filters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:",
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`,
@@ -1419,7 +1419,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   const KEYWORD_ONLY_FILE_RESULT_WORDING = {
     ...FILE_RESULT_WORDING,
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, text files, HTML pages, and .py/.sh/.ps1 scripts)",
+      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts)",
   }
 
   it.each([
diff --git a/src/vault-mcp/mcp-core/tools/search-tools.ts b/src/vault-mcp/mcp-core/tools/search-tools.ts
index 88b4ecf25..81f920f2e 100644
--- a/src/vault-mcp/mcp-core/tools/search-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/search-tools.ts
@@ -87,8 +87,9 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   // are never embedded, which matters to a caller only while semantic matching runs.
   const scriptMatchClause = config.embeddingEnabled ? "; scripts match by keyword only" : ""
   const scriptExtensions = getExtensionsOfKind("script").join("/")
+  const textExtensions = getExtensionsOfKind("text").join("/")
   const searchedContentText = config.fileToolsEnabled
-    ? `vault notes and file content (canvas, PDF, text files, HTML pages, and ${scriptExtensions} scripts${scriptMatchClause})`
+    ? `vault notes and file content (canvas, PDF, the text formats ${textExtensions}, HTML pages, and ${scriptExtensions} scripts${scriptMatchClause})`
     : "vault notes"
   const searchResultFieldsText = config.fileToolsEnabled
     ? `path, title, snippet, score, ${tagsFieldsText}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`

From 6a51239b381a00dc8fc1f1839a8e5dc5d8200888 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 04:23:42 -0500
Subject: [PATCH 29/38] fix(tools): say search covers an HTML page's visible
 text and a text read drops a leading byte-order mark

SECURITY.md also names the image and PDF readers as the exception to
reading any UTF-8 file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                                             | 2 +-
 README.md                                                   | 2 +-
 SECURITY.md                                                 | 3 ++-
 .../__tests__/__snapshots__/tool-surface/default.json       | 4 ++--
 .../__snapshots__/tool-surface/disabled-tools.json          | 4 ++--
 .../__tests__/__snapshots__/tool-surface/embedding-off.json | 4 ++--
 .../tool-surface/memory-off+embedding-off.json              | 4 ++--
 .../__tests__/__snapshots__/tool-surface/memory-off.json    | 4 ++--
 .../__tests__/__snapshots__/tool-surface/obsidian-sync.json | 4 ++--
 .../__snapshots__/tool-surface/readonly+embedding-off.json  | 4 ++--
 .../tool-surface/readonly+memory-off+embedding-off.json     | 4 ++--
 .../__snapshots__/tool-surface/readonly+memory-off.json     | 4 ++--
 .../__tests__/__snapshots__/tool-surface/readonly.json      | 4 ++--
 src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts   | 6 +++---
 src/vault-mcp/mcp-core/tools/asset-tools.ts                 | 6 +++---
 src/vault-mcp/mcp-core/tools/search-tools.ts                | 2 +-
 16 files changed, 31 insertions(+), 30 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index c352fb7e3..d740e339b 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -349,7 +349,7 @@ Link queries use a `links` table populated during indexing:
 
 1. **Images** (`.png`/`.jpg`/`.jpeg`/`.gif`/`.webp`) return an MCP `image` content block plus a one-line metadata text block: the path, the delivered format, dimensions and bytes, and, when the image was recompressed, its original dimensions and bytes. A shared fit-to-byte-budget pipeline (`utils/fit-image-to-byte-budget.ts`, built on sharp) makes oversized images deliverable: EXIF auto-orient → resize long edge to ≤1568px → walk a fixed quality ladder (JPEG via mozjpeg for opaque images, WebP for alpha — PNG has no quality knob) → shrink dimensions by √(budget/actual) if the ladder floor still exceeds the budget. Deterministic and terminating (bounded attempts, 64px floor); sharp's default `limitInputPixels` stays active as the decompression-bomb guard. The budget (`MAX_IMAGE_OUTPUT_BYTES`, default 48 KiB binary) is sized for the tightest mainstream client cap.
 2. **Canvas** (`.canvas`) linearizes to markdown via the pure `obsidian-markdown/canvas.ts` parser ([JSON Canvas 1.0](https://jsoncanvas.org)): group membership by spatial rect containment (innermost group wins; equal rects tiebreak deterministically by id), nodes in reading order (y, then x), and an edge list with node ids resolved to display names. Lenient parsing — unknown properties ignored, malformed entries skipped. `raw: true` skips the linearizer and returns the JSON source verbatim for full structural fidelity. Canvas content is also FTS-indexed (linearized text in `file_content` + `file_content_fts` tables, gated behind `FILE_TOOLS_ENABLED`) so canvas files appear in `vault_search` results with `kind: "file"`. Canvas `file`-type node references are extracted unconditionally into the `links` table for graph queries regardless of the feature gate.
-3. **Text formats** (`.svg`/`.json`/`.txt`/`.csv`/`.xml`/`.log`/`.yaml`/`.yml`/`.base`) pass through verbatim as text, capped at a fixed 100 KiB output size (explicit error over silent truncation). They skip the NUL-byte check in item 5, so a NUL-padded log still reads. `start_line`/`limit` page any text result — text files, canvas renditions, PDF-extracted text — as a 1-based line window preceded by a window-metadata block stating the range, total line count, and next `start_line`; the cap applies to the window, and an unpaged read stays byte-exact.
+3. **Text formats** (`.svg`/`.json`/`.txt`/`.csv`/`.xml`/`.log`/`.yaml`/`.yml`/`.base`) pass through as text, without a leading byte-order mark, capped at a fixed 100 KiB output size (explicit error over silent truncation). They skip the NUL-byte check in item 5, so a NUL-padded log still reads. `start_line`/`limit` page any text result — text files, canvas renditions, PDF-extracted text — as a 1-based line window preceded by a window-metadata block stating the range, total line count, and next `start_line`; the cap applies to the window, and an unpaged read stays byte-exact.
 4. **PDFs** (`.pdf`) return structured markdown reconstructed from layout-aware extraction (`unpdf`, based on Mozilla's PDF.js):
    - A document metadata header (title, page count, link count)
    - Heading hierarchy inferred from font sizes relative to the dominant
diff --git a/README.md b/README.md
index 91a7d6c9d..14675a717 100644
--- a/README.md
+++ b/README.md
@@ -282,7 +282,7 @@ Your notes embed screenshots, reference architecture diagrams, and link out to c
 - **Images** — the image itself, not the filename. Screenshots and diagrams are downscaled and recompressed server-side when they exceed what MCP clients accept, so even a phone session can look at a 5MB architecture diagram
 - **Canvases** — a [Canvas](https://help.obsidian.md/canvas) board arrives as a readable outline: its groups, each card's content in reading order, and the connections between them. Canvas content is full-text searchable, and file references on the board appear in the link graph — backlinks and outgoing links work just like note-to-note links. The exact JSON source is one flag away when full fidelity matters
 - **PDFs** — text is extracted with heading hierarchy, code blocks, and hyperlinks preserved; PDF content is full-text searchable alongside your notes. Set `raw: true` to render pages as images instead, showing layout, diagrams, and tables that text extraction can't preserve — scanned and image-only PDFs work in this mode
-- **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written, and their first 100 KB is full-text searchable. Any other UTF-8 text file reads back the same way. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
+- **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written, apart from a leading byte-order mark, and their first 100 KB is full-text searchable. Any other UTF-8 text file reads back the same way. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
 - **HTML pages and scripts** — a saved page or generated report is searchable by the text a browser shows, never its tags or script code. Python, shell, and PowerShell scripts are searchable by keyword. Both must be UTF-8 text, and both read back as their source
 - **Browse** — list any visible folder's files with per-extension counts and file sizes; files a note links to report their size in the link graph too
 
diff --git a/SECURITY.md b/SECURITY.md
index fddfa846c..c87cb5585 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -94,7 +94,8 @@ mechanism-level detail.
   other vault file, and `vault_read_file` refuses it only because a
   SQLite file holds binary data.
 - `vault_read_file` returns any visible file whose bytes are UTF-8 text,
-  whatever its extension, so a credential kept in a visible vault folder
+  whatever its extension (a file named as an image or a PDF goes to the
+  image or PDF reader instead), so a credential kept in a visible vault folder
   (a `deploy.env` or `secrets.txt`) is readable by any signed-in client.
   Hidden files such as `.env` stay refused by the hidden-path check above.
 - The hidden-path check is lexical: a visible symlink whose target is a
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
index f87c357e0..9e7f3ac80 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
@@ -1075,7 +1075,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1313,7 +1313,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
index f9485424f..cd0d8a80e 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
@@ -1016,7 +1016,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1254,7 +1254,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
index b22cec1d0..17f247baa 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
@@ -1077,7 +1077,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
index bb5ffc0d7..5819f2355 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
@@ -935,7 +935,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1173,7 +1173,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
index 9e03a7957..f756eee0a 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
@@ -934,7 +934,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1172,7 +1172,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
index 021d7925a..320999034 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
@@ -1077,7 +1077,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
index 376bb9fb6..715d59fdf 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
@@ -653,7 +653,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -795,7 +795,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
index d18a50788..f7023f487 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
@@ -558,7 +558,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -700,7 +700,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
index 3043dc190..58b0c0cfc 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
@@ -557,7 +557,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -699,7 +699,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
index 63da55f39..bbfe502de 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
@@ -652,7 +652,7 @@
     {
       "name": "vault_read_file",
       "title": "Read File",
-      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases, PDFs, HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.",
+      "description": "Read a non-markdown vault file in its most useful form per type — the read-side companion to vault_read_note for everything that isn't a note.\n\nExample: vault_read_file({ path: \"attachments/diagram.png\" }) — the image itself, shrunk when too large\nExample: vault_read_file({ path: \"Boards/Roadmap.canvas\" }) — a readable outline of the canvas\nExample: vault_read_file({ path: \"exports/data.json\" }) — the file content as text\nExample: vault_read_file({ path: \"exports/big.csv\", limit: 500 }) — the first 500 lines\nExample: vault_read_file({ path: \"papers/research.pdf\" }) — structured text with title, headings, and links\n\nWhen to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF. Find the files a note links to (with byte sizes) via vault_get_outgoing_links. Browse a folder's files via vault_list_files. vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (.html/.htm), scripts (.py/.sh/.ps1), and the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, but not images or other files. For .md notes use vault_read_note. To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.\n\nParameters:\n- raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first 5 pages are rendered, and later pages are readable only as text, without raw.\n- start_line and limit page any text result as a line window. The text output cap (a fixed 100 KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.\n\nBehavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue (\"data.csv — lines 51–100 of 400 (continue with start_line: 101)\"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.\n\nErrors:\n- \"not a file: … is a markdown note\" — the path ends in .md; read notes with vault_read_note\n- \"file not found\" — no file exists at that path (a folder is not a file); discover valid paths via vault_list_files\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — pass a vault-relative path with no dot-prefixed part\n- \"file too large\" — the file exceeds the file-size cap (MAX_FILE_BYTES, default 50 MiB), which the server's operator can raise\n- \"text output too large\" — a text file, canvas, or PDF renders past the text output cap; page it with start_line and limit, or reduce limit when a single window overflows\n- \"start line past the end\" — start_line exceeds the file's line count; the error states the total, so retry with a smaller start_line\n- \"line range is not available\" (start_line or limit on an image, or on a PDF read with raw: true) / \"raw source is not available for images\" (raw on an image) — drop that input\n- \"not valid UTF-8\" — the file's bytes aren't UTF-8 text; ask for a UTF-8 copy\n- \"invalid .canvas JSON\" — the canvas file is empty or not valid JSON; set raw: true to read its source as text\n- \"PDF has no extractable text\" — the PDF contains no text (scanned or image-only); the error states the page count. Set raw: true to render pages as images instead\n- \"PDF is password-protected\" — read an unprotected copy instead\n- \"PDF is damaged or not a PDF\" / \"could not decode image\" — the PDF does not parse, or the image is empty, damaged, not an image despite its extension, or over about 268 million pixels; any other PDF or image error comes back in the reading library's own words. Replace or re-export the file\n- \"PDF page rendering failed\" — read it without raw: true to get its text instead; if that read also finds no text, this tool can't read the PDF\n- \"image cannot be fitted into …\" — the image is over the image output budget even after shrinking; ask the server's operator to raise MAX_IMAGE_OUTPUT_BYTES\n- \"ENAMETOOLONG: …\" or another filesystem error — the message says what to do\n- \"file changed while reading\" — retry the read\n- \"PDF reader could not start\" — the server's PDF reader failed to load; retry once, then ask the server's operator to restart the server\n- \"unsupported file type …\" — the file holds binary data (audio, archives, UTF-16 text, …); the error names the readable types plus the file's existence and size. Ask for a UTF-8 copy of UTF-16 text\n\nReturns: by file type:\n- Images (.png/.jpg/.jpeg/.gif/.webp): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (49152 bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.\n- Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.\n- PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).\n- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -794,7 +794,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index 039d6ac92..0158c4bd0 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1375,7 +1375,7 @@ describe("vault_search description reflects EMBEDDING_ENABLED", () => {
     const description = findSearchDescription(registerWithConfig({}))
     const openingSentence = description.slice(0, description.indexOf(". ") + 1)
     expect(openingSentence).toBe(
-      "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
+      "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
     )
     expect(description).toContain("career aspirations")
     expect(description).toContain("search_mode")
@@ -1403,7 +1403,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   // only the hybrid variant says scripts match by keyword alone.
   const FILE_RESULT_WORDING = {
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only)",
+      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only)",
     filtersLeadIn:
       "Filters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:",
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`,
@@ -1419,7 +1419,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   const KEYWORD_ONLY_FILE_RESULT_WORDING = {
     ...FILE_RESULT_WORDING,
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, HTML pages, and .py/.sh/.ps1 scripts)",
+      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts)",
   }
 
   it.each([
diff --git a/src/vault-mcp/mcp-core/tools/asset-tools.ts b/src/vault-mcp/mcp-core/tools/asset-tools.ts
index 49fb47d22..1daebe4b6 100644
--- a/src/vault-mcp/mcp-core/tools/asset-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/asset-tools.ts
@@ -120,13 +120,13 @@ Example: vault_read_file({ path: "exports/data.json" }) — the file content as
 Example: vault_read_file({ path: "exports/big.csv", limit: 500 }) — the first 500 lines
 Example: vault_read_file({ path: "papers/research.pdf" }) — structured text with title, headings, and links
 
-When to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF.${whenToolEnabledText("vault_get_outgoing_links", " Find the files a note links to (with byte sizes) via vault_get_outgoing_links.")}${whenToolEnabledText("vault_list_files", " Browse a folder's files via vault_list_files.")}${whenToolEnabledText("vault_search", ` vault_search also indexes the content of canvases, PDFs, HTML pages (${htmlExtensions}), scripts (${scriptExtensions}), and the text formats ${textExtensions}, but not images or other files.`)}${whenToolEnabledText("vault_read_note", " For .md notes use vault_read_note.")} To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.
+When to use: whenever a note references a file you need to actually see or read — an embedded diagram, a linked canvas, data file, or PDF.${whenToolEnabledText("vault_get_outgoing_links", " Find the files a note links to (with byte sizes) via vault_get_outgoing_links.")}${whenToolEnabledText("vault_list_files", " Browse a folder's files via vault_list_files.")}${whenToolEnabledText("vault_search", ` vault_search also indexes the content of canvases and PDFs, the visible text of HTML pages (${htmlExtensions}), scripts (${scriptExtensions}), and the text formats ${textExtensions}, but not images or other files.`)}${whenToolEnabledText("vault_read_note", " For .md notes use vault_read_note.")} To check a large file's line count before reading it whole, request start_line: 1 with limit: 1 — one line plus the total.
 
 Parameters:
 - raw: true switches a canvas or PDF to its other form. A canvas returns its exact JSON source (geometry, ids, colors) instead of the outline. A PDF returns each page rendered as an image instead of extracted text, showing layout, diagrams, tables, and formatting; only the first ${config.maxPdfRenderPages} pages are rendered, and later pages are readable only as text, without raw.
 - start_line and limit page any text result as a line window. The text output cap (a fixed ${MAX_TEXT_OUTPUT_BYTES / 1024} KiB) applies to each window, so one very long line can still overflow it; paging never gets around the file-size cap.
 
-Behavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue ("data.csv — lines 51–100 of 400 (continue with start_line: 101)"); an unpaged read of a text file returns the file byte-exact.
+Behavior: A paged window comes back with \\n line endings and no trailing newline, preceded by a metadata line stating the window, the total line count, and where to continue ("data.csv — lines 51–100 of 400 (continue with start_line: 101)"); an unpaged read of a text file returns the file byte-exact, except that a leading byte-order mark is dropped.
 
 Errors:
 - "not a file: … is a markdown note" — the path ends in .md${whenToolEnabledText("vault_read_note", "; read notes with vault_read_note")}
@@ -152,7 +152,7 @@ Returns: by file type:
 - Images (${imageExtensions}): an image content block plus a one-line metadata text block. The image is downscaled and recompressed when it exceeds the image output budget (${config.maxImageOutputBytes} bytes) or has a longer side over 1568 pixels; an animated GIF is reduced to its first frame when recompressed.
 - Canvas (.canvas): one text block holding a readable markdown outline — groups, node content in reading order, and a connections list with edge labels.
 - PDFs (.pdf): one text block of structured text with document metadata — title, page count, heading hierarchy, code blocks and inline code, page separators, and a links footer; with raw: true, a metadata text block followed by alternating image and text blocks (one pair per page).
-- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content verbatim.`,
+- Any other UTF-8 text file (.svg, .json, .csv, .html, .py, no extension, …): one text block holding the file content.`,
       inputSchema: {
         path: z
           .string()
diff --git a/src/vault-mcp/mcp-core/tools/search-tools.ts b/src/vault-mcp/mcp-core/tools/search-tools.ts
index 81f920f2e..d0e268eda 100644
--- a/src/vault-mcp/mcp-core/tools/search-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/search-tools.ts
@@ -89,7 +89,7 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   const scriptExtensions = getExtensionsOfKind("script").join("/")
   const textExtensions = getExtensionsOfKind("text").join("/")
   const searchedContentText = config.fileToolsEnabled
-    ? `vault notes and file content (canvas, PDF, the text formats ${textExtensions}, HTML pages, and ${scriptExtensions} scripts${scriptMatchClause})`
+    ? `vault notes and file content (canvas, PDF, the text formats ${textExtensions}, the visible text of HTML pages, and ${scriptExtensions} scripts${scriptMatchClause})`
     : "vault notes"
   const searchResultFieldsText = config.fileToolsEnabled
     ? `path, title, snippet, score, ${tagsFieldsText}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`

From 7b480c3d189bc9fb400c1b184c74ec5e95f6c160 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 05:12:29 -0500
Subject: [PATCH 30/38] fix(tools): name search's per-file text cap and the
 HTML page limit

- vault_search says each file's first 100 KiB of text is searched, and
  that HTML visible text is searched for pages up to 16 MiB.
- The reader comments, ARCHITECTURE.md and README say a larger page is
  never read and is found by its name; ARCHITECTURE.md item 3 and
  SECURITY.md now state the byte-order-mark and markdown exceptions.
- fileTextToIndexedText checks the page size through
  isHtmlPageIndexedByNameOnly, and the embedding file filter reads a
  named field.
- Tests: both 16 MiB tests refuse a two-argument read of the page; a
  script over 16 MiB is found by its text; a read drops a leading
  byte-order mark from a text format and an HTML page; a rebuild with
  file tools off runs no file embedding pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .devin/wiki.json                              |  2 +-
 ARCHITECTURE.md                               |  4 +-
 README.md                                     |  2 +-
 SECURITY.md                                   |  8 +--
 .../__snapshots__/tool-surface/default.json   |  2 +-
 .../tool-surface/disabled-tools.json          |  2 +-
 .../tool-surface/embedding-off.json           |  2 +-
 .../memory-off+embedding-off.json             |  2 +-
 .../tool-surface/memory-off.json              |  2 +-
 .../tool-surface/obsidian-sync.json           |  2 +-
 .../tool-surface/readonly+embedding-off.json  |  2 +-
 .../readonly+memory-off+embedding-off.json    |  2 +-
 .../tool-surface/readonly+memory-off.json     |  2 +-
 .../__snapshots__/tool-surface/readonly.json  |  2 +-
 .../__tests__/tool-definitions.test.ts        |  6 +--
 src/vault-mcp/mcp-core/tools/search-tools.ts  |  3 +-
 .../search/__tests__/file-watcher.test.ts     |  2 +
 .../search/__tests__/search-index.test.ts     | 53 +++++++++++++++++++
 src/vault-mcp/search/file-watcher.ts          |  8 ++-
 src/vault-mcp/search/search-index.ts          | 25 ++++-----
 .../__tests__/asset-operations.test.ts        | 21 ++++++++
 21 files changed, 118 insertions(+), 36 deletions(-)

diff --git a/.devin/wiki.json b/.devin/wiki.json
index fe4f10ae2..f119431f3 100644
--- a/.devin/wiki.json
+++ b/.devin/wiki.json
@@ -40,7 +40,7 @@
     },
     {
       "title": "Obsidian Markdown Parsing",
-      "purpose": "The pure parser layer in obsidian-markdown/ — no filesystem I/O except pdf-engine.ts, which resolves pdfjs package paths from disk: links.ts, lines.ts, frontmatter.ts, tags.ts, body-tags.ts with obsidian-remark-parser.ts and remark-ports/ (body tags on remark-parse 8, the parser Obsidian forked), callouts.ts, headings.ts, tasks.ts, recurrence.ts, memory-entries.ts, canvas.ts, file-kinds.ts, html.ts, plaintext.ts, pdf.ts, pdf-engine.ts, moment-format.ts. This layer encodes the Obsidian-parity behavior (every link form and 'New link format' mode Obsidian recognizes; both Tasks-plugin formats) that distinguishes Vault Cortex from simpler file-based integrations.",
+      "purpose": "The pure parser layer in obsidian-markdown/: links.ts, lines.ts, frontmatter.ts, tags.ts, body-tags.ts with obsidian-remark-parser.ts and remark-ports/ (body tags on remark-parse 8, the parser Obsidian forked), callouts.ts, headings.ts, tasks.ts, recurrence.ts, memory-entries.ts, canvas.ts, file-kinds.ts, html.ts, plaintext.ts, pdf.ts, pdf-engine.ts, moment-format.ts. None does filesystem I/O except pdf-engine.ts, which resolves pdfjs package paths from disk. This layer encodes the Obsidian-parity behavior (every link form and 'New link format' mode Obsidian recognizes; both Tasks-plugin formats) that distinguishes Vault Cortex from simpler file-based integrations.",
       "parent": "Architecture"
     },
     {
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index d740e339b..598ab7afc 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -349,7 +349,7 @@ Link queries use a `links` table populated during indexing:
 
 1. **Images** (`.png`/`.jpg`/`.jpeg`/`.gif`/`.webp`) return an MCP `image` content block plus a one-line metadata text block: the path, the delivered format, dimensions and bytes, and, when the image was recompressed, its original dimensions and bytes. A shared fit-to-byte-budget pipeline (`utils/fit-image-to-byte-budget.ts`, built on sharp) makes oversized images deliverable: EXIF auto-orient → resize long edge to ≤1568px → walk a fixed quality ladder (JPEG via mozjpeg for opaque images, WebP for alpha — PNG has no quality knob) → shrink dimensions by √(budget/actual) if the ladder floor still exceeds the budget. Deterministic and terminating (bounded attempts, 64px floor); sharp's default `limitInputPixels` stays active as the decompression-bomb guard. The budget (`MAX_IMAGE_OUTPUT_BYTES`, default 48 KiB binary) is sized for the tightest mainstream client cap.
 2. **Canvas** (`.canvas`) linearizes to markdown via the pure `obsidian-markdown/canvas.ts` parser ([JSON Canvas 1.0](https://jsoncanvas.org)): group membership by spatial rect containment (innermost group wins; equal rects tiebreak deterministically by id), nodes in reading order (y, then x), and an edge list with node ids resolved to display names. Lenient parsing — unknown properties ignored, malformed entries skipped. `raw: true` skips the linearizer and returns the JSON source verbatim for full structural fidelity. Canvas content is also FTS-indexed (linearized text in `file_content` + `file_content_fts` tables, gated behind `FILE_TOOLS_ENABLED`) so canvas files appear in `vault_search` results with `kind: "file"`. Canvas `file`-type node references are extracted unconditionally into the `links` table for graph queries regardless of the feature gate.
-3. **Text formats** (`.svg`/`.json`/`.txt`/`.csv`/`.xml`/`.log`/`.yaml`/`.yml`/`.base`) pass through as text, without a leading byte-order mark, capped at a fixed 100 KiB output size (explicit error over silent truncation). They skip the NUL-byte check in item 5, so a NUL-padded log still reads. `start_line`/`limit` page any text result — text files, canvas renditions, PDF-extracted text — as a 1-based line window preceded by a window-metadata block stating the range, total line count, and next `start_line`; the cap applies to the window, and an unpaged read stays byte-exact.
+3. **Text formats** (`.svg`/`.json`/`.txt`/`.csv`/`.xml`/`.log`/`.yaml`/`.yml`/`.base`) pass through as text, without a leading byte-order mark, capped at a fixed 100 KiB output size (explicit error over silent truncation). They skip the NUL-byte check in item 5, so a NUL-padded log still reads. `start_line`/`limit` page any text result — text files, canvas renditions, PDF-extracted text — as a 1-based line window preceded by a window-metadata block stating the range, total line count, and next `start_line`; the cap applies to the window, and an unpaged read is byte-exact apart from that mark.
 4. **PDFs** (`.pdf`) return structured markdown reconstructed from layout-aware extraction (`unpdf`, based on Mozilla's PDF.js):
    - A document metadata header (title, page count, link count)
    - Heading hierarchy inferred from font sizes relative to the dominant
@@ -383,7 +383,7 @@ Search indexes file content in the `file_content` + `file_content_fts` tables, c
 | Scripts (`.py`/`.sh`/`.ps1`) | The file's source                                                                                                 | No       |
 
 - **HTML extraction** runs htmlparser2's tokenizer, which keeps no element stack, so unclosed tags cost no more than closed ones. Hidden elements (script, style, noscript, template, and the fallback content of iframe, noembed and noframes) end only at a closing tag with their own name, so a stray closing tag never shows hidden text. Block elements become line breaks, other whitespace collapses, and reading stops at the 100 KiB cap. Extraction stays on the main thread, and the 16 MiB page limit keeps its measured worst case under 2 seconds.
-- **HTML pages and scripts are read as bytes** and indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds text from a page or script that a read refuses as binary or as not UTF-8. A page over 16 MiB is never read for indexing. When a watched page or script stops passing it, its stored content is removed and its file row stays.
+- **HTML pages and scripts are read as bytes**, and their text is indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds text from a page or script that a read refuses as binary or as not UTF-8. A page over 16 MiB is never read, so search finds it by name even when a read refuses it. When a watched page or script stops passing that test, its stored content is removed and its file row stays.
 - **Scripts are searched by keyword only.** The markdown chunker reads a script's `# comment` lines as headings and turns `snake_case` names into one word, so embedding skips scripts before their text loads.
 
 **Opt-out:** File tools are opt-out: set `FILE_TOOLS_ENABLED=false` to hide `vault_read_file` and `vault_list_files`, and strip file tool references from server metadata and other tool descriptions. The `vault_get_outgoing_links` tool continues to report file links (it indexes from the links table, not the file tools). File config vars (`MAX_FILE_BYTES`, `MAX_IMAGE_OUTPUT_BYTES`, `MAX_PDF_RENDER_PAGES`) are still parsed when disabled.
diff --git a/README.md b/README.md
index 14675a717..6ce3300f0 100644
--- a/README.md
+++ b/README.md
@@ -283,7 +283,7 @@ Your notes embed screenshots, reference architecture diagrams, and link out to c
 - **Canvases** — a [Canvas](https://help.obsidian.md/canvas) board arrives as a readable outline: its groups, each card's content in reading order, and the connections between them. Canvas content is full-text searchable, and file references on the board appear in the link graph — backlinks and outgoing links work just like note-to-note links. The exact JSON source is one flag away when full fidelity matters
 - **PDFs** — text is extracted with heading hierarchy, code blocks, and hyperlinks preserved; PDF content is full-text searchable alongside your notes. Set `raw: true` to render pages as images instead, showing layout, diagrams, and tables that text extraction can't preserve — scanned and image-only PDFs work in this mode
 - **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written, apart from a leading byte-order mark, and their first 100 KB is full-text searchable. Any other UTF-8 text file reads back the same way. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
-- **HTML pages and scripts** — a saved page or generated report is searchable by the text a browser shows, never its tags or script code. Python, shell, and PowerShell scripts are searchable by keyword. Both must be UTF-8 text, and both read back as their source
+- **HTML pages and scripts** — a saved page or generated report is searchable by the first 100 KB of the text a browser shows, never its tags or script code; a page over 16 MB is searchable by name only. Python, shell, and PowerShell scripts are searchable by keyword. Both must be UTF-8 text, and both read back as their source
 - **Browse** — list any visible folder's files with per-extension counts and file sizes; files a note links to report their size in the link graph too
 
 Set `FILE_TOOLS_ENABLED=false` to hide the file tools — useful when your remote vault syncs without attachments.
diff --git a/SECURITY.md b/SECURITY.md
index c87cb5585..41c9cb4d4 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -93,10 +93,10 @@ mechanism-level detail.
   _visible_ vault folder — there `vault_list_files` lists it like any
   other vault file, and `vault_read_file` refuses it only because a
   SQLite file holds binary data.
-- `vault_read_file` returns any visible file whose bytes are UTF-8 text,
-  whatever its extension (a file named as an image or a PDF goes to the
-  image or PDF reader instead), so a credential kept in a visible vault folder
-  (a `deploy.env` or `secrets.txt`) is readable by any signed-in client.
+- `vault_read_file` returns any visible non-markdown file whose bytes are
+  UTF-8 text, whatever its extension, so a credential kept in a visible vault
+  folder (a `deploy.env` or `secrets.txt`) is readable by any signed-in client.
+  A file named as an image or a PDF goes to the image or PDF reader instead.
   Hidden files such as `.env` stay refused by the hidden-path check above.
 - The hidden-path check is lexical: a visible symlink whose target is a
   hidden path is followed. Creating such a symlink requires direct
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
index 9e7f3ac80..81377c961 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
@@ -1313,7 +1313,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
index cd0d8a80e..bfac981cd 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
@@ -1254,7 +1254,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
index 17f247baa..8f393d01a 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
index 5819f2355..9b22339e8 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
@@ -1173,7 +1173,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
index f756eee0a..ded3e9196 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
@@ -1172,7 +1172,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
index 320999034..74d92a875 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
index 715d59fdf..5e9f9a3da 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
@@ -795,7 +795,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
index f7023f487..ed75b8436 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
@@ -700,7 +700,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
index 58b0c0cfc..eca82b923 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
@@ -699,7 +699,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
index bbfe502de..a1da102cf 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
@@ -794,7 +794,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds.\n\nErrors:\n- No matches returns an empty results array with total 0, not an error\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\")\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index 0158c4bd0..b4059a66e 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1375,7 +1375,7 @@ describe("vault_search description reflects EMBEDDING_ENABLED", () => {
     const description = findSearchDescription(registerWithConfig({}))
     const openingSentence = description.slice(0, description.indexOf(". ") + 1)
     expect(openingSentence).toBe(
-      "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
+      "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
     )
     expect(description).toContain("career aspirations")
     expect(description).toContain("search_mode")
@@ -1403,7 +1403,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   // only the hybrid variant says scripts match by keyword alone.
   const FILE_RESULT_WORDING = {
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; scripts match by keyword only)",
+      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only)",
     filtersLeadIn:
       "Filters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:",
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`,
@@ -1419,7 +1419,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   const KEYWORD_ONLY_FILE_RESULT_WORDING = {
     ...FILE_RESULT_WORDING,
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts)",
+      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched)",
   }
 
   it.each([
diff --git a/src/vault-mcp/mcp-core/tools/search-tools.ts b/src/vault-mcp/mcp-core/tools/search-tools.ts
index d0e268eda..f9970cf59 100644
--- a/src/vault-mcp/mcp-core/tools/search-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/search-tools.ts
@@ -6,6 +6,7 @@ import type { ToolRegistrationContext } from "./tool-helpers.js"
 import { readEffectiveOrphanExcludeFolders } from "../../vault-operations/vault-folder-config.js"
 import { readDailyNotesConfig } from "../../vault-operations/daily-notes.js"
 import { getExtensionsOfKind } from "../../obsidian-markdown/file-kinds.js"
+import { MAX_INDEXED_CONTENT_BYTES } from "../../search/search-index.js"
 import {
   createStrictInputObject,
   describeNoteMetadataResult,
@@ -89,7 +90,7 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   const scriptExtensions = getExtensionsOfKind("script").join("/")
   const textExtensions = getExtensionsOfKind("text").join("/")
   const searchedContentText = config.fileToolsEnabled
-    ? `vault notes and file content (canvas, PDF, the text formats ${textExtensions}, the visible text of HTML pages, and ${scriptExtensions} scripts${scriptMatchClause})`
+    ? `vault notes and file content (canvas, PDF, the text formats ${textExtensions}, the visible text of HTML pages up to 16 MiB, and ${scriptExtensions} scripts; each file's first ${MAX_INDEXED_CONTENT_BYTES / 1024} KiB of text is searched${scriptMatchClause})`
     : "vault notes"
   const searchResultFieldsText = config.fileToolsEnabled
     ? `path, title, snippet, score, ${tagsFieldsText}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`
diff --git a/src/vault-mcp/search/__tests__/file-watcher.test.ts b/src/vault-mcp/search/__tests__/file-watcher.test.ts
index 1a17fa63c..361df1262 100644
--- a/src/vault-mcp/search/__tests__/file-watcher.test.ts
+++ b/src/vault-mcp/search/__tests__/file-watcher.test.ts
@@ -1603,7 +1603,9 @@ describe("file watcher — obsolete events and embedding queues", () => {
 
     expect(await searchPaths("giganticpage")).toEqual(["giganticpage.html"])
     expect(await searchPaths("buriedcobalt")).toEqual([])
+    // readFile takes at most two arguments, so these two cover every read of the page
     expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(pagePath)
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(pagePath, expect.anything())
   })
 
   it("leaves a page that is not UTF-8 out of search", async () => {
diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index e30aa72fe..f03d707a9 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -8263,9 +8263,14 @@ describe("HTML pages", () => {
       ["giganticpage.html"],
       [],
     ])
+    // readFile takes at most two arguments, so these two cover every read of the page
     expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
       expect.stringMatching(/giganticpage\.html$/),
     )
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
+      expect.stringMatching(/giganticpage\.html$/),
+      expect.anything(),
+    )
   })
 
   it("leaves out a page that is not UTF-8 or holds a NUL byte, and keeps the rest", async () => {
@@ -8401,6 +8406,15 @@ describe("scripts", () => {
     })
   })
 
+  it("finds a script over 16 MiB by its text, since the page size limit is for HTML only", async () => {
+    const filler = "# filler\n".repeat(Math.ceil((16 * 1024 * 1024) / 9) + 1)
+    const { database } = await rebuildVaultOf({
+      files: [{ path: "giganticscript.py", content: `buriedjasper = 1\n${filler}` }],
+    })
+
+    expect(keywordPaths(database, "buriedjasper")).toEqual(["giganticscript.py"])
+  })
+
   it("leaves a script holding a NUL byte out of search", async () => {
     const { database } = await rebuildVaultOf({
       files: [
@@ -9118,6 +9132,45 @@ describe("file content vector embeddings", () => {
       expect(vectorCount.count).toBe(1)
     })
   })
+
+  it("runs no file embedding pass after a rebuild with file tools off, though canvases still index", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "file-tools-off-embedding-"))
+    onTestFinished(() => rm(dir, { recursive: true, force: true }))
+    const vaultPath = join(dir, "vault")
+    await mkdir(vaultPath)
+    await writeFile(join(vaultPath, "note.md"), "A note the canvas embeds.")
+    await writeFile(
+      join(vaultPath, "board.canvas"),
+      JSON.stringify({
+        nodes: [{ id: "a", type: "file", x: 0, y: 0, width: 100, height: 100, file: "note.md" }],
+        edges: [],
+      }),
+    )
+    const infoSpy = vi.spyOn(logger, "info").mockImplementation(() => {})
+    onTestFinished(() => infoSpy.mockRestore())
+    const index = createSearchIndex(":memory:", createMockEmbedder(), undefined, {
+      fileToolsEnabled: false,
+    })
+
+    const rebuilt = await index.rebuildFromVault(
+      { vaultPath, bodyTagParser: inProcessBodyTagParser },
+      logger,
+    )
+    await rebuilt.embedding
+
+    // The canvas still indexes for its links, so it reached the rebuild's file list
+    expect(
+      index.getBacklinks({ path: "note.md" }, logger).map((backlink) => backlink.path),
+    ).toEqual(["board.canvas"])
+    expect(infoSpy).toHaveBeenCalledWith("embedding pass complete", {
+      notes: 1,
+      chunksEmbedded: 1,
+    })
+    expect(infoSpy).not.toHaveBeenCalledWith(
+      "file content embedding pass complete",
+      expect.anything(),
+    )
+  })
 })
 
 describe("trash entries (retention-sweep bookkeeping)", () => {
diff --git a/src/vault-mcp/search/file-watcher.ts b/src/vault-mcp/search/file-watcher.ts
index 3eff7dec6..90afc54d5 100644
--- a/src/vault-mcp/search/file-watcher.ts
+++ b/src/vault-mcp/search/file-watcher.ts
@@ -237,8 +237,12 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
 
     if (isCanvas || isIndexableNonCanvas) {
       try {
-        /** The file's text, or null for an HTML page or script that is not
-         *  UTF-8 or holds a NUL byte early on, which vault_read_file refuses too. */
+        /** The text to index for the file:
+         *  - empty for an HTML page too large to extract, which is never read, so
+         *    its file_content row still lets search find it by name;
+         *  - null for an HTML page or script that is not UTF-8 or holds a NUL byte
+         *    early on, which vault_read_file refuses too;
+         *  - the file's text otherwise. */
         const readContentToIndex = async (): Promise<string | null> => {
           switch (fileKind) {
             case "pdf": {
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index e742732ce..c159170f0 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -83,15 +83,15 @@ const EMBEDDED_FILE_KINDS: ReadonlySet<FileKind> = new Set(["canvas", "pdf", "te
 
 /** Cap on rendered content indexed into file_content_fts — prevents
  *  pathological FTS rows from large CSVs or verbose JSONs. */
-const MAX_INDEXED_CONTENT_BYTES = 102_400
+export const MAX_INDEXED_CONTENT_BYTES = 102_400
 
 /** An HTML page larger than this is indexed by its name only, like a scanned
  *  PDF. Extracting its text runs on the main thread, which answers no request
  *  meanwhile, and attribute-heavy pages at 16 MiB already took up to 1.7 s. */
 const MAX_INDEXED_HTML_PAGE_BYTES = 16 * 1024 * 1024
 
-/** True for an HTML page that search finds by its name only, which its reader
- *  then skips reading. */
+/** True for an HTML page too large to extract. Search finds such a page by its
+ *  name only, so indexing never reads it. */
 export const isHtmlPageIndexedByNameOnly = (params: {
   filePath: string
   fileBytes: number
@@ -113,7 +113,7 @@ const fileTextToIndexedText = (params: {
     case "canvas":
       return linearizeCanvas(params.fileText)
     case "html":
-      if (params.fileBytes > MAX_INDEXED_HTML_PAGE_BYTES) return ""
+      if (isHtmlPageIndexedByNameOnly(params)) return ""
       return extractHtmlVisibleText({
         html: params.fileText,
         maxBytes: MAX_INDEXED_CONTENT_BYTES,
@@ -513,7 +513,8 @@ export const createSearchIndex = (
       body_tags   TEXT NOT NULL DEFAULT '[]'
     );
 
-    -- path UNINDEXED: stored so a match joins back to its note; not searchable, saves index space
+    -- A search match joins back to its notes row by path. UNINDEXED keeps
+    -- path out of keyword matching and saves index space.
     CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
       path UNINDEXED, title, content, metadata, tokenize='porter unicode61'
     );
@@ -2487,9 +2488,12 @@ export const createSearchIndex = (
     })
     const textFileContents = textFileContentResults.filter((entry) => entry !== null)
 
-    /** Reads an HTML page or script as bytes and keeps it only when the bytes
-     *  are UTF-8 with no NUL byte early on, the test vault_read_file applies,
-     *  so search never holds text that a read refuses. */
+    /** Reads an HTML page or script for indexing:
+     *  - a page too large to extract is never read and keeps empty text, so its
+     *    file_content row still lets search find it by name;
+     *  - any other file keeps its text only when its bytes are UTF-8 with no NUL
+     *    byte early on, the test vault_read_file applies, so search never holds
+     *    text that a read refuses. */
     const readHtmlOrScriptFile = async (
       file: RebuildFilePaths,
     ): Promise<RebuildFileContent | null> => {
@@ -2733,13 +2737,10 @@ export const createSearchIndex = (
     // Files of an embedded kind whose text this rebuild indexed. Each file's
     // text loads from file_content only when the embedding pass reaches it,
     // so the pass holds one file's text at a time.
-    const isEmbeddedFilePath = ([filePath]: [string, symbol]): boolean => {
-      return EMBEDDED_FILE_KINDS.has(getFileKind(filePath))
-    }
     const filesForEmbedding = fileContentVectorEnabled
       ? [...fileVersionsForEmbedding]
-          .filter(isEmbeddedFilePath)
           .map(([path, sourceVersion]) => ({ path, sourceVersion }))
+          .filter((file) => EMBEDDED_FILE_KINDS.has(getFileKind(file.path)))
       : []
     // Every note read from disk, including notes that failed to index, unlike indexedNotes
     const readableNotePaths = new Set(noteContents.map((note) => note.relativePath))
diff --git a/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts b/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
index e3b7fba8c..45695a4fc 100644
--- a/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
+++ b/src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
@@ -1130,6 +1130,27 @@ describe("readAssetContent — UTF-8 files outside the dedicated types", () => {
   })
 })
 
+// The tool text says a read drops a leading byte-order mark, so both decode
+// paths are pinned: text formats and every other UTF-8 file
+describe("readAssetContent — byte-order mark", () => {
+  const BYTE_ORDER_MARK = Buffer.from([0xef, 0xbb, 0xbf])
+
+  it.each([
+    { label: "a text format", path: "exports/data.json", extension: ".json", source: '{"a":1}\n' },
+    { label: "an HTML page", path: "pages/home.html", extension: ".html", source: "<p>hi</p>\n" },
+  ])(
+    "drops a leading byte-order mark from $label and keeps the rest byte-exact",
+    async ({ path, extension, source }) => {
+      const buffer = Buffer.concat([BYTE_ORDER_MARK, Buffer.from(source)])
+      mockedReadAsset.mockResolvedValue({ buffer, bytes: buffer.length, extension })
+
+      const result = await assetOperations.readAssetContent({ ...defaultParams, path }, logger)
+
+      expect(result).toEqual({ kind: "text", text: source, path })
+    },
+  )
+})
+
 // Each stub reports the extension lowercased, as readAsset does, while the path
 // keeps the caller's uppercase extension
 describe("readAssetContent — uppercase extensions", () => {

From 4001916e1070cd6eefe036b25062b9f8014769e7 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 13:22:41 -0500
Subject: [PATCH 31/38] fix(search): read no more of a script or text file than
 search keeps

Indexing read every script and text-format file whole, though search
keeps only a file's first 100 KiB, so one very large file could spike
memory, with up to 16 such reads at once during a rebuild.

- Text formats read only their first 100 KiB through a new
  readFileTextPrefix helper, which decodes the way readFile does.
  Search results do not change.
- A script over 16 MiB is never read and is found by its name only, as
  an HTML page over that size already is. A script's UTF-8 check needs
  the whole file, so its read cannot stop at 100 KiB.
- vault_search, README and ARCHITECTURE say a page or script over
  16 MiB is found by its name only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                               |   6 +-
 README.md                                     |   2 +-
 src/utils/__tests__/fs.test.ts                |  54 ++++++++-
 src/utils/fs.ts                               |  20 ++++
 .../__snapshots__/tool-surface/default.json   |   2 +-
 .../tool-surface/disabled-tools.json          |   2 +-
 .../tool-surface/embedding-off.json           |   2 +-
 .../memory-off+embedding-off.json             |   2 +-
 .../tool-surface/memory-off.json              |   2 +-
 .../tool-surface/obsidian-sync.json           |   2 +-
 .../tool-surface/readonly+embedding-off.json  |   2 +-
 .../readonly+memory-off+embedding-off.json    |   2 +-
 .../tool-surface/readonly+memory-off.json     |   2 +-
 .../__snapshots__/tool-surface/readonly.json  |   2 +-
 .../__tests__/tool-definitions.test.ts        |   6 +-
 src/vault-mcp/mcp-core/tools/search-tools.ts  |   7 +-
 .../search/__tests__/file-watcher.test.ts     |  83 +++++++++++---
 .../search/__tests__/search-index.test.ts     | 106 ++++++++++++++++--
 src/vault-mcp/search/file-watcher.ts          |  32 ++++--
 src/vault-mcp/search/search-index.ts          |  57 ++++++----
 20 files changed, 323 insertions(+), 70 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index c7da8217d..9bba0d3a2 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -378,12 +378,12 @@ Search indexes file content in the `file_content` + `file_content_fts` tables, c
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
 | Canvas                       | Linearized outline; file cards also go to the link graph (see Canvas above)                                       | Yes      |
 | PDF                          | Text extracted by `obsidian-markdown/pdf.ts`; a scanned or image-only PDF has none and is found by file name only | Yes      |
-| Text formats (item 3)        | The file's content, with bytes that are not UTF-8 replaced rather than refused                                    | Yes      |
+| Text formats (item 3)        | The file's first 100 KiB, the only part read, with bytes that are not UTF-8 replaced rather than refused          | Yes      |
 | HTML (`.html`/`.htm`)        | The text a browser shows, from `obsidian-markdown/html.ts`; a page over 16 MiB is found by file name only         | Yes      |
-| Scripts (`.py`/`.sh`/`.ps1`) | The file's source                                                                                                 | No       |
+| Scripts (`.py`/`.sh`/`.ps1`) | The file's source; a script over 16 MiB is found by file name only                                                | No       |
 
 - **HTML extraction** runs htmlparser2's tokenizer, which keeps no element stack, so unclosed tags cost no more than closed ones. Hidden elements (script, style, noscript, template, and the fallback content of iframe, noembed and noframes) end only at a closing tag with their own name, so a stray closing tag never shows hidden text. Block elements become line breaks, other whitespace collapses, and reading stops at the 100 KiB cap. Extraction stays on the main thread, and the 16 MiB page limit keeps its measured worst case under 2 seconds.
-- **HTML pages and scripts are read as bytes**, and their text is indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds text from a page or script that a read refuses as binary or as not UTF-8. A page over 16 MiB is never read, so search finds it by name even when a read refuses it. When a watched page or script stops passing that test, its stored content is removed and its file row stays.
+- **HTML pages and scripts are read as bytes**, and their text is indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds text from a page or script that a read refuses as binary or as not UTF-8. Because that test needs the whole file, a page or script over 16 MiB is never read, which caps the memory one read takes. Search finds such a file by name, even when a read would refuse it. When a watched page or script stops passing that test, its stored content is removed and its file row stays.
 - **Scripts are searched by keyword only.** The markdown chunker reads a script's `# comment` lines as headings and turns `snake_case` names into one word, so embedding skips scripts before their text loads.
 
 **Opt-out:** File tools are opt-out: set `FILE_TOOLS_ENABLED=false` to hide `vault_read_file` and `vault_list_files`, and strip file tool references from server metadata and other tool descriptions. The `vault_get_outgoing_links` tool continues to report file links (it indexes from the links table, not the file tools). File config vars (`MAX_FILE_BYTES`, `MAX_IMAGE_OUTPUT_BYTES`, `MAX_PDF_RENDER_PAGES`) are still parsed when disabled.
diff --git a/README.md b/README.md
index 6ce3300f0..2014f41b6 100644
--- a/README.md
+++ b/README.md
@@ -283,7 +283,7 @@ Your notes embed screenshots, reference architecture diagrams, and link out to c
 - **Canvases** — a [Canvas](https://help.obsidian.md/canvas) board arrives as a readable outline: its groups, each card's content in reading order, and the connections between them. Canvas content is full-text searchable, and file references on the board appear in the link graph — backlinks and outgoing links work just like note-to-note links. The exact JSON source is one flag away when full fidelity matters
 - **PDFs** — text is extracted with heading hierarchy, code blocks, and hyperlinks preserved; PDF content is full-text searchable alongside your notes. Set `raw: true` to render pages as images instead, showing layout, diagrams, and tables that text extraction can't preserve — scanned and image-only PDFs work in this mode
 - **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written, apart from a leading byte-order mark, and their first 100 KB is full-text searchable. Any other UTF-8 text file reads back the same way. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
-- **HTML pages and scripts** — a saved page or generated report is searchable by the first 100 KB of the text a browser shows, never its tags or script code; a page over 16 MB is searchable by name only. Python, shell, and PowerShell scripts are searchable by keyword. Both must be UTF-8 text, and both read back as their source
+- **HTML pages and scripts** — a saved page or generated report is searchable by the first 100 KB of the text a browser shows, never its tags or script code. Python, shell, and PowerShell scripts are searchable by keyword. A page or script over 16 MB is searchable by name only. Both must be UTF-8 text, and both read back as their source
 - **Browse** — list any visible folder's files with per-extension counts and file sizes; files a note links to report their size in the link graph too
 
 Set `FILE_TOOLS_ENABLED=false` to hide the file tools — useful when your remote vault syncs without attachments.
diff --git a/src/utils/__tests__/fs.test.ts b/src/utils/__tests__/fs.test.ts
index 09c9a95a5..4078b5f92 100644
--- a/src/utils/__tests__/fs.test.ts
+++ b/src/utils/__tests__/fs.test.ts
@@ -8,6 +8,7 @@ import { tmpdir } from "node:os"
 vi.mock("node:fs/promises", { spy: true })
 import {
   readFileOrNull,
+  readFileTextPrefix,
   readdirOrNull,
   realpathOrNull,
   fileExists,
@@ -73,13 +74,64 @@ describe("readFileOrNull", () => {
   )
 })
 
+describe("readFileTextPrefix", () => {
+  it("returns the whole text of a file shorter than maxBytes", async () => {
+    const dir = await makeTempDir()
+    const path = join(dir, "short.log")
+    await writeFile(path, "short line\n", "utf8")
+
+    expect(await readFileTextPrefix({ path, maxBytes: 100 })).toBe("short line\n")
+  })
+
+  it("returns only the first maxBytes of a longer file", async () => {
+    const dir = await makeTempDir()
+    const path = join(dir, "long.log")
+    await writeFile(path, "0123456789abcdef", "utf8")
+
+    expect(await readFileTextPrefix({ path, maxBytes: 10 })).toBe("0123456789")
+  })
+
+  it("leaves out a character the cut splits instead of ending in a replacement character", async () => {
+    const dir = await makeTempDir()
+    const path = join(dir, "accent.log")
+    // "é" is the two bytes 0xC3 0xA9, so a 3-byte cut keeps only its first byte
+    await writeFile(path, "abé", "utf8")
+
+    expect(await readFileTextPrefix({ path, maxBytes: 3 })).toBe("ab")
+  })
+
+  it("keeps a byte-order mark and replaces an invalid byte, as readFile does", async () => {
+    const dir = await makeTempDir()
+    const path = join(dir, "latin1.log")
+    // 0xEF 0xBB 0xBF is the UTF-8 byte-order mark; 0xE9 alone is never valid UTF-8
+    await writeFile(path, Buffer.from([0xef, 0xbb, 0xbf, 0x61, 0xe9, 0x62]))
+
+    expect(await readFileTextPrefix({ path, maxBytes: 100 })).toBe("a�b")
+  })
+
+  it("rejects when no file exists at the path", async () => {
+    const dir = await makeTempDir()
+    const missingPath = join(dir, "missing.log")
+
+    // Node reports ENOENT as errno -2 on both Linux and macOS
+    const missingFileError = Object.assign(
+      new Error(`ENOENT: no such file or directory, open '${missingPath}'`),
+      { errno: -2, code: "ENOENT", syscall: "open", path: missingPath },
+    )
+
+    await expect(readFileTextPrefix({ path: missingPath, maxBytes: 100 })).rejects.toThrow(
+      missingFileError,
+    )
+  })
+})
+
 describe("readdirOrNull", () => {
   it("returns recursive directory entries when the directory exists", async () => {
     const dir = await makeTempDir()
     await mkdir(join(dir, "sub"))
     await writeFile(join(dir, "sub", "a.md"), "x", "utf8")
     const entries = await readdirOrNull(dir)
-    const names = entries?.map((entry) => entry.name).sort()
+    const names = entries?.map((entry) => entry.name).toSorted()
     expect(names).toEqual(["a.md", "sub"])
   })
 
diff --git a/src/utils/fs.ts b/src/utils/fs.ts
index 2fbb724da..4359facb8 100644
--- a/src/utils/fs.ts
+++ b/src/utils/fs.ts
@@ -1,5 +1,8 @@
 import { lstat, readFile, readdir, realpath, stat } from "node:fs/promises"
+import { createReadStream } from "node:fs"
 import type { Dirent, Stats } from "node:fs"
+import { buffer as streamToBuffer } from "node:stream/consumers"
+import { StringDecoder } from "node:string_decoder"
 import { isErrnoException } from "./is-errno-exception.js"
 
 /** True for the errors that mean nothing is reachable at a path: the entry is
@@ -22,6 +25,23 @@ export const readFileOrNull = async (path: string): Promise<string | null> => {
   }
 }
 
+/** Reads at most maxBytes from the start of a file and decodes them as UTF-8
+ *  the way readFile does: an invalid byte becomes a replacement character and
+ *  a byte-order mark stays. The rest of the file is never loaded. */
+export const readFileTextPrefix = async (params: {
+  path: string
+  maxBytes: number
+}): Promise<string> => {
+  // end is inclusive, so the stream stops after maxBytes bytes
+  const prefix = await streamToBuffer(
+    createReadStream(params.path, { start: 0, end: params.maxBytes - 1 }),
+  )
+
+  // The cut can split a character. write() holds back that character's bytes,
+  // so the text never ends in a replacement character.
+  return new StringDecoder("utf8").write(prefix)
+}
+
 /** Stats a path, returning null instead of throwing when nothing exists there
  *  (ENOENT) or a parent is a file (ENOTDIR). Any other error propagates. */
 export const statOrNull = async (path: string): Promise<Stats | null> => {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
index 8fffa957f..e0bff3faf 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
@@ -1313,7 +1313,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
index 706c8ee70..5b95e4e05 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
@@ -1254,7 +1254,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
index 7ea9a5a88..110156cb5 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
index 874e1d13b..4c98d17cd 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
@@ -1173,7 +1173,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
index a00e16919..19ddb1662 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
@@ -1172,7 +1172,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
index ead881d0c..de0c266c3 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
index a3c2da14e..85ae5b3d4 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
@@ -795,7 +795,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
index 3cfcc8293..e16a61b43 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
@@ -700,7 +700,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
index c10449276..4f2898ecd 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
@@ -699,7 +699,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
index d41405ca9..b3674f123 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
@@ -794,7 +794,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index 670b025a2..ee391046a 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1465,7 +1465,7 @@ describe("vault_search description reflects EMBEDDING_ENABLED", () => {
     const description = findSearchDescription(registerWithConfig({}))
     const openingSentence = description.slice(0, description.indexOf(". ") + 1)
     expect(openingSentence).toBe(
-      "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
+      "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
     )
     expect(description).toContain("career aspirations")
     expect(description).toContain("search_mode")
@@ -1493,7 +1493,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   // only the hybrid variant says scripts match by keyword alone.
   const FILE_RESULT_WORDING = {
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched; scripts match by keyword only)",
+      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only)",
     filtersLeadIn:
       "Filters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:",
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`,
@@ -1509,7 +1509,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   const KEYWORD_ONLY_FILE_RESULT_WORDING = {
     ...FILE_RESULT_WORDING,
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages up to 16 MiB, and .py/.sh/.ps1 scripts; each file's first 100 KiB of text is searched)",
+      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched)",
   }
 
   it.each([
diff --git a/src/vault-mcp/mcp-core/tools/search-tools.ts b/src/vault-mcp/mcp-core/tools/search-tools.ts
index e2b1ac90b..4490f2b06 100644
--- a/src/vault-mcp/mcp-core/tools/search-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/search-tools.ts
@@ -6,7 +6,10 @@ import type { ToolRegistrationContext } from "./tool-helpers.js"
 import { readEffectiveOrphanExcludeFolders } from "../../vault-operations/vault-folder-config.js"
 import { readDailyNotesConfig } from "../../vault-operations/daily-notes.js"
 import { getExtensionsOfKind } from "../../obsidian-markdown/file-kinds.js"
-import { MAX_INDEXED_CONTENT_BYTES } from "../../search/search-index.js"
+import {
+  MAX_INDEXED_CONTENT_BYTES,
+  MAX_INDEXED_HTML_OR_SCRIPT_BYTES,
+} from "../../search/search-index.js"
 import { SEARCH_LEG_ROW_CAP } from "../../search/hybrid-search.js"
 import {
   createStrictInputObject,
@@ -91,7 +94,7 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   const scriptExtensions = getExtensionsOfKind("script").join("/")
   const textExtensions = getExtensionsOfKind("text").join("/")
   const searchedContentText = config.fileToolsEnabled
-    ? `vault notes and file content (canvas, PDF, the text formats ${textExtensions}, the visible text of HTML pages up to 16 MiB, and ${scriptExtensions} scripts; each file's first ${MAX_INDEXED_CONTENT_BYTES / 1024} KiB of text is searched${scriptMatchClause})`
+    ? `vault notes and file content (canvas, PDF, the text formats ${textExtensions}, the visible text of HTML pages, and ${scriptExtensions} scripts; a page or script over ${MAX_INDEXED_HTML_OR_SCRIPT_BYTES / (1024 * 1024)} MiB is found by its name only; each file's first ${MAX_INDEXED_CONTENT_BYTES / 1024} KiB of text is searched${scriptMatchClause})`
     : "vault notes"
   const searchResultFieldsText = config.fileToolsEnabled
     ? `path, title, snippet, score, ${tagsFieldsText}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`
diff --git a/src/vault-mcp/search/__tests__/file-watcher.test.ts b/src/vault-mcp/search/__tests__/file-watcher.test.ts
index 361df1262..dedcfacc4 100644
--- a/src/vault-mcp/search/__tests__/file-watcher.test.ts
+++ b/src/vault-mcp/search/__tests__/file-watcher.test.ts
@@ -20,7 +20,7 @@ import { DateTime } from "luxon"
 import * as sqliteVec from "sqlite-vec"
 import { createSearchIndex } from "../search-index.js"
 import { extractPdfText } from "../../obsidian-markdown/pdf.js"
-import { readdirOrNull, statOrNull } from "../../../utils/fs.js"
+import { readdirOrNull, readFileTextPrefix, statOrNull } from "../../../utils/fs.js"
 import type { SearchIndex } from "../search-index.js"
 import { watchVaultAndBuildIndex } from "../file-watcher.js"
 import { atomicWriteFile } from "../../vault-operations/vault-filesystem.js"
@@ -967,10 +967,11 @@ describe("file watcher — obsolete events and embedding queues", () => {
       const { testVault, search, database, fire } = await createControlledWatcher()
       const filePath = join(testVault, "content.txt")
       await writeFile(filePath, "currentopal")
-      const actualFs = await vi.importActual<typeof import("node:fs/promises")>("node:fs/promises")
-      const readSpy = vi.mocked(readFile).mockImplementation(async (requestedPath, options) => {
-        if (requestedPath === filePath) throw new Error("controlled content read failure")
-        return actualFs.readFile(requestedPath, options)
+      const actualFsUtils =
+        await vi.importActual<typeof import("../../../utils/fs.js")>("../../../utils/fs.js")
+      const readSpy = vi.mocked(readFileTextPrefix).mockImplementation(async (params) => {
+        if (params.path === filePath) throw new Error("controlled content read failure")
+        return actualFsUtils.readFileTextPrefix(params)
       })
       const contentSpy = vi.spyOn(search, "upsertFileContent")
       const warnSpy = vi.spyOn(logger, "warn")
@@ -980,7 +981,7 @@ describe("file watcher — obsolete events and embedding queues", () => {
       })
 
       await expect(fire(event, "content.txt")).resolves.toBeUndefined()
-      expect(readSpy).toHaveBeenCalledWith(filePath, "utf8")
+      expect(readSpy).toHaveBeenCalledWith({ path: filePath, maxBytes: 102_400 })
       expect(warnSpy).toHaveBeenCalledExactlyOnceWith("file content indexing failed", {
         path: "content.txt",
         error: "[Error]: controlled content read failure",
@@ -1194,22 +1195,36 @@ describe("file watcher — obsolete events and embedding queues", () => {
     })
   })
 
+  /** Holds the first read of filePath open until release() runs. A note is
+   *  read whole and a text file through the prefix reader, so both are held. */
   const delayFirstRead = async (filePath: string) => {
     const actualFs = await vi.importActual<typeof import("node:fs/promises")>("node:fs/promises")
+    const actualFsUtils =
+      await vi.importActual<typeof import("../../../utils/fs.js")>("../../../utils/fs.js")
     const entered = Promise.withResolvers<undefined>()
     const release = Promise.withResolvers<undefined>()
     const delayedPaths = new Set<string>()
+    const holdFirstRead = async (requestedPath: unknown): Promise<void> => {
+      if (requestedPath !== filePath || delayedPaths.has(filePath)) return
+
+      delayedPaths.add(filePath)
+      entered.resolve(undefined)
+      await release.promise
+    }
     vi.mocked(readFile).mockImplementation(async (requestedPath, options) => {
       const content = await actualFs.readFile(requestedPath, options)
-
-      if (requestedPath === filePath && !delayedPaths.has(filePath)) {
-        delayedPaths.add(filePath)
-        entered.resolve(undefined)
-        await release.promise
-      }
+      await holdFirstRead(requestedPath)
       return content
     })
-    onTestFinished(() => vi.mocked(readFile).mockRestore())
+    vi.mocked(readFileTextPrefix).mockImplementation(async (params) => {
+      const content = await actualFsUtils.readFileTextPrefix(params)
+      await holdFirstRead(params.path)
+      return content
+    })
+    onTestFinished(() => {
+      vi.mocked(readFile).mockRestore()
+      vi.mocked(readFileTextPrefix).mockRestore()
+    })
     return { entered: entered.promise, release: () => release.resolve(undefined) }
   }
 
@@ -1608,6 +1623,48 @@ describe("file watcher — obsolete events and embedding queues", () => {
     expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(pagePath, expect.anything())
   })
 
+  it("finds a script over 16 MiB by its name without reading it", async () => {
+    const { testVault, search, fire } = await createControlledWatcher()
+    const filler = "# filler\n".repeat(Math.ceil((16 * 1024 * 1024) / 9) + 1)
+    const scriptPath = join(testVault, "giganticscript.py")
+    await writeFile(scriptPath, `buriedjasper = 1\n${filler}`, "utf8")
+    const searchPaths = async (query: string) => {
+      const { results } = await search.hybridSearch({ query }, logger)
+      return results.map((result) => result.path)
+    }
+
+    await fire("add", "giganticscript.py")
+
+    expect(await searchPaths("giganticscript")).toEqual(["giganticscript.py"])
+    expect(await searchPaths("buriedjasper")).toEqual([])
+    // readFile takes at most two arguments, so these two cover every read of the script
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(scriptPath)
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(scriptPath, expect.anything())
+  })
+
+  it("reads only the first 100 KiB of a changed text file, all the text search keeps", async () => {
+    const { testVault, search, fire } = await createControlledWatcher()
+    const logPath = join(testVault, "prefixread.log")
+    // The opening word sits inside the first 100 KiB and the closing word past it
+    await writeFile(logPath, `openingtopaz\n${"x ".repeat(60_000)}\nclosingtopaz\n`, "utf8")
+    const searchPaths = async (query: string) => {
+      const { results } = await search.hybridSearch({ query }, logger)
+      return results.map((result) => result.path)
+    }
+
+    await fire("add", "prefixread.log")
+
+    expect(await searchPaths("openingtopaz")).toEqual(["prefixread.log"])
+    expect(await searchPaths("closingtopaz")).toEqual([])
+    expect(vi.mocked(readFileTextPrefix)).toHaveBeenCalledWith({
+      path: logPath,
+      maxBytes: 102_400,
+    })
+    // readFile takes at most two arguments, so these two cover every whole-file read
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(logPath)
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(logPath, expect.anything())
+  })
+
   it("leaves a page that is not UTF-8 out of search", async () => {
     const { testVault, database, fire } = await createControlledWatcher()
     // 0xE9 is "é" in Latin-1 and never a complete UTF-8 sequence
diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index f03d707a9..4945f990e 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -11,7 +11,7 @@ import { createSearchIndex, CONTENT_INDEXED_FILE_KINDS } from "../search-index.j
 import type { NoteMetadata, OutgoingLinkEntry, SearchIndex, TaskEntry } from "../search-index.js"
 import type { StatusClassification } from "../../obsidian-markdown/tasks.js"
 import { logger } from "../../../logger.js"
-import { statOrNull } from "../../../utils/fs.js"
+import { readFileTextPrefix, statOrNull } from "../../../utils/fs.js"
 import { decodeTextBuffer } from "../../../utils/decode-text-buffer.js"
 import { extractPdfText } from "../../obsidian-markdown/pdf.js"
 import { buildPdf } from "../../obsidian-markdown/__tests__/pdf-fixture.js"
@@ -3860,10 +3860,19 @@ describe("rebuildFromVault bounded I/O", () => {
         })
         restoreOperations.push(() => statSpy.mockRestore())
       }
-      if (operation !== "size") {
+      // Text files go through the prefix reader; notes and canvases are read whole
+      if (operation === "text") {
+        const prefixReadSpy = vi.mocked(readFileTextPrefix).mockImplementation(async (params) => {
+          if (targetPaths.has(params.path)) await holdTargetOperation(params.path)
+          return actualFsUtils.readFileTextPrefix(params)
+        })
+        restoreOperations.push(() => prefixReadSpy.mockRestore())
+      }
+      if (operation === "note" || operation === "canvas") {
         const readSpy = vi.mocked(readFile).mockImplementation(async (requestedPath, options) => {
-          if (typeof requestedPath === "string" && targetPaths.has(requestedPath))
+          if (typeof requestedPath === "string" && targetPaths.has(requestedPath)) {
             await holdTargetOperation(requestedPath)
+          }
           return actualFs.readFile(requestedPath, options)
         })
         restoreOperations.push(() => readSpy.mockRestore())
@@ -4060,10 +4069,44 @@ describe("rebuildFromVault filesystem failures", () => {
     expect(warnSpy).toHaveBeenCalledTimes(1)
   })
 
+  it("warns and skips an unreadable text file while indexing healthy files", async () => {
+    const { vaultPath, search } = await createRebuildVault()
+    const filePath = join(vaultPath, "broken.txt")
+    await writeFile(filePath, "brokenquartz")
+    const actualFsUtils =
+      await vi.importActual<typeof import("../../../utils/fs.js")>("../../../utils/fs.js")
+    const prefixReadSpy = vi.mocked(readFileTextPrefix).mockImplementation(async (params) => {
+      if (params.path === filePath) throw new Error("controlled read failure")
+      return actualFsUtils.readFileTextPrefix(params)
+    })
+    const warnSpy = vi.spyOn(logger, "warn")
+    onTestFinished(() => {
+      prefixReadSpy.mockRestore()
+      warnSpy.mockRestore()
+    })
+    const rebuilt = await search.rebuildFromVault(
+      { vaultPath, bodyTagParser: inProcessBodyTagParser },
+      logger,
+    )
+    await rebuilt.embedding
+
+    expect(rebuilt.count).toBe(1)
+    expect(prefixReadSpy).toHaveBeenCalledWith({ path: filePath, maxBytes: 102_400 })
+    expect(warnSpy).toHaveBeenCalledExactlyOnceWith("skipped unreadable text file during rebuild", {
+      path: "broken.txt",
+      error: "[Error]: controlled read failure",
+    })
+    expect(
+      (await search.hybridSearch({ query: "healthyamber" }, logger)).results.map(
+        (entry) => entry.path,
+      ),
+    ).toEqual(["healthy.md"])
+    expect((await search.hybridSearch({ query: "brokenquartz" }, logger)).results).toEqual([])
+  })
+
   it.each([
     { fileName: "broken.md", sourceKind: "note" },
     { fileName: "broken.canvas", sourceKind: "canvas file" },
-    { fileName: "broken.txt", sourceKind: "text file" },
     { fileName: "broken.pdf", sourceKind: "PDF" },
   ])(
     "warns and skips an unreadable $sourceKind while indexing healthy files",
@@ -8406,13 +8449,26 @@ describe("scripts", () => {
     })
   })
 
-  it("finds a script over 16 MiB by its text, since the page size limit is for HTML only", async () => {
+  it("finds a script over 16 MiB by its name without reading it", async () => {
     const filler = "# filler\n".repeat(Math.ceil((16 * 1024 * 1024) / 9) + 1)
-    const { database } = await rebuildVaultOf({
+    const { fileIndex } = await rebuildVaultOf({
       files: [{ path: "giganticscript.py", content: `buriedjasper = 1\n${filler}` }],
     })
+    const searchPaths = async (query: string) => {
+      const { results } = await fileIndex.hybridSearch({ query }, logger)
+      return results.map((result) => result.path)
+    }
 
-    expect(keywordPaths(database, "buriedjasper")).toEqual(["giganticscript.py"])
+    expect(await searchPaths("giganticscript")).toEqual(["giganticscript.py"])
+    expect(await searchPaths("buriedjasper")).toEqual([])
+    // readFile takes at most two arguments, so these two cover every read of the script
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
+      expect.stringMatching(/giganticscript\.py$/),
+    )
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
+      expect.stringMatching(/giganticscript\.py$/),
+      expect.anything(),
+    )
   })
 
   it("leaves a script holding a NUL byte out of search", async () => {
@@ -8432,6 +8488,42 @@ describe("scripts", () => {
   })
 })
 
+describe("text formats in a rebuild", () => {
+  it("reads only the first 100 KiB of a text file, all the text search keeps", async () => {
+    const vaultDir = await mkdtemp(join(tmpdir(), "text-formats-"))
+    onTestFinished(() => rm(vaultDir, { recursive: true }))
+    // The opening word sits inside the first 100 KiB and the closing word past it
+    await writeFile(
+      join(vaultDir, "prefixread.log"),
+      `openingtopaz\n${"x ".repeat(60_000)}\nclosingtopaz\n`,
+    )
+    const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
+      fileToolsEnabled: true,
+    })
+    await fileIndex.rebuildFromVault(
+      { vaultPath: vaultDir, bodyTagParser: inProcessBodyTagParser },
+      logger,
+    )
+    const searchPaths = async (query: string) => {
+      const { results } = await fileIndex.hybridSearch({ query }, logger)
+      return results.map((result) => result.path)
+    }
+
+    expect(await searchPaths("openingtopaz")).toEqual(["prefixread.log"])
+    expect(await searchPaths("closingtopaz")).toEqual([])
+    expect(vi.mocked(readFileTextPrefix)).toHaveBeenCalledWith({
+      path: expect.stringMatching(/prefixread\.log$/),
+      maxBytes: 102_400,
+    })
+    // readFile takes at most two arguments, so these two cover every whole-file read
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(expect.stringMatching(/prefixread\.log$/))
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
+      expect.stringMatching(/prefixread\.log$/),
+      expect.anything(),
+    )
+  })
+})
+
 describe("committed embedding source versions", () => {
   it.each(["note", "file"] as const)(
     "rejects a %s model result after source deletion",
diff --git a/src/vault-mcp/search/file-watcher.ts b/src/vault-mcp/search/file-watcher.ts
index 90afc54d5..058391d66 100644
--- a/src/vault-mcp/search/file-watcher.ts
+++ b/src/vault-mcp/search/file-watcher.ts
@@ -11,7 +11,8 @@ import { join, relative, resolve as resolvePath, sep } from "node:path"
 import {
   CONTENT_INDEXED_FILE_KINDS,
   INDEXING_FILE_READ_CONCURRENCY,
-  isHtmlPageIndexedByNameOnly,
+  isIndexedByNameOnly,
+  MAX_INDEXED_CONTENT_BYTES,
   PDF_EXTRACTION_CONCURRENCY,
 } from "./search-index.js"
 import type { RebuildResult, SearchIndex } from "./search-index.js"
@@ -27,7 +28,13 @@ import type { Logger } from "../../logger.js"
 import { decodeTextBuffer } from "../../utils/decode-text-buffer.js"
 import { describeError, describeErrorForLog } from "../../utils/describe-error.js"
 import { isErrnoException } from "../../utils/is-errno-exception.js"
-import { isMissingPathError, readdirOrNull, realpathOrNull, statOrNull } from "../../utils/fs.js"
+import {
+  isMissingPathError,
+  readdirOrNull,
+  readFileTextPrefix,
+  realpathOrNull,
+  statOrNull,
+} from "../../utils/fs.js"
 import { hasHiddenPathSegment } from "../../utils/has-hidden-path-segment.js"
 import { mapWithConcurrency } from "../../utils/map-with-concurrency.js"
 
@@ -238,8 +245,8 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
     if (isCanvas || isIndexableNonCanvas) {
       try {
         /** The text to index for the file:
-         *  - empty for an HTML page too large to extract, which is never read, so
-         *    its file_content row still lets search find it by name;
+         *  - empty for an HTML page or script over the size limit, which is never
+         *    read, so its file_content row still lets search find it by name;
          *  - null for an HTML page or script that is not UTF-8 or holds a NUL byte
          *    early on, which vault_read_file refuses too;
          *  - the file's text otherwise. */
@@ -255,7 +262,7 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
             }
             case "html":
             case "script": {
-              const indexedByNameOnly = isHtmlPageIndexedByNameOnly({
+              const indexedByNameOnly = isIndexedByNameOnly({
                 filePath: relativePath,
                 fileBytes: fileStat.size,
               })
@@ -266,11 +273,18 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
               if (decodedSource.status !== "text") return null
               return decodedSource.text
             }
-            // Canvases and text formats decode leniently, so a stray invalid byte
-            // or NUL padding keeps them in search. Images and other files never
-            // reach this switch: the guard above reads only the kinds search indexes.
-            case "canvas":
+            // Text formats and canvases decode leniently, so a stray invalid byte
+            // or NUL padding keeps them in search. Search keeps a text file's
+            // first MAX_INDEXED_CONTENT_BYTES only, so no more is read.
             case "text":
+              return await readFileTextPrefix({
+                path: filePath,
+                maxBytes: MAX_INDEXED_CONTENT_BYTES,
+              })
+            // A canvas is read whole, because its links need the whole JSON.
+            // Images and other files never reach this switch: the guard above
+            // reads only the kinds search indexes.
+            case "canvas":
             case "image":
             case "other":
               return await readFile(filePath, "utf8")
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index c159170f0..ac75aa75c 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -31,7 +31,7 @@ import { extractPdfText } from "../obsidian-markdown/pdf.js"
 import { caseFoldPath } from "../../utils/case-fold-path.js"
 import { describeError, describeErrorForLog } from "../../utils/describe-error.js"
 import { filterValidSymlinks } from "../../utils/filter-valid-symlinks.js"
-import { statOrNull } from "../../utils/fs.js"
+import { readFileTextPrefix, statOrNull } from "../../utils/fs.js"
 import { hasHiddenPathSegment } from "../../utils/has-hidden-path-segment.js"
 import { mapWithConcurrency } from "../../utils/map-with-concurrency.js"
 import {
@@ -85,18 +85,21 @@ const EMBEDDED_FILE_KINDS: ReadonlySet<FileKind> = new Set(["canvas", "pdf", "te
  *  pathological FTS rows from large CSVs or verbose JSONs. */
 export const MAX_INDEXED_CONTENT_BYTES = 102_400
 
-/** An HTML page larger than this is indexed by its name only, like a scanned
- *  PDF. Extracting its text runs on the main thread, which answers no request
- *  meanwhile, and attribute-heavy pages at 16 MiB already took up to 1.7 s. */
-const MAX_INDEXED_HTML_PAGE_BYTES = 16 * 1024 * 1024
-
-/** True for an HTML page too large to extract. Search finds such a page by its
- *  name only, so indexing never reads it. */
-export const isHtmlPageIndexedByNameOnly = (params: {
-  filePath: string
-  fileBytes: number
-}): boolean => {
-  return getFileKind(params.filePath) === "html" && params.fileBytes > MAX_INDEXED_HTML_PAGE_BYTES
+/** An HTML page or script larger than this is indexed by its name only, like a
+ *  scanned PDF. Each kind has its own reason for the same limit:
+ *  - a page's text is extracted on the main thread, which answers no request
+ *    meanwhile, and attribute-heavy pages at 16 MiB already took up to 1.7 s;
+ *  - a script is read whole, because indexing keeps its text only when every
+ *    byte is UTF-8, so the limit bounds the memory one read takes. */
+export const MAX_INDEXED_HTML_OR_SCRIPT_BYTES = 16 * 1024 * 1024
+
+/** True for an HTML page or script over the size limit. Search finds such a
+ *  file by its name only, so indexing never reads it. */
+export const isIndexedByNameOnly = (params: { filePath: string; fileBytes: number }): boolean => {
+  const fileKind = getFileKind(params.filePath)
+  const isHtmlOrScript = fileKind === "html" || fileKind === "script"
+
+  return isHtmlOrScript && params.fileBytes > MAX_INDEXED_HTML_OR_SCRIPT_BYTES
 }
 
 /** The text file_content_fts holds for a file, built from the text its reader
@@ -113,7 +116,7 @@ const fileTextToIndexedText = (params: {
     case "canvas":
       return linearizeCanvas(params.fileText)
     case "html":
-      if (isHtmlPageIndexedByNameOnly(params)) return ""
+      if (isIndexedByNameOnly(params)) return ""
       return extractHtmlVisibleText({
         html: params.fileText,
         maxBytes: MAX_INDEXED_CONTENT_BYTES,
@@ -2419,11 +2422,23 @@ export const createSearchIndex = (
     }): Promise<RebuildFileContent | null> => {
       const { file, sourceKind } = params
 
+      // Search keeps a text file's first MAX_INDEXED_CONTENT_BYTES only, so no
+      // more is read. A canvas's links and a note's body need the whole file.
+      const readContent = (): Promise<string> => {
+        switch (sourceKind) {
+          case "text file":
+            return readFileTextPrefix({
+              path: file.absolutePath,
+              maxBytes: MAX_INDEXED_CONTENT_BYTES,
+            })
+          case "canvas file":
+          case "note":
+            return readFile(file.absolutePath, "utf8")
+        }
+      }
+
       try {
-        const [content, fileStat] = await Promise.all([
-          readFile(file.absolutePath, "utf8"),
-          stat(file.absolutePath),
-        ])
+        const [content, fileStat] = await Promise.all([readContent(), stat(file.absolutePath)])
         return {
           relativePath: file.relativePath,
           content,
@@ -2489,8 +2504,8 @@ export const createSearchIndex = (
     const textFileContents = textFileContentResults.filter((entry) => entry !== null)
 
     /** Reads an HTML page or script for indexing:
-     *  - a page too large to extract is never read and keeps empty text, so its
-     *    file_content row still lets search find it by name;
+     *  - a page or script over the size limit is never read and keeps empty
+     *    text, so its file_content row still lets search find it by name;
      *  - any other file keeps its text only when its bytes are UTF-8 with no NUL
      *    byte early on, the test vault_read_file applies, so search never holds
      *    text that a read refuses. */
@@ -2502,7 +2517,7 @@ export const createSearchIndex = (
       const readDecodedFile = async () => {
         try {
           const fileStat = await stat(file.absolutePath)
-          const indexedByNameOnly = isHtmlPageIndexedByNameOnly({
+          const indexedByNameOnly = isIndexedByNameOnly({
             filePath: file.relativePath,
             fileBytes: fileStat.size,
           })

From de2971035cf77d8842a7901aa09d2025b96e483f Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 13:23:23 -0500
Subject: [PATCH 32/38] test(search): sort without mutating and brace a
 multi-line if

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/vault-mcp/search/__tests__/file-watcher.test.ts | 2 +-
 src/vault-mcp/search/__tests__/search-index.test.ts | 5 +++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/vault-mcp/search/__tests__/file-watcher.test.ts b/src/vault-mcp/search/__tests__/file-watcher.test.ts
index dedcfacc4..6b9ac7d5a 100644
--- a/src/vault-mcp/search/__tests__/file-watcher.test.ts
+++ b/src/vault-mcp/search/__tests__/file-watcher.test.ts
@@ -3718,7 +3718,7 @@ describe("file watcher — new-directory rescan", () => {
         logger,
       )
       // readdir order isn't guaranteed, so compare sorted ("loop" < "settled.md").
-      expect([...addedPaths].sort()).toEqual([loopLink, settledPath])
+      expect([...addedPaths].toSorted()).toEqual([loopLink, settledPath])
     },
   )
 
diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index 4945f990e..a8126086e 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -4011,8 +4011,9 @@ describe("rebuildFromVault filesystem failures", () => {
     const actualFs =
       await vi.importActual<typeof import("../../../utils/fs.js")>("../../../utils/fs.js")
     const statSpy = vi.mocked(statOrNull).mockImplementation(async (requestedPath) => {
-      if (requestedPath === filePath)
+      if (requestedPath === filePath) {
         throw Object.assign(new Error("controlled stat failure"), { code })
+      }
       return actualFs.statOrNull(requestedPath)
     })
     const warnSpy = vi.spyOn(logger, "warn")
@@ -4855,7 +4856,7 @@ describe("rebuildFromVault", () => {
 
     const results = index.fullTextSearch({ query: "symlink target content" }, logger)
     expect(results).toHaveLength(2)
-    const paths = results.map((result) => result.path).sort()
+    const paths = results.map((result) => result.path).toSorted()
     expect(paths).toEqual(["linked.md", "real/original.md"])
   })
 

From d7e880cfa2922c6e86201a1a34636afca24637fd Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 13:25:53 -0500
Subject: [PATCH 33/38] fix(tools): define search_mode once and drop a repeated
 vault_list_files example gloss

vault_search glossed search_mode "fts" as "only keyword matching ran" in three places;
the Behavior lines now name the mode by its value, and Returns keeps the definition.
vault_list_files' first example repeated the folder parameter's own description.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../__tests__/__snapshots__/tool-surface/default.json         | 4 ++--
 .../__tests__/__snapshots__/tool-surface/disabled-tools.json  | 4 ++--
 .../__tests__/__snapshots__/tool-surface/embedding-off.json   | 2 +-
 .../__tests__/__snapshots__/tool-surface/file-tools-off.json  | 2 +-
 .../__snapshots__/tool-surface/memory-off+embedding-off.json  | 2 +-
 .../__snapshots__/tool-surface/memory-off+file-tools-off.json | 2 +-
 .../__tests__/__snapshots__/tool-surface/memory-off.json      | 4 ++--
 .../__tests__/__snapshots__/tool-surface/obsidian-sync.json   | 4 ++--
 .../__snapshots__/tool-surface/readonly+embedding-off.json    | 2 +-
 .../__snapshots__/tool-surface/readonly+file-tools-off.json   | 2 +-
 .../tool-surface/readonly+memory-off+embedding-off.json       | 2 +-
 .../tool-surface/readonly+memory-off+file-tools-off.json      | 2 +-
 .../__snapshots__/tool-surface/readonly+memory-off.json       | 4 ++--
 .../__tests__/__snapshots__/tool-surface/readonly.json        | 4 ++--
 src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts     | 4 ++--
 src/vault-mcp/mcp-core/tools/asset-tools.ts                   | 2 +-
 src/vault-mcp/mcp-core/tools/search-tools.ts                  | 4 ++--
 17 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
index e0bff3faf..71c752039 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
@@ -486,7 +486,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({})\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1313,7 +1313,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
index 5b95e4e05..2e4948eba 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
@@ -488,7 +488,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({})\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1254,7 +1254,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
index 110156cb5..42d66869f 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
@@ -488,7 +488,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({})\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/file-tools-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/file-tools-off.json
index 60c1b75ba..bd50f2085 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/file-tools-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/file-tools-off.json
@@ -1228,7 +1228,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes, ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes come back; with \"hybrid\", at most 200 notes.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (top-level folder), type, kind, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is always \"note\". created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes, ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes come back; with \"hybrid\", at most 200 notes.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (top-level folder), type, kind, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is always \"note\". created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
index 4c98d17cd..31b30f843 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
@@ -406,7 +406,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({})\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+file-tools-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+file-tools-off.json
index 01e0815ff..f403b4d4c 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+file-tools-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+file-tools-off.json
@@ -1086,7 +1086,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes, ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes come back; with \"hybrid\", at most 200 notes.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (top-level folder), type, kind, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is always \"note\". created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes, ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes come back; with \"hybrid\", at most 200 notes.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (top-level folder), type, kind, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is always \"note\". created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
index 19ddb1662..f90a6d7b2 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
@@ -405,7 +405,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({})\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1172,7 +1172,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
index de0c266c3..5bf577840 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
@@ -488,7 +488,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({})\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
index 85ae5b3d4..ff40a19f8 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
@@ -165,7 +165,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({})\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+file-tools-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+file-tools-off.json
index 14db80ecc..57f26ff0b 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+file-tools-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+file-tools-off.json
@@ -708,7 +708,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes, ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes come back; with \"hybrid\", at most 200 notes.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (top-level folder), type, kind, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is always \"note\". created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes, ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes come back; with \"hybrid\", at most 200 notes.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (top-level folder), type, kind, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is always \"note\". created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
index e16a61b43..1f510be4e 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
@@ -130,7 +130,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({})\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+file-tools-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+file-tools-off.json
index dae8b78b7..a385a4e80 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+file-tools-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+file-tools-off.json
@@ -613,7 +613,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes, ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes come back; with \"hybrid\", at most 200 notes.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (top-level folder), type, kind, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is always \"note\". created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes, ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes come back; with \"hybrid\", at most 200 notes.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (top-level folder), type, kind, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is always \"note\". created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
index 4f2898ecd..8791f5810 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
@@ -129,7 +129,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({})\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -699,7 +699,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
index b3674f123..73cdd19b0 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
@@ -164,7 +164,7 @@
     {
       "name": "vault_list_files",
       "title": "List Files",
-      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({}) — non-markdown files across the whole vault\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
+      "description": "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.\n\nExample: vault_list_files({})\nExample: vault_list_files({ folder: \"attachments\" })\nExample: vault_list_files({ extensions: [\".png\", \".jpg\"], limit: 20 })\n\nWhen to use: discovering what files exist before reading them with vault_read_file. vault_list_notes and vault_search_by_folder cover only markdown notes, and beyond notes vault_search indexes only canvas, PDF, HTML (.html/.htm), script (.py/.sh/.ps1), and .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base files, so this is the discovery surface for everything else. For the files one specific note links to, prefer vault_get_outgoing_links.\n\nBehavior: A visible folder containing no files — or one that doesn't exist, or a path that names a file — returns an empty listing, not an error. Use the folder's exact letter case; a different case can find nothing. Hidden (dot-prefixed) files and folders, .obsidian/ among them, never appear.\n\nErrors:\n- \"absolute path blocked\" / \"path traversal blocked\" / \"hidden path blocked\" — the folder is absolute, escapes the vault, names the vault root itself (e.g. \".\"), or is hidden like \".obsidian\"; use a vault-relative folder outside hidden folders, and omit folder to list the whole vault.\n- \"ENAMETOOLONG: …\" or another filesystem error — the message names the folder it could not read, and what to do; until then, pass a folder outside it.\n\nReturns: JSON with files (array of { path, extension, bytes }, sorted by path; extension is \"(none)\" for a file without one), extension_counts (counts keyed by extension, e.g. { \".png\": 3 }, over the full filtered set), total (full filtered count), and truncated (true when total exceeds limit).\n\nReadable types: vault_read_file reads images (.png/.jpg/.jpeg/.gif/.webp), .canvas, .pdf, and any UTF-8 text file.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -794,7 +794,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. When only keyword matching ran (search_mode \"fts\"), at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode \"fts\").\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index ee391046a..1ba77e814 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1563,12 +1563,12 @@ describe("vault_search result cap", () => {
     {
       label: "bounds both modes for notes and files by default",
       env: {},
-      expectedLine: `${BEHAVIOR_LEAD} When only keyword matching ran (search_mode "fts"), at most 100 notes and 100 files come back; with "hybrid", at most 200 notes and 200 files.`,
+      expectedLine: `${BEHAVIOR_LEAD} With search_mode "fts", at most 100 notes and 100 files come back; with "hybrid", at most 200 notes and 200 files.`,
     },
     {
       label: "bounds both modes for notes only when file tools are off",
       env: { FILE_TOOLS_ENABLED: "false" },
-      expectedLine: `${BEHAVIOR_LEAD} When only keyword matching ran (search_mode "fts"), at most 100 notes come back; with "hybrid", at most 200 notes.`,
+      expectedLine: `${BEHAVIOR_LEAD} With search_mode "fts", at most 100 notes come back; with "hybrid", at most 200 notes.`,
     },
     {
       label: "states only the keyword bound for notes and files when embeddings are off",
diff --git a/src/vault-mcp/mcp-core/tools/asset-tools.ts b/src/vault-mcp/mcp-core/tools/asset-tools.ts
index 4350c8205..ed5540cab 100644
--- a/src/vault-mcp/mcp-core/tools/asset-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/asset-tools.ts
@@ -245,7 +245,7 @@ Returns: by file type:
       title: "List Files",
       description: `List non-markdown files in the vault or a folder — images, canvases, PDFs, data files — with per-file byte sizes and per-extension counts.
 
-Example: vault_list_files({}) — non-markdown files across the whole vault
+Example: vault_list_files({})
 Example: vault_list_files({ folder: "attachments" })
 Example: vault_list_files({ extensions: [".png", ".jpg"], limit: 20 })
 
diff --git a/src/vault-mcp/mcp-core/tools/search-tools.ts b/src/vault-mcp/mcp-core/tools/search-tools.ts
index 4490f2b06..90f4ad751 100644
--- a/src/vault-mcp/mcp-core/tools/search-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/search-tools.ts
@@ -111,7 +111,7 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
     ? {
         stage: "keyword matching",
         outcome:
-          'a query left with no terms is matched by meaning only, or finds nothing when only keyword matching ran (search_mode "fts")',
+          'a query left with no terms is matched by meaning only, or finds nothing when search_mode is "fts"',
       }
     : {
         stage: "matching",
@@ -126,7 +126,7 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   const keywordCapExtent = describeCapExtent(SEARCH_LEG_ROW_CAP)
   const hybridCapExtent = describeCapExtent(SEARCH_LEG_ROW_CAP * 2)
   const resultCapSentence = config.embeddingEnabled
-    ? `When only keyword matching ran (search_mode "fts"), at most ${keywordCapExtent} come back; with "hybrid", at most ${hybridCapExtent}.`
+    ? `With search_mode "fts", at most ${keywordCapExtent} come back; with "hybrid", at most ${hybridCapExtent}.`
     : `At most ${keywordCapExtent} come back.`
   const searchBehaviorLine = `Behavior: ${INDEX_LAG_LEAD}. No matches returns an empty results array with total 0, not an error. ${resultCapSentence}
 - Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before ${emptiedQueryText.stage}; ${emptiedQueryText.outcome}.`

From b8bcb7ea90666ea8f40042c9182f834857ae9127 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 13:45:26 -0500
Subject: [PATCH 34/38] fix(search): match readFile at the end of a file and
 tighten read-size wording

Review fixes for the read-size change:

- readFileTextPrefix turns an unfinished character at the end of a file
  into a replacement character, as readFile does, and returns "" for a
  maxBytes below one byte instead of throwing.
- isIndexedByNameOnly is now isHtmlOrScriptTooLargeToRead, since a scanned
  PDF is also found by name only. Its comments state the memory reason for
  both kinds and the extraction-time reason for pages.
- vault_search's opening sentence lists only what is searched; the 100 KiB,
  16 MiB and keyword-only limits move to its Behavior line.
- README and ARCHITECTURE wording; one comment unglued from its neighbour.
- Tests: a sparse 3 GiB file read by its start, the 16 MiB boundary, an
  empty file, maxBytes edge cases, exact paths in the size tests, accurate
  comments on the readFile negatives, escapes for invisible characters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                               |   4 +-
 README.md                                     |   2 +-
 src/utils/__tests__/fs.test.ts                |  58 +++++++++-
 src/utils/fs.ts                               |  20 ++--
 .../__snapshots__/tool-surface/default.json   |   2 +-
 .../tool-surface/disabled-tools.json          |   2 +-
 .../tool-surface/embedding-off.json           |   2 +-
 .../memory-off+embedding-off.json             |   2 +-
 .../tool-surface/memory-off.json              |   2 +-
 .../tool-surface/obsidian-sync.json           |   2 +-
 .../tool-surface/readonly+embedding-off.json  |   2 +-
 .../readonly+memory-off+embedding-off.json    |   2 +-
 .../tool-surface/readonly+memory-off.json     |   2 +-
 .../__snapshots__/tool-surface/readonly.json  |   2 +-
 .../__tests__/tool-definitions.test.ts        |  20 ++--
 src/vault-mcp/mcp-core/tools/search-tools.ts  |   9 +-
 .../search/__tests__/file-watcher.test.ts     |   6 +-
 .../search/__tests__/search-index.test.ts     | 102 +++++++++++-------
 src/vault-mcp/search/file-watcher.ts          |  18 ++--
 src/vault-mcp/search/search-index.ts          |  29 +++--
 20 files changed, 198 insertions(+), 90 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 9bba0d3a2..35db77c7c 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -378,12 +378,12 @@ Search indexes file content in the `file_content` + `file_content_fts` tables, c
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
 | Canvas                       | Linearized outline; file cards also go to the link graph (see Canvas above)                                       | Yes      |
 | PDF                          | Text extracted by `obsidian-markdown/pdf.ts`; a scanned or image-only PDF has none and is found by file name only | Yes      |
-| Text formats (item 3)        | The file's first 100 KiB, the only part read, with bytes that are not UTF-8 replaced rather than refused          | Yes      |
+| Text formats (item 3)        | The file's first 100 KiB, which is all indexing reads; bytes that are not UTF-8 are replaced rather than refused  | Yes      |
 | HTML (`.html`/`.htm`)        | The text a browser shows, from `obsidian-markdown/html.ts`; a page over 16 MiB is found by file name only         | Yes      |
 | Scripts (`.py`/`.sh`/`.ps1`) | The file's source; a script over 16 MiB is found by file name only                                                | No       |
 
 - **HTML extraction** runs htmlparser2's tokenizer, which keeps no element stack, so unclosed tags cost no more than closed ones. Hidden elements (script, style, noscript, template, and the fallback content of iframe, noembed and noframes) end only at a closing tag with their own name, so a stray closing tag never shows hidden text. Block elements become line breaks, other whitespace collapses, and reading stops at the 100 KiB cap. Extraction stays on the main thread, and the 16 MiB page limit keeps its measured worst case under 2 seconds.
-- **HTML pages and scripts are read as bytes**, and their text is indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds text from a page or script that a read refuses as binary or as not UTF-8. Because that test needs the whole file, a page or script over 16 MiB is never read, which caps the memory one read takes. Search finds such a file by name, even when a read would refuse it. When a watched page or script stops passing that test, its stored content is removed and its file row stays.
+- **HTML pages and scripts are read as bytes**, and their text is indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds text from a page or script that a read refuses as binary or as not UTF-8. That test needs the whole file, so indexing reads a page or script whole and skips one whose size is over 16 MiB, which limits the memory one read takes. Search finds such a file by name, even when `vault_read_file` would refuse it. When a watched page or script stops passing that test, its stored content is removed and its file row stays.
 - **Scripts are searched by keyword only.** The markdown chunker reads a script's `# comment` lines as headings and turns `snake_case` names into one word, so embedding skips scripts before their text loads.
 
 **Opt-out:** File tools are opt-out: set `FILE_TOOLS_ENABLED=false` to hide `vault_read_file` and `vault_list_files`, and strip file tool references from server metadata and other tool descriptions. The `vault_get_outgoing_links` tool continues to report file links (it indexes from the links table, not the file tools). File config vars (`MAX_FILE_BYTES`, `MAX_IMAGE_OUTPUT_BYTES`, `MAX_PDF_RENDER_PAGES`) are still parsed when disabled.
diff --git a/README.md b/README.md
index 2014f41b6..52e596dfe 100644
--- a/README.md
+++ b/README.md
@@ -283,7 +283,7 @@ Your notes embed screenshots, reference architecture diagrams, and link out to c
 - **Canvases** — a [Canvas](https://help.obsidian.md/canvas) board arrives as a readable outline: its groups, each card's content in reading order, and the connections between them. Canvas content is full-text searchable, and file references on the board appear in the link graph — backlinks and outgoing links work just like note-to-note links. The exact JSON source is one flag away when full fidelity matters
 - **PDFs** — text is extracted with heading hierarchy, code blocks, and hyperlinks preserved; PDF content is full-text searchable alongside your notes. Set `raw: true` to render pages as images instead, showing layout, diagrams, and tables that text extraction can't preserve — scanned and image-only PDFs work in this mode
 - **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written, apart from a leading byte-order mark, and their first 100 KB is full-text searchable. Any other UTF-8 text file reads back the same way. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
-- **HTML pages and scripts** — a saved page or generated report is searchable by the first 100 KB of the text a browser shows, never its tags or script code. Python, shell, and PowerShell scripts are searchable by keyword. A page or script over 16 MB is searchable by name only. Both must be UTF-8 text, and both read back as their source
+- **HTML pages and scripts** — a saved page or generated report is searchable by the first 100 KB of the text a browser shows, never its tags or script code. Python, shell, and PowerShell scripts are searchable by keyword. Both must be UTF-8 text, and both read back as their source. A page or script over 16 MB is searchable by its name only
 - **Browse** — list any visible folder's files with per-extension counts and file sizes; files a note links to report their size in the link graph too
 
 Set `FILE_TOOLS_ENABLED=false` to hide the file tools — useful when your remote vault syncs without attachments.
diff --git a/src/utils/__tests__/fs.test.ts b/src/utils/__tests__/fs.test.ts
index 4078b5f92..c21e88b4c 100644
--- a/src/utils/__tests__/fs.test.ts
+++ b/src/utils/__tests__/fs.test.ts
@@ -1,5 +1,15 @@
 import { describe, it, expect, onTestFinished, vi } from "vitest"
-import { chmod, mkdtemp, readdir, realpath, rm, symlink, writeFile, mkdir } from "node:fs/promises"
+import {
+  chmod,
+  mkdtemp,
+  readdir,
+  realpath,
+  rm,
+  symlink,
+  truncate,
+  writeFile,
+  mkdir,
+} from "node:fs/promises"
 import { join } from "node:path"
 import { tmpdir } from "node:os"
 
@@ -83,6 +93,41 @@ describe("readFileTextPrefix", () => {
     expect(await readFileTextPrefix({ path, maxBytes: 100 })).toBe("short line\n")
   })
 
+  it("returns an empty string for an empty file", async () => {
+    const dir = await makeTempDir()
+    const path = join(dir, "empty.log")
+    await writeFile(path, "", "utf8")
+
+    expect(await readFileTextPrefix({ path, maxBytes: 100 })).toBe("")
+  })
+
+  it("reads the start of a file too large to load whole", async () => {
+    const dir = await makeTempDir()
+    const path = join(dir, "huge.log")
+    await writeFile(path, "first line\n", "utf8")
+    // A sparse 3 GiB file takes no disk space, and readFile refuses any file over 2 GiB
+    await truncate(path, 3 * 1024 ** 3)
+
+    expect(await readFileTextPrefix({ path, maxBytes: 11 })).toBe("first line\n")
+  })
+
+  it("returns an empty string for a maxBytes below one byte", async () => {
+    const dir = await makeTempDir()
+    const path = join(dir, "short.log")
+    await writeFile(path, "short line\n", "utf8")
+
+    expect(await readFileTextPrefix({ path, maxBytes: 0 })).toBe("")
+    expect(await readFileTextPrefix({ path, maxBytes: 0.5 })).toBe("")
+  })
+
+  it("reads whole bytes only when maxBytes has a fraction", async () => {
+    const dir = await makeTempDir()
+    const path = join(dir, "short.log")
+    await writeFile(path, "short line\n", "utf8")
+
+    expect(await readFileTextPrefix({ path, maxBytes: 2.5 })).toBe("sh")
+  })
+
   it("returns only the first maxBytes of a longer file", async () => {
     const dir = await makeTempDir()
     const path = join(dir, "long.log")
@@ -100,13 +145,22 @@ describe("readFileTextPrefix", () => {
     expect(await readFileTextPrefix({ path, maxBytes: 3 })).toBe("ab")
   })
 
+  it("replaces an unfinished character at the end of the file, as readFile does", async () => {
+    const dir = await makeTempDir()
+    const path = join(dir, "unfinished.log")
+    // 0xE2 0x82 starts a three-byte character that the file never finishes
+    await writeFile(path, Buffer.from([0x61, 0x62, 0xe2, 0x82]))
+
+    expect(await readFileTextPrefix({ path, maxBytes: 100 })).toBe("ab\uFFFD")
+  })
+
   it("keeps a byte-order mark and replaces an invalid byte, as readFile does", async () => {
     const dir = await makeTempDir()
     const path = join(dir, "latin1.log")
     // 0xEF 0xBB 0xBF is the UTF-8 byte-order mark; 0xE9 alone is never valid UTF-8
     await writeFile(path, Buffer.from([0xef, 0xbb, 0xbf, 0x61, 0xe9, 0x62]))
 
-    expect(await readFileTextPrefix({ path, maxBytes: 100 })).toBe("a�b")
+    expect(await readFileTextPrefix({ path, maxBytes: 100 })).toBe("\uFEFFa\uFFFDb")
   })
 
   it("rejects when no file exists at the path", async () => {
diff --git a/src/utils/fs.ts b/src/utils/fs.ts
index 4359facb8..f3b220054 100644
--- a/src/utils/fs.ts
+++ b/src/utils/fs.ts
@@ -27,19 +27,27 @@ export const readFileOrNull = async (path: string): Promise<string | null> => {
 
 /** Reads at most maxBytes from the start of a file and decodes them as UTF-8
  *  the way readFile does: an invalid byte becomes a replacement character and
- *  a byte-order mark stays. The rest of the file is never loaded. */
+ *  a byte-order mark stays. The rest of the file is never loaded, and a
+ *  character that the maxBytes cut splits is left out. */
 export const readFileTextPrefix = async (params: {
   path: string
   maxBytes: number
 }): Promise<string> => {
-  // end is inclusive, so the stream stops after maxBytes bytes
+  const byteLimit = Math.floor(params.maxBytes)
+
+  if (byteLimit < 1) return ""
+
+  // end is inclusive, so the stream stops after byteLimit bytes
   const prefix = await streamToBuffer(
-    createReadStream(params.path, { start: 0, end: params.maxBytes - 1 }),
+    createReadStream(params.path, { start: 0, end: byteLimit - 1 }),
   )
+  const decoder = new StringDecoder("utf8")
+  const reachedEndOfFile = prefix.length < byteLimit
 
-  // The cut can split a character. write() holds back that character's bytes,
-  // so the text never ends in a replacement character.
-  return new StringDecoder("utf8").write(prefix)
+  // At the end of the file, end() turns an unfinished character into a
+  // replacement character, as readFile does. At a cut, write() holds back the
+  // bytes of the character the cut splits, so the text never ends in one.
+  return reachedEndOfFile ? decoder.end(prefix) : decoder.write(prefix)
 }
 
 /** Stats a path, returning null instead of throwing when nothing exists there
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
index 71c752039..11beb8803 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/default.json
@@ -1313,7 +1313,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files. Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only; scripts match by keyword only.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
index 2e4948eba..949c830ae 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/disabled-tools.json
@@ -1254,7 +1254,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files. Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only; scripts match by keyword only.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
index 42d66869f..2b5ed6209 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/embedding-off.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back. Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
index 31b30f843..80046ebb7 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off+embedding-off.json
@@ -1173,7 +1173,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back. Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
index f90a6d7b2..76e9af991 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/memory-off.json
@@ -1172,7 +1172,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files. Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only; scripts match by keyword only.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
index 5bf577840..189e049f5 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/obsidian-sync.json
@@ -1315,7 +1315,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files. Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only; scripts match by keyword only.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
index ff40a19f8..c346e6232 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+embedding-off.json
@@ -795,7 +795,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back. Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
index 1f510be4e..387281626 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off+embedding-off.json
@@ -700,7 +700,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Full-text search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by relevance. Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\nExample: vault_search({ query: \"deployment\", filters: { properties: { status: \"active\" } } })\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. At most 100 notes and 100 files come back. Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before matching; a query left with no terms returns no results.\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"fts\" — keyword-only ranking), and reranked (always false in keyword-only mode). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
index 8791f5810..1b78110f6 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly+memory-off.json
@@ -699,7 +699,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files. Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only; scripts match by keyword only.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
index 73cdd19b0..0d046c0ba 100644
--- a/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
+++ b/src/vault-mcp/mcp-core/__tests__/__snapshots__/tool-surface/readonly.json
@@ -794,7 +794,7 @@
     {
       "name": "vault_search",
       "title": "Search Notes",
-      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
+      "description": "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by combined keyword and semantic relevance. Semantic matching finds notes even when exact keywords differ — \"career aspirations\" finds notes about \"goals\" and \"targets\". Unquoted terms use implicit AND with stemming (\"running\" also matches \"run\"); wrap in double quotes for exact phrases; punctuated terms (vault-cortex, deploy/local) are matched as exact adjacent-word phrases.\n\nFilters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:\n- folder: a whole folder, subfolders included: \"Projects\" covers \"Projects/Archive\" but not \"ProjectsOld/\", ignoring ASCII letter case\n- tags: every listed tag must match, in the tags property or as a #tag in the body, in any letter case; \"project\" also matches \"project/a\"\n- type: the type property, matched exactly, letter case included\n- related: every listed link must appear in the related property, written as it is there, brackets and alias included\n- properties: keys and text values match exactly, letter case included; values compare by exact type — pass a number as a number, not \"4\". Exception: true and false compare as 1 and 0, so true or 1 matches a checked checkbox and the number 1. A list property matches when any element equals the value.\n- created / modified: bounds compare whole calendar days in the server's time zone (returned created and modified values show its UTC offset). A note whose created property is missing or not an ISO date never matches a created filter\n\nExample: vault_search({ query: \"how the server watches for file changes\" })\nExample: vault_search({ query: \"kubernetes networking\", filters: { tags: [\"reference\"] } })\nExample: vault_search({ query: \"meeting notes\", filters: { type: \"meeting\", folder: \"Work\" } })\nExample: vault_search({ query: \"decision\", filters: { modified: { after: \"2026-06-30\" } } }) — matching notes touched in July or later\n\nWhen to use: The primary discovery tool for content-based queries, optionally constrained by metadata.\nPrefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.\n\nBehavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error. With search_mode \"fts\", at most 100 notes and 100 files come back; with \"hybrid\", at most 200 notes and 200 files. Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only; scripts match by keyword only.\n- Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before keyword matching; a query left with no terms is matched by meaning only, or finds nothing when search_mode is \"fts\".\n\nErrors:\n- \"invalid created.on date: …\" or \"… is not a calendar date\" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form\n- \"tag must not be empty …\" — a tags entry is only \"#\"; pass the tag name\n- \"[SqliteError]: …\" / \"[IndexIntegrityError]: …\" — the index failed, not the call; the message says what to do\n\nReturns: JSON with results array (path, title, snippet, score, tags (the tags property), body_tags (#tags in the note's text, one per spelling; absent when none), folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes), total (results returned, not all matches), search_mode (\"hybrid\" when vector embeddings contributed, \"fts\" when only keyword matching ran), and reranked (true when a second ranking pass reordered the results). A higher score is more relevant. kind is \"note\" or, for non-markdown content, \"file\", which also carries extension (e.g. \".pdf\"). created is omitted, not null, when a result has none; type is null when the result has no type property; bytes is the on-disk size. With include_leading_callout, each result also carries leading_callout (the opening callout, { type, title, body }) when present.",
       "inputSchema": {
         "type": "object",
         "properties": {
diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index 1ba77e814..c16efaa25 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1465,7 +1465,7 @@ describe("vault_search description reflects EMBEDDING_ENABLED", () => {
     const description = findSearchDescription(registerWithConfig({}))
     const openingSentence = description.slice(0, description.indexOf(". ") + 1)
     expect(openingSentence).toBe(
-      "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only), ranked by combined keyword and semantic relevance.",
+      "Hybrid search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts), ranked by combined keyword and semantic relevance.",
     )
     expect(description).toContain("career aspirations")
     expect(description).toContain("search_mode")
@@ -1493,7 +1493,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   // only the hybrid variant says scripts match by keyword alone.
   const FILE_RESULT_WORDING = {
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched; scripts match by keyword only)",
+      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts)",
     filtersLeadIn:
       "Filters — all conditions AND-combine with each other and the text query; any filter but folder returns notes only:",
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`,
@@ -1509,7 +1509,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   const KEYWORD_ONLY_FILE_RESULT_WORDING = {
     ...FILE_RESULT_WORDING,
     searchedScope:
-      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts; a page or script over 16 MiB is found by its name only; each file's first 100 KiB of text is searched)",
+      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts)",
   }
 
   it.each([
@@ -1555,15 +1555,18 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
   })
 })
 
-describe("vault_search result cap", () => {
+describe("vault_search Behavior line: result cap and file content limits", () => {
   const BEHAVIOR_LEAD =
     "Behavior: Results can lag a file change by a few seconds. No matches returns an empty results array with total 0, not an error."
+  // Stated only while file content is searched (FILE_TOOLS_ENABLED on)
+  const FILE_CONTENT_LIMITS =
+    "Each file's first 100 KiB of text is searched; a page or script over 16 MiB is found by its name only"
 
   it.each([
     {
-      label: "bounds both modes for notes and files by default",
+      label: "bounds both modes for notes and files and states the file limits by default",
       env: {},
-      expectedLine: `${BEHAVIOR_LEAD} With search_mode "fts", at most 100 notes and 100 files come back; with "hybrid", at most 200 notes and 200 files.`,
+      expectedLine: `${BEHAVIOR_LEAD} With search_mode "fts", at most 100 notes and 100 files come back; with "hybrid", at most 200 notes and 200 files. ${FILE_CONTENT_LIMITS}; scripts match by keyword only.`,
     },
     {
       label: "bounds both modes for notes only when file tools are off",
@@ -1571,9 +1574,10 @@ describe("vault_search result cap", () => {
       expectedLine: `${BEHAVIOR_LEAD} With search_mode "fts", at most 100 notes come back; with "hybrid", at most 200 notes.`,
     },
     {
-      label: "states only the keyword bound for notes and files when embeddings are off",
+      label:
+        "states only the keyword bound for notes and files, and the file limits, when embeddings are off",
       env: { EMBEDDING_ENABLED: "false" },
-      expectedLine: `${BEHAVIOR_LEAD} At most 100 notes and 100 files come back.`,
+      expectedLine: `${BEHAVIOR_LEAD} At most 100 notes and 100 files come back. ${FILE_CONTENT_LIMITS}.`,
     },
     {
       label: "states only the keyword bound for notes when embeddings and file tools are off",
diff --git a/src/vault-mcp/mcp-core/tools/search-tools.ts b/src/vault-mcp/mcp-core/tools/search-tools.ts
index 90f4ad751..4fbec142c 100644
--- a/src/vault-mcp/mcp-core/tools/search-tools.ts
+++ b/src/vault-mcp/mcp-core/tools/search-tools.ts
@@ -93,9 +93,14 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   const scriptMatchClause = config.embeddingEnabled ? "; scripts match by keyword only" : ""
   const scriptExtensions = getExtensionsOfKind("script").join("/")
   const textExtensions = getExtensionsOfKind("text").join("/")
+  const nameOnlyLimitMiB = MAX_INDEXED_HTML_OR_SCRIPT_BYTES / (1024 * 1024)
+  const indexedPrefixKiB = MAX_INDEXED_CONTENT_BYTES / 1024
   const searchedContentText = config.fileToolsEnabled
-    ? `vault notes and file content (canvas, PDF, the text formats ${textExtensions}, the visible text of HTML pages, and ${scriptExtensions} scripts; a page or script over ${MAX_INDEXED_HTML_OR_SCRIPT_BYTES / (1024 * 1024)} MiB is found by its name only; each file's first ${MAX_INDEXED_CONTENT_BYTES / 1024} KiB of text is searched${scriptMatchClause})`
+    ? `vault notes and file content (canvas, PDF, the text formats ${textExtensions}, the visible text of HTML pages, and ${scriptExtensions} scripts)`
     : "vault notes"
+  const fileContentLimitsSentence = config.fileToolsEnabled
+    ? ` Each file's first ${indexedPrefixKiB} KiB of text is searched; a page or script over ${nameOnlyLimitMiB} MiB is found by its name only${scriptMatchClause}.`
+    : ""
   const searchResultFieldsText = config.fileToolsEnabled
     ? `path, title, snippet, score, ${tagsFieldsText}, folder (a note's top-level folder; a file's full parent folder), type, kind, extension, created, modified, bytes`
     : `path, title, snippet, score, ${tagsFieldsText}, folder (top-level folder), type, kind, created, modified, bytes`
@@ -128,7 +133,7 @@ Example: vault_search({ query: "decision", filters: { modified: { after: "2026-0
   const resultCapSentence = config.embeddingEnabled
     ? `With search_mode "fts", at most ${keywordCapExtent} come back; with "hybrid", at most ${hybridCapExtent}.`
     : `At most ${keywordCapExtent} come back.`
-  const searchBehaviorLine = `Behavior: ${INDEX_LAG_LEAD}. No matches returns an empty results array with total 0, not an error. ${resultCapSentence}
+  const searchBehaviorLine = `Behavior: ${INDEX_LAG_LEAD}. No matches returns an empty results array with total 0, not an error. ${resultCapSentence}${fileContentLimitsSentence}
 - Malformed query syntax never throws: the words AND, OR, NOT and NEAR in any letter case, and punctuation such as *, ^, parentheses and colons, are dropped before ${emptiedQueryText.stage}; ${emptiedQueryText.outcome}.`
   const searchErrorsSection = `Errors:
 - "invalid created.on date: …" or "… is not a calendar date" (any created/modified bound) — pass a real calendar date in YYYY-MM-DD form
diff --git a/src/vault-mcp/search/__tests__/file-watcher.test.ts b/src/vault-mcp/search/__tests__/file-watcher.test.ts
index 6b9ac7d5a..c9bff0fdb 100644
--- a/src/vault-mcp/search/__tests__/file-watcher.test.ts
+++ b/src/vault-mcp/search/__tests__/file-watcher.test.ts
@@ -1618,7 +1618,7 @@ describe("file watcher — obsolete events and embedding queues", () => {
 
     expect(await searchPaths("giganticpage")).toEqual(["giganticpage.html"])
     expect(await searchPaths("buriedcobalt")).toEqual([])
-    // readFile takes at most two arguments, so these two cover every read of the page
+    // These two cover a read as a buffer and a read given an encoding or options
     expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(pagePath)
     expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(pagePath, expect.anything())
   })
@@ -1637,7 +1637,7 @@ describe("file watcher — obsolete events and embedding queues", () => {
 
     expect(await searchPaths("giganticscript")).toEqual(["giganticscript.py"])
     expect(await searchPaths("buriedjasper")).toEqual([])
-    // readFile takes at most two arguments, so these two cover every read of the script
+    // These two cover a read as a buffer and a read given an encoding or options
     expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(scriptPath)
     expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(scriptPath, expect.anything())
   })
@@ -1660,7 +1660,7 @@ describe("file watcher — obsolete events and embedding queues", () => {
       path: logPath,
       maxBytes: 102_400,
     })
-    // readFile takes at most two arguments, so these two cover every whole-file read
+    // These two cover a read as a buffer and a read given an encoding or options
     expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(logPath)
     expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(logPath, expect.anything())
   })
diff --git a/src/vault-mcp/search/__tests__/search-index.test.ts b/src/vault-mcp/search/__tests__/search-index.test.ts
index a8126086e..aadae06ca 100644
--- a/src/vault-mcp/search/__tests__/search-index.test.ts
+++ b/src/vault-mcp/search/__tests__/search-index.test.ts
@@ -7,7 +7,11 @@ import Database from "better-sqlite3"
 import { DateTime } from "luxon"
 import * as sqliteVec from "sqlite-vec"
 vi.mock("sqlite-vec", { spy: true })
-import { createSearchIndex, CONTENT_INDEXED_FILE_KINDS } from "../search-index.js"
+import {
+  createSearchIndex,
+  CONTENT_INDEXED_FILE_KINDS,
+  isHtmlOrScriptTooLargeToRead,
+} from "../search-index.js"
 import type { NoteMetadata, OutgoingLinkEntry, SearchIndex, TaskEntry } from "../search-index.js"
 import type { StatusClassification } from "../../obsidian-markdown/tasks.js"
 import { logger } from "../../../logger.js"
@@ -8230,7 +8234,7 @@ describe("HTML pages", () => {
   const rebuildVaultOf = async (
     files: ReadonlyArray<{ path: string; content: string | Buffer }>,
     embedder?: Parameters<typeof createSearchIndex>[1],
-  ): Promise<SearchIndex> => {
+  ): Promise<{ fileIndex: SearchIndex; vaultDir: string }> => {
     const vaultDir = await mkdtemp(join(tmpdir(), "html-pages-"))
     onTestFinished(() => rm(vaultDir, { recursive: true }))
     for (const file of files) {
@@ -8245,7 +8249,7 @@ describe("HTML pages", () => {
       logger,
     )
     await rebuilt.embedding
-    return fileIndex
+    return { fileIndex, vaultDir }
   }
 
   /** The paths each query finds, in query order. */
@@ -8261,7 +8265,7 @@ describe("HTML pages", () => {
   }
 
   it("finds an .html or .htm page by its visible text, never by its script", async () => {
-    const fileIndex = await rebuildVaultOf([
+    const { fileIndex } = await rebuildVaultOf([
       { path: "runbook.html", content: "<p>visiblequartz</p><script>scriptquartz()</script>" },
       { path: "report.htm", content: "<p>visibleopal</p><script>scriptopal()</script>" },
     ])
@@ -8290,7 +8294,7 @@ describe("HTML pages", () => {
     const styledWords = '<span style="color: red; font-weight: bold; padding: 2px">a</span>'.repeat(
       2_000,
     )
-    const fileIndex = await rebuildVaultOf([
+    const { fileIndex } = await rebuildVaultOf([
       { path: "styled.html", content: `<p>${styledWords}</p><p>closingamber</p>` },
     ])
 
@@ -8299,26 +8303,22 @@ describe("HTML pages", () => {
 
   it("finds a page over 16 MiB by its name without reading it", async () => {
     const filler = "<p>filler</p>".repeat(Math.ceil((16 * 1024 * 1024) / 13) + 1)
-    const fileIndex = await rebuildVaultOf([
+    const { fileIndex, vaultDir } = await rebuildVaultOf([
       { path: "giganticpage.html", content: `<p>buriedcobalt</p>${filler}` },
     ])
+    const pagePath = join(vaultDir, "giganticpage.html")
 
     expect(await searchEach(fileIndex, ["giganticpage", "buriedcobalt"])).toEqual([
       ["giganticpage.html"],
       [],
     ])
-    // readFile takes at most two arguments, so these two cover every read of the page
-    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
-      expect.stringMatching(/giganticpage\.html$/),
-    )
-    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
-      expect.stringMatching(/giganticpage\.html$/),
-      expect.anything(),
-    )
+    // These two cover a read as a buffer and a read given an encoding or options
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(pagePath)
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(pagePath, expect.anything())
   })
 
   it("leaves out a page that is not UTF-8 or holds a NUL byte, and keeps the rest", async () => {
-    const fileIndex = await rebuildVaultOf([
+    const { fileIndex } = await rebuildVaultOf([
       {
         path: "latin1.html",
         // 0xE9 is "é" in Latin-1 and never a complete UTF-8 sequence
@@ -8378,7 +8378,7 @@ describe("scripts", () => {
     onTestFinished(() => {
       database.close()
     })
-    return { fileIndex, database }
+    return { fileIndex, database, vaultPath }
   }
 
   /** The paths whose indexed text matches the phrase, by keyword alone. */
@@ -8452,9 +8452,10 @@ describe("scripts", () => {
 
   it("finds a script over 16 MiB by its name without reading it", async () => {
     const filler = "# filler\n".repeat(Math.ceil((16 * 1024 * 1024) / 9) + 1)
-    const { fileIndex } = await rebuildVaultOf({
+    const { fileIndex, vaultPath } = await rebuildVaultOf({
       files: [{ path: "giganticscript.py", content: `buriedjasper = 1\n${filler}` }],
     })
+    const scriptPath = join(vaultPath, "giganticscript.py")
     const searchPaths = async (query: string) => {
       const { results } = await fileIndex.hybridSearch({ query }, logger)
       return results.map((result) => result.path)
@@ -8462,14 +8463,9 @@ describe("scripts", () => {
 
     expect(await searchPaths("giganticscript")).toEqual(["giganticscript.py"])
     expect(await searchPaths("buriedjasper")).toEqual([])
-    // readFile takes at most two arguments, so these two cover every read of the script
-    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
-      expect.stringMatching(/giganticscript\.py$/),
-    )
-    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
-      expect.stringMatching(/giganticscript\.py$/),
-      expect.anything(),
-    )
+    // These two cover a read as a buffer and a read given an encoding or options
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(scriptPath)
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(scriptPath, expect.anything())
   })
 
   it("leaves a script holding a NUL byte out of search", async () => {
@@ -8493,11 +8489,9 @@ describe("text formats in a rebuild", () => {
   it("reads only the first 100 KiB of a text file, all the text search keeps", async () => {
     const vaultDir = await mkdtemp(join(tmpdir(), "text-formats-"))
     onTestFinished(() => rm(vaultDir, { recursive: true }))
+    const logPath = join(vaultDir, "prefixread.log")
     // The opening word sits inside the first 100 KiB and the closing word past it
-    await writeFile(
-      join(vaultDir, "prefixread.log"),
-      `openingtopaz\n${"x ".repeat(60_000)}\nclosingtopaz\n`,
-    )
+    await writeFile(logPath, `openingtopaz\n${"x ".repeat(60_000)}\nclosingtopaz\n`)
     const fileIndex = createSearchIndex(":memory:", undefined, undefined, {
       fileToolsEnabled: true,
     })
@@ -8513,15 +8507,51 @@ describe("text formats in a rebuild", () => {
     expect(await searchPaths("openingtopaz")).toEqual(["prefixread.log"])
     expect(await searchPaths("closingtopaz")).toEqual([])
     expect(vi.mocked(readFileTextPrefix)).toHaveBeenCalledWith({
-      path: expect.stringMatching(/prefixread\.log$/),
+      path: logPath,
       maxBytes: 102_400,
     })
-    // readFile takes at most two arguments, so these two cover every whole-file read
-    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(expect.stringMatching(/prefixread\.log$/))
-    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(
-      expect.stringMatching(/prefixread\.log$/),
-      expect.anything(),
-    )
+    // These two cover a read as a buffer and a read given an encoding or options
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(logPath)
+    expect(vi.mocked(readFile)).not.toHaveBeenCalledWith(logPath, expect.anything())
+  })
+})
+
+describe("isHtmlOrScriptTooLargeToRead", () => {
+  const limitBytes = 16 * 1024 * 1024
+
+  it.each([
+    {
+      label: "reads a script of exactly 16 MiB",
+      filePath: "big.py",
+      fileBytes: limitBytes,
+      expected: false,
+    },
+    {
+      label: "skips a script one byte over 16 MiB",
+      filePath: "big.py",
+      fileBytes: limitBytes + 1,
+      expected: true,
+    },
+    {
+      label: "reads a page of exactly 16 MiB",
+      filePath: "big.html",
+      fileBytes: limitBytes,
+      expected: false,
+    },
+    {
+      label: "skips a page one byte over 16 MiB",
+      filePath: "big.html",
+      fileBytes: limitBytes + 1,
+      expected: true,
+    },
+    {
+      label: "never skips a text file, which is read by its first bytes",
+      filePath: "big.log",
+      fileBytes: limitBytes + 1,
+      expected: false,
+    },
+  ])("$label", ({ filePath, fileBytes, expected }) => {
+    expect(isHtmlOrScriptTooLargeToRead({ filePath, fileBytes })).toBe(expected)
   })
 })
 
diff --git a/src/vault-mcp/search/file-watcher.ts b/src/vault-mcp/search/file-watcher.ts
index 058391d66..713479657 100644
--- a/src/vault-mcp/search/file-watcher.ts
+++ b/src/vault-mcp/search/file-watcher.ts
@@ -11,7 +11,7 @@ import { join, relative, resolve as resolvePath, sep } from "node:path"
 import {
   CONTENT_INDEXED_FILE_KINDS,
   INDEXING_FILE_READ_CONCURRENCY,
-  isIndexedByNameOnly,
+  isHtmlOrScriptTooLargeToRead,
   MAX_INDEXED_CONTENT_BYTES,
   PDF_EXTRACTION_CONCURRENCY,
 } from "./search-index.js"
@@ -262,28 +262,28 @@ const startHoldingWatcher = (params: WatchVaultParams, logger: Logger): HoldingW
             }
             case "html":
             case "script": {
-              const indexedByNameOnly = isIndexedByNameOnly({
+              const tooLargeToRead = isHtmlOrScriptTooLargeToRead({
                 filePath: relativePath,
                 fileBytes: fileStat.size,
               })
 
-              if (indexedByNameOnly) return ""
+              if (tooLargeToRead) return ""
               const decodedSource = decodeTextBuffer(await readFile(filePath))
 
               if (decodedSource.status !== "text") return null
               return decodedSource.text
             }
-            // Text formats and canvases decode leniently, so a stray invalid byte
-            // or NUL padding keeps them in search. Search keeps a text file's
-            // first MAX_INDEXED_CONTENT_BYTES only, so no more is read.
+            // Search keeps a text file's first MAX_INDEXED_CONTENT_BYTES only, so
+            // no more is read. The read decodes leniently, so a stray invalid byte
+            // or NUL padding keeps the file in search.
             case "text":
               return await readFileTextPrefix({
                 path: filePath,
                 maxBytes: MAX_INDEXED_CONTENT_BYTES,
               })
-            // A canvas is read whole, because its links need the whole JSON.
-            // Images and other files never reach this switch: the guard above
-            // reads only the kinds search indexes.
+            // A canvas is read whole, because its links need the whole JSON, and
+            // it decodes leniently like a text file. Images and other files never
+            // reach this switch: the guard above reads only the kinds search indexes.
             case "canvas":
             case "image":
             case "other":
diff --git a/src/vault-mcp/search/search-index.ts b/src/vault-mcp/search/search-index.ts
index ac75aa75c..0645f00e3 100644
--- a/src/vault-mcp/search/search-index.ts
+++ b/src/vault-mcp/search/search-index.ts
@@ -86,16 +86,19 @@ const EMBEDDED_FILE_KINDS: ReadonlySet<FileKind> = new Set(["canvas", "pdf", "te
 export const MAX_INDEXED_CONTENT_BYTES = 102_400
 
 /** An HTML page or script larger than this is indexed by its name only, like a
- *  scanned PDF. Each kind has its own reason for the same limit:
- *  - a page's text is extracted on the main thread, which answers no request
- *    meanwhile, and attribute-heavy pages at 16 MiB already took up to 1.7 s;
- *  - a script is read whole, because indexing keeps its text only when every
- *    byte is UTF-8, so the limit bounds the memory one read takes. */
+ *  scanned PDF. The limit bounds two costs:
+ *  - indexing reads a page or script whole, because it keeps the text only
+ *    when every byte is UTF-8, so the limit keeps one read's memory near it;
+ *  - a page's text is also extracted on the main thread, which answers no
+ *    request meanwhile, and attribute-heavy pages at 16 MiB took up to 1.7 s. */
 export const MAX_INDEXED_HTML_OR_SCRIPT_BYTES = 16 * 1024 * 1024
 
-/** True for an HTML page or script over the size limit. Search finds such a
- *  file by its name only, so indexing never reads it. */
-export const isIndexedByNameOnly = (params: { filePath: string; fileBytes: number }): boolean => {
+/** True for an HTML page or script over MAX_INDEXED_HTML_OR_SCRIPT_BYTES.
+ *  Indexing never reads such a file, so search finds it by its name only. */
+export const isHtmlOrScriptTooLargeToRead = (params: {
+  filePath: string
+  fileBytes: number
+}): boolean => {
   const fileKind = getFileKind(params.filePath)
   const isHtmlOrScript = fileKind === "html" || fileKind === "script"
 
@@ -116,7 +119,9 @@ const fileTextToIndexedText = (params: {
     case "canvas":
       return linearizeCanvas(params.fileText)
     case "html":
-      if (isIndexedByNameOnly(params)) return ""
+      // Extraction blocks the main thread, so a page over the limit is never
+      // extracted, even when a caller passes its source in directly
+      if (isHtmlOrScriptTooLargeToRead(params)) return ""
       return extractHtmlVisibleText({
         html: params.fileText,
         maxBytes: MAX_INDEXED_CONTENT_BYTES,
@@ -2453,6 +2458,7 @@ export const createSearchIndex = (
         return null
       }
     }
+
     // Read canvas files for content indexing + link extraction.
     const canvasContentResults = await mapWithConcurrency({
       items: canvasFiles,
@@ -2517,13 +2523,14 @@ export const createSearchIndex = (
       const readDecodedFile = async () => {
         try {
           const fileStat = await stat(file.absolutePath)
-          const indexedByNameOnly = isIndexedByNameOnly({
+          const tooLargeToRead = isHtmlOrScriptTooLargeToRead({
             filePath: file.relativePath,
             fileBytes: fileStat.size,
           })
 
-          if (indexedByNameOnly)
+          if (tooLargeToRead) {
             return { decodedText: { status: "text", text: "" } as const, fileStat }
+          }
           return { decodedText: decodeTextBuffer(await readFile(file.absolutePath)), fileStat }
         } catch (error) {
           logger.warn("skipped unreadable file during rebuild", {

From 90be8c4a62fcea1dd0d985fd877dde4121ccfb75 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 13:55:43 -0500
Subject: [PATCH 35/38] fix(search): decode a file exactly maxBytes long like
 readFile

readFileTextPrefix treated a file of exactly maxBytes as cut and dropped an unfinished
character at its end. It now reads one byte past the limit to tell a cut from the
file's end, so such a file ends in a replacement character, as readFile gives.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/utils/__tests__/fs.test.ts |  9 +++++++++
 src/utils/fs.ts                | 26 ++++++++++++++------------
 2 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/src/utils/__tests__/fs.test.ts b/src/utils/__tests__/fs.test.ts
index c21e88b4c..546a5208a 100644
--- a/src/utils/__tests__/fs.test.ts
+++ b/src/utils/__tests__/fs.test.ts
@@ -154,6 +154,15 @@ describe("readFileTextPrefix", () => {
     expect(await readFileTextPrefix({ path, maxBytes: 100 })).toBe("ab\uFFFD")
   })
 
+  it("replaces an unfinished character at the end of a file exactly maxBytes long", async () => {
+    const dir = await makeTempDir()
+    const path = join(dir, "exact.log")
+    // The file ends at the limit, so nothing is cut and readFile's decoding applies
+    await writeFile(path, Buffer.from([0x61, 0x62, 0xe2, 0x82]))
+
+    expect(await readFileTextPrefix({ path, maxBytes: 4 })).toBe("ab\uFFFD")
+  })
+
   it("keeps a byte-order mark and replaces an invalid byte, as readFile does", async () => {
     const dir = await makeTempDir()
     const path = join(dir, "latin1.log")
diff --git a/src/utils/fs.ts b/src/utils/fs.ts
index f3b220054..b95936fc1 100644
--- a/src/utils/fs.ts
+++ b/src/utils/fs.ts
@@ -25,10 +25,9 @@ export const readFileOrNull = async (path: string): Promise<string | null> => {
   }
 }
 
-/** Reads at most maxBytes from the start of a file and decodes them as UTF-8
- *  the way readFile does: an invalid byte becomes a replacement character and
- *  a byte-order mark stays. The rest of the file is never loaded, and a
- *  character that the maxBytes cut splits is left out. */
+/** Decodes as UTF-8 the way readFile does: an invalid byte becomes a
+ *  replacement character and a byte-order mark stays. Reads at most one byte
+ *  past maxBytes, and leaves out a character that the maxBytes cut splits. */
 export const readFileTextPrefix = async (params: {
   path: string
   maxBytes: number
@@ -37,17 +36,20 @@ export const readFileTextPrefix = async (params: {
 
   if (byteLimit < 1) return ""
 
-  // end is inclusive, so the stream stops after byteLimit bytes
-  const prefix = await streamToBuffer(
-    createReadStream(params.path, { start: 0, end: byteLimit - 1 }),
+  // end is inclusive, so the stream stops after byteLimit + 1 bytes. The extra
+  // byte shows whether the file goes on past byteLimit.
+  const readBytes = await streamToBuffer(
+    createReadStream(params.path, { start: 0, end: byteLimit }),
   )
   const decoder = new StringDecoder("utf8")
-  const reachedEndOfFile = prefix.length < byteLimit
+  const fileContinuesPastLimit = readBytes.length > byteLimit
 
-  // At the end of the file, end() turns an unfinished character into a
-  // replacement character, as readFile does. At a cut, write() holds back the
-  // bytes of the character the cut splits, so the text never ends in one.
-  return reachedEndOfFile ? decoder.end(prefix) : decoder.write(prefix)
+  // At a cut, write() holds back the bytes of the character the cut splits, so
+  // the text never ends in a replacement character. At the end of the file,
+  // end() turns an unfinished character into one, as readFile does.
+  return fileContinuesPastLimit
+    ? decoder.write(readBytes.subarray(0, byteLimit))
+    : decoder.end(readBytes)
 }
 
 /** Stats a path, returning null instead of throwing when nothing exists there

From af542469692d9e655ca75993bef50c2699f5d889 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 14:22:33 -0500
Subject: [PATCH 36/38] fix(search): leave an inline SVG's title and desc out
 of a page's indexed text

A tooltip inside an inline <svg> is never shown on the page, but the extractor indexed it
as text, so a search could match a page on its icons' tooltips. Title and desc inside an
open svg are now hidden like script; a self-closing <desc/> or <svg/> there holds nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                               |  2 +-
 .../obsidian-markdown/__tests__/html.test.ts  | 24 ++++++++++
 src/vault-mcp/obsidian-markdown/html.ts       | 47 +++++++++++++++++--
 3 files changed, 69 insertions(+), 4 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 35db77c7c..1d68ccb2e 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -382,7 +382,7 @@ Search indexes file content in the `file_content` + `file_content_fts` tables, c
 | HTML (`.html`/`.htm`)        | The text a browser shows, from `obsidian-markdown/html.ts`; a page over 16 MiB is found by file name only         | Yes      |
 | Scripts (`.py`/`.sh`/`.ps1`) | The file's source; a script over 16 MiB is found by file name only                                                | No       |
 
-- **HTML extraction** runs htmlparser2's tokenizer, which keeps no element stack, so unclosed tags cost no more than closed ones. Hidden elements (script, style, noscript, template, and the fallback content of iframe, noembed and noframes) end only at a closing tag with their own name, so a stray closing tag never shows hidden text. Block elements become line breaks, other whitespace collapses, and reading stops at the 100 KiB cap. Extraction stays on the main thread, and the 16 MiB page limit keeps its measured worst case under 2 seconds.
+- **HTML extraction** runs htmlparser2's tokenizer, which keeps no element stack, so unclosed tags cost no more than closed ones. Hidden elements (script, style, noscript, template, the fallback content of iframe, noembed and noframes, and an inline SVG's title and desc tooltips) end only at a closing tag with their own name, so a stray closing tag never shows hidden text. Block elements become line breaks, other whitespace collapses, and reading stops at the 100 KiB cap. Extraction stays on the main thread, and the 16 MiB page limit keeps its measured worst case under 2 seconds.
 - **HTML pages and scripts are read as bytes**, and their text is indexed only when `utils/decode-text-buffer.ts` accepts them, the test `vault_read_file` applies, so search never holds text from a page or script that a read refuses as binary or as not UTF-8. That test needs the whole file, so indexing reads a page or script whole and skips one whose size is over 16 MiB, which limits the memory one read takes. Search finds such a file by name, even when `vault_read_file` would refuse it. When a watched page or script stops passing that test, its stored content is removed and its file row stays.
 - **Scripts are searched by keyword only.** The markdown chunker reads a script's `# comment` lines as headings and turns `snake_case` names into one word, so embedding skips scripts before their text loads.
 
diff --git a/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts b/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
index 5b0c16f6b..febac3584 100644
--- a/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
+++ b/src/vault-mcp/obsidian-markdown/__tests__/html.test.ts
@@ -56,6 +56,30 @@ describe("extractHtmlVisibleText", () => {
     )
   })
 
+  it("drops an inline SVG's title and desc but keeps its visible text", () => {
+    const page =
+      "<p>Download</p><svg><title>download icon</title><desc>an arrow</desc>" +
+      "<text>Q3 total</text></svg><p>After</p>"
+
+    expect(extractAll(page)).toBe("Download\nQ3 total\nAfter")
+  })
+
+  it("shows a title after the SVG holding another title closes", () => {
+    expect(extractAll("<svg><title>icon</title></svg><title>Page title</title>")).toBe("Page title")
+  })
+
+  it("keeps an SVG title hidden after a nested svg closes", () => {
+    expect(extractAll("<svg><svg></svg><title>tooltip</title></svg><p>shown</p>")).toBe("shown")
+  })
+
+  it("shows the rest of the page after a self-closing desc inside an SVG", () => {
+    expect(extractAll("<svg><desc/></svg><p>shown</p>")).toBe("shown")
+  })
+
+  it("shows a title after a self-closing svg", () => {
+    expect(extractAll("<svg/><title>Page title</title>")).toBe("Page title")
+  })
+
   it("breaks no line for a block element inside a hidden element", () => {
     expect(extractAll("<p>one <template><div>inert</div></template>two</p>")).toBe("one two")
   })
diff --git a/src/vault-mcp/obsidian-markdown/html.ts b/src/vault-mcp/obsidian-markdown/html.ts
index 02e9eddd0..9cb874641 100644
--- a/src/vault-mcp/obsidian-markdown/html.ts
+++ b/src/vault-mcp/obsidian-markdown/html.ts
@@ -15,6 +15,10 @@ const HIDDEN_ELEMENTS: ReadonlySet<string> = new Set([
   "noframes",
 ])
 
+/** Inside an inline <svg>, the tooltip and the description a browser never
+ *  shows on the page. Outside one, <title> is the page's own title. */
+const SVG_TOOLTIP_ELEMENTS: ReadonlySet<string> = new Set(["title", "desc"])
+
 /** Elements that start and end on a line of their own when a page renders. */
 const LINE_BREAKING_ELEMENTS: ReadonlySet<string> = new Set([
   "address",
@@ -89,6 +93,10 @@ export const extractHtmlVisibleText = (params: { html: string; maxBytes: number
   let atLineStart = true
   let spaceOwed = false
   let textBytes = 0
+  // Also threaded in document order: how many inline <svg> elements are open,
+  // and what opening the last tag did, so a self-closing slash can undo it
+  let openSvgCount = 0
+  let lastOpenEffect: "pushed-svg-tooltip" | "counted-svg" | "none" = "none"
 
   const emit = (text: string): void => {
     textParts.push(text)
@@ -143,12 +151,23 @@ export const extractHtmlVisibleText = (params: { html: string; maxBytes: number
       // slash on an element that is not void, so the name alone decides.
       onopentagname: (start, end) => {
         const tagName = readTagName(start, end)
+        const isSvgTooltip = openSvgCount > 0 && SVG_TOOLTIP_ELEMENTS.has(tagName)
+        const opensHiddenElement = HIDDEN_ELEMENTS.has(tagName) || isSvgTooltip
 
-        if (HIDDEN_ELEMENTS.has(tagName)) {
+        if (opensHiddenElement) {
           hiddenElementStack.push(tagName)
+          lastOpenEffect = isSvgTooltip ? "pushed-svg-tooltip" : "none"
           return
         }
-        if (hiddenElementStack.length === 0) handleTagBoundary(tagName)
+
+        lastOpenEffect = "none"
+        if (hiddenElementStack.length > 0) return
+
+        if (tagName === "svg") {
+          openSvgCount += 1
+          lastOpenEffect = "counted-svg"
+        }
+        handleTagBoundary(tagName)
       },
       onclosetag: (start, end) => {
         const tagName = readTagName(start, end)
@@ -157,8 +176,31 @@ export const extractHtmlVisibleText = (params: { html: string; maxBytes: number
           if (hiddenElementStack.at(-1) === tagName) hiddenElementStack.pop()
           return
         }
+        // A stray </svg> leaves the count at zero
+        if (tagName === "svg") openSvgCount = Math.max(0, openSvgCount - 1)
         handleTagBoundary(tagName)
       },
+      // SVG honours a self-closing slash, so <svg/>, and a <desc/> or <title/>
+      // inside one, hold nothing; a tooltip left open would hide the rest of the
+      // page. The tokenizer still reads text after a <title/> raw until
+      // </title>, as it does after a self-closing <script/>, which stays open.
+      // The callback fires right after its tag opens, so it undoes that tag alone.
+      onselfclosingtag: () => {
+        const insideSvg = openSvgCount > 0
+
+        if (!insideSvg) return
+        switch (lastOpenEffect) {
+          case "pushed-svg-tooltip":
+            hiddenElementStack.pop()
+            break
+          case "counted-svg":
+            openSvgCount -= 1
+            break
+          case "none":
+            break
+        }
+        lastOpenEffect = "none"
+      },
       onattribdata: ignoreToken,
       onattribentity: ignoreToken,
       onattribend: ignoreToken,
@@ -169,7 +211,6 @@ export const extractHtmlVisibleText = (params: { html: string; maxBytes: number
       onend: ignoreToken,
       onopentagend: ignoreToken,
       onprocessinginstruction: ignoreToken,
-      onselfclosingtag: ignoreToken,
     },
   )
 

From a0c4113d7f0d3eeab1c85be618d8325c851e6586 Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 14:36:10 -0500
Subject: [PATCH 37/38] test(tools): drop a keyword-only expectation identical
 to the hybrid one

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../mcp-core/__tests__/tool-definitions.test.ts       | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
index c16efaa25..c6a572799 100644
--- a/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
+++ b/src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
@@ -1489,8 +1489,8 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
 
   // Search indexes file content only while file tools are on, so with them
   // off the description must not mention file content, the extension field,
-  // or file results. Both embedding variants share this wording, except that
-  // only the hybrid variant says scripts match by keyword alone.
+  // or file results. Both embedding variants share this wording; the Behavior
+  // line tests below pin where they differ.
   const FILE_RESULT_WORDING = {
     searchedScope:
       "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts)",
@@ -1506,11 +1506,6 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
     resultFields: `results array (path, title, snippet, score, ${TAG_FIELDS_WORDING}, folder (top-level folder), type, kind, created, modified, bytes`,
     kindSentence: 'kind is always "note".',
   }
-  const KEYWORD_ONLY_FILE_RESULT_WORDING = {
-    ...FILE_RESULT_WORDING,
-    searchedScope:
-      "search across vault notes and file content (canvas, PDF, the text formats .txt/.csv/.json/.xml/.svg/.log/.yaml/.yml/.base, the visible text of HTML pages, and .py/.sh/.ps1 scripts)",
-  }
 
   it.each([
     {
@@ -1526,7 +1521,7 @@ describe("vault_search description reflects FILE_TOOLS_ENABLED", () => {
     {
       label: "advertises file results in the keyword-only variant while file tools are on",
       env: { EMBEDDING_ENABLED: "false" },
-      expectedWording: KEYWORD_ONLY_FILE_RESULT_WORDING,
+      expectedWording: FILE_RESULT_WORDING,
     },
     {
       label: "advertises notes only in the keyword-only variant when file tools are off",

From c6f5b56b07182ec72534042d09c8f0de77aaf86a Mon Sep 17 00:00:00 2001
From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com>
Date: Sat, 7 Nov 2026 15:22:14 -0500
Subject: [PATCH 38/38] docs: say any other UTF-8 file reads as text but is
 found by browsing, not search

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 52e596dfe..e185bfe7b 100644
--- a/README.md
+++ b/README.md
@@ -282,8 +282,9 @@ Your notes embed screenshots, reference architecture diagrams, and link out to c
 - **Images** — the image itself, not the filename. Screenshots and diagrams are downscaled and recompressed server-side when they exceed what MCP clients accept, so even a phone session can look at a 5MB architecture diagram
 - **Canvases** — a [Canvas](https://help.obsidian.md/canvas) board arrives as a readable outline: its groups, each card's content in reading order, and the connections between them. Canvas content is full-text searchable, and file references on the board appear in the link graph — backlinks and outgoing links work just like note-to-note links. The exact JSON source is one flag away when full fidelity matters
 - **PDFs** — text is extracted with heading hierarchy, code blocks, and hyperlinks preserved; PDF content is full-text searchable alongside your notes. Set `raw: true` to render pages as images instead, showing layout, diagrams, and tables that text extraction can't preserve — scanned and image-only PDFs work in this mode
-- **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written, apart from a leading byte-order mark, and their first 100 KB is full-text searchable. Any other UTF-8 text file reads back the same way. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
+- **Text and data files** — TXT, SVG, JSON, XML, CSV, YAML, logs, and [Bases](https://help.obsidian.md/bases) files return exactly as written, apart from a leading byte-order mark, and their first 100 KB is full-text searchable. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
 - **HTML pages and scripts** — a saved page or generated report is searchable by the first 100 KB of the text a browser shows, never its tags or script code. Python, shell, and PowerShell scripts are searchable by keyword. Both must be UTF-8 text, and both read back as their source. A page or script over 16 MB is searchable by its name only
+- **Other text files** — a file of any other type, such as a `.js` file, a `.toml` config or a file with no extension, reads back the way a text file does when its content is UTF-8. Search doesn't index these, so browse a folder to find them
 - **Browse** — list any visible folder's files with per-extension counts and file sizes; files a note links to report their size in the link graph too
 
 Set `FILE_TOOLS_ENABLED=false` to hide the file tools — useful when your remote vault syncs without attachments.