@openparachute/vault 0.7.0-rc.1 → 0.7.0-rc.3

package/core/src/cursor.ts

@@ -94,41 +94,59 @@ export function encodeCursor(payload: CursorPayload): string {
   return Buffer.from(json, "utf8").toString("base64url");
 }
 
-/** Decode a cursor string. Throws `CursorError` on any structural problem. */
+/**
+ * Trailing hint appended to every `cursor_invalid` message (vault#550) so a
+ * caller who passed a garbage cursor — or never understood the bootstrap
+ * shape in the first place — gets the actual recovery flow, not just "this
+ * string is broken." The bootstrap flow: an EMPTY string (`cursor: ""` /
+ * `?cursor=`) opts into cursor mode without a watermark yet; the response's
+ * `next_cursor` is what you pass on every call after that.
+ */
+const CURSOR_BOOTSTRAP_HINT =
+  'first call: pass cursor:"" (or omit `cursor` entirely for a plain, non-paginated list); the response carries `next_cursor` — pass that back on each subsequent call to resume from the watermark.';
+
+/**
+ * Decode a cursor string. Throws `CursorError` on any structural problem.
+ * An EMPTY string is deliberately NOT accepted here — callers (queryNotes /
+ * queryNotesPaged) must special-case `opts.cursor === ""` as "cursor mode,
+ * no watermark yet" and skip calling this at all (vault#550 bootstrap fix).
+ * Any caller that reaches this function with an empty string gets the same
+ * loud `cursor_invalid` as any other malformed cursor.
+ */
 export function decodeCursor(cursor: string): CursorPayload {
   if (typeof cursor !== "string" || cursor.length === 0) {
-    throw new CursorError("cursor must be a non-empty string", "cursor_invalid");
+    throw new CursorError(`cursor must be a non-empty string — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   let json: string;
   try {
     json = Buffer.from(cursor, "base64url").toString("utf8");
   } catch {
-    throw new CursorError("cursor is not valid base64url", "cursor_invalid");
+    throw new CursorError(`cursor is not valid base64url — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   let parsed: unknown;
   try {
     parsed = JSON.parse(json);
   } catch {
-    throw new CursorError("cursor payload is not valid JSON", "cursor_invalid");
+    throw new CursorError(`cursor payload is not valid JSON — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   if (!parsed || typeof parsed !== "object") {
-    throw new CursorError("cursor payload must be an object", "cursor_invalid");
+    throw new CursorError(`cursor payload must be an object — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   const p = parsed as Record<string, unknown>;
   if (typeof p.v !== "number" || p.v !== CURSOR_VERSION) {
     throw new CursorError(
-      `cursor schema version mismatch (expected ${CURSOR_VERSION}, got ${String(p.v)})`,
+      `cursor schema version mismatch (expected ${CURSOR_VERSION}, got ${String(p.v)}) — ${CURSOR_BOOTSTRAP_HINT}`,
       "cursor_invalid",
     );
   }
   if (typeof p.last_updated_at !== "number" || !Number.isFinite(p.last_updated_at)) {
-    throw new CursorError("cursor.last_updated_at must be a finite number", "cursor_invalid");
+    throw new CursorError(`cursor.last_updated_at must be a finite number — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   if (typeof p.last_id !== "string") {
-    throw new CursorError("cursor.last_id must be a string", "cursor_invalid");
+    throw new CursorError(`cursor.last_id must be a string — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   if (typeof p.query_hash !== "string" || p.query_hash.length === 0) {
-    throw new CursorError("cursor.query_hash must be a non-empty string", "cursor_invalid");
+    throw new CursorError(`cursor.query_hash must be a non-empty string — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   return {
     v: p.v,

package/core/src/links.ts

@@ -404,6 +404,66 @@ export function traverseLinks(
   return results;
 }
 
+/** Hydrated find-path result — see `hydratePathResult` for field semantics. */
+export interface FindPathResult {
+  /** Note IDs, source → target (unchanged shape — back-compat). */
+  path: string[];
+  /** relationships[i] is the edge connecting path[i] to path[i+1] (unchanged shape). */
+  relationships: string[];
+  /**
+   * Hydrated companion to `path[]` (vault#550, additive): one entry per
+   * node, in the same order, carrying the note's `path` field alongside
+   * its `id` — so a caller doesn't have to round-trip each id through a
+   * separate note fetch just to render a human-legible chain.
+   */
+  nodes: { id: string; path: string | null }[];
+  /**
+   * Hydrated companion to `relationships[]` (vault#550, additive): each
+   * hop as a self-contained `{source, target, relationship}` edge plus
+   * both endpoints' note `path`, so a graph-rendering client can draw the
+   * chain without cross-referencing `nodes`.
+   */
+  edges: {
+    source: string;
+    target: string;
+    relationship: string;
+    sourcePath: string | null;
+    targetPath: string | null;
+  }[];
+}
+
+/**
+ * Hydrate a raw BFS result (`path` ids + `relationships`) with each node's
+ * note `path` field, in ONE batched query (not one fetch per hop). `path`
+ * and `relationships` pass through byte-identical to before this existed —
+ * `nodes`/`edges` are pure additions.
+ */
+function hydratePathResult(db: Database, path: string[], relationships: string[]): FindPathResult {
+  const pathById = new Map<string, string | null>();
+  for (const chunk of chunkForInClause(path)) {
+    const placeholders = chunk.map(() => "?").join(", ");
+    const rows = db.prepare(`SELECT id, path FROM notes WHERE id IN (${placeholders})`).all(...chunk) as
+      { id: string; path: string | null }[];
+    for (const row of rows) pathById.set(row.id, row.path);
+  }
+
+  const nodes = path.map((id) => ({ id, path: pathById.get(id) ?? null }));
+  const edges: FindPathResult["edges"] = [];
+  for (let i = 0; i < path.length - 1; i++) {
+    const source = path[i]!;
+    const target = path[i + 1]!;
+    edges.push({
+      source,
+      target,
+      relationship: relationships[i] ?? "",
+      sourcePath: pathById.get(source) ?? null,
+      targetPath: pathById.get(target) ?? null,
+    });
+  }
+
+  return { path, relationships, nodes, edges };
+}
+
 /**
  * Find a path between two notes in the link graph.
  * Returns the sequence of note IDs from source to target, or null if no path exists.
@@ -413,11 +473,11 @@ export function findPath(
   sourceId: string,
   targetId: string,
   opts?: { max_depth?: number },
-): { path: string[]; relationships: string[] } | null {
+): FindPathResult | null {
   const maxDepth = opts?.max_depth ?? 5;
 
   if (sourceId === targetId) {
-    return { path: [sourceId], relationships: [] };
+    return hydratePathResult(db, [sourceId], []);
   }
 
   // BFS from source
@@ -460,7 +520,7 @@ export function findPath(
             current = entry.parent;
           }
           path.unshift(sourceId);
-          return { path, relationships };
+          return hydratePathResult(db, path, relationships);
         }
       }
     }

package/core/src/mcp.ts

@@ -4,7 +4,9 @@ import { transactionAsync } from "./txn.js";
 import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
 import { QueryError } from "./query-operators.js";
-import { TAG_EXPAND_MODES, stripTagHash, type TagExpandMode } from "./tag-hierarchy.js";
+import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "./tag-hierarchy.js";
+import { collectUnknownTagWarnings, emptySearchWarning, ignoredParamWarning, type QueryWarning } from "./query-warnings.js";
+import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "./search-query.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -237,7 +239,14 @@ Defaults: include_content=true for single note, false for lists. include_links=f
 
 Large notes: pass \`content_offset\` / \`content_length\` (UTF-8 bytes) for a bounded read of note content — the response carries the slice plus \`content_total_length\` and \`content_next_offset\` (null when complete). Loop, feeding \`content_next_offset\` back as \`content_offset\`, to read a note too large for one response.
 
-Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returned content. Tune with \`expand_depth\` (1–3, default 1) and \`expand_mode\` ("full" inlines full content, "summary" inlines only metadata.summary). Expansions are deduplicated across the query and cycle-guarded.`,
+Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returned content. Tune with \`expand_depth\` (1–3, default 1) and \`expand_mode\` ("full" inlines full content, "summary" inlines only metadata.summary). Expansions are deduplicated across the query and cycle-guarded.
+
+Response shape (vault#550 — three variants, pick by what you passed):
+- Default (no \`cursor\`, no warnings): a bare array of notes.
+- Cursor mode (\`cursor\` param present — including \`cursor: ""\` to bootstrap): \`{notes: [...], next_cursor}\`. See \`cursor\` below for the bootstrap flow.
+- Warnings present (e.g. an unrecognized \`tag\`) and NOT in cursor mode: \`{notes: [...], warnings: [...]}\`. Cursor mode + warnings compose: \`{notes, next_cursor, warnings}\`. Absent \`warnings\` key means nothing to flag — don't assume its presence either way.
+
+\`search\` is literal-by-default (vault#551): your text is escaped and phrase-quoted before it reaches FTS5, so ordinary punctuation ("didn't", "eleven-day", "18.6") is matched as literal content instead of being parsed as query syntax (a bare hyphen used to mean NOT; an apostrophe or decimal point used to break the parse and silently return \`[]\`). Pass \`search_mode: "advanced"\` to opt back into raw FTS5 syntax (AND/OR/NOT, manual phrase quoting, prefix \`*\`) — a malformed advanced query now throws a structured error instead of silently returning \`[]\`. \`sort\` is honored under \`search\` too: omit it for relevance ranking (default), or pass "asc"/"desc" to order by \`created_at\` instead.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -291,7 +300,17 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             ],
             description: "Filter by file extension (vault#328). Pass a single extension (e.g. \"csv\") or an array (e.g. [\"csv\", \"yaml\", \"json\"]). Notes default to \"md\"; case-insensitive match.",
           },
-          search: { type: "string", description: "Full-text search query" },
+          search: {
+            type: "string",
+            description:
+              'Full-text search query. Literal-by-default (vault#551): your text is escaped and phrase-quoted before reaching FTS5, so punctuation ("didn\'t", "eleven-day", "18.6") is matched as literal content rather than parsed as FTS5 query syntax. Pass `search_mode: "advanced"` for raw FTS5 syntax (boolean/phrase/prefix operators). `sort` is honored under search (see below) — default is relevance ranking.',
+          },
+          search_mode: {
+            type: "string",
+            enum: [...SEARCH_MODES],
+            description:
+              'How `search` text is turned into an FTS5 query (vault#551). "literal" (DEFAULT): escape + phrase-quote the text so punctuation is literal content, not FTS5 syntax — the fix for `search: "didn\'t"` / "eleven-day" / "18.6" silently returning `[]`. "advanced": pass the text through to FTS5 raw, for callers who want boolean (AND/OR/NOT), manual phrase quoting, or prefix (`*`) syntax — a malformed advanced query throws a structured error (`error_type: "invalid_search_syntax"`) instead of silently returning `[]`. Has no effect without `search` (an `ignored_param` warning fires if you pass it without `search`). Omit for the default ("literal").',
+          },
           metadata: {
             type: "object",
             description: "Filter by metadata values. Each value is either a primitive (exact match, scans JSON) or an operator object: `{eq|ne|gt|gte|lt|lte|in|not_in|exists: value}`. Operator objects require the field to be declared `indexed: true` in a tag schema — they route through the backing B-tree index. Multiple operators on one field AND together (e.g. `{gt: 5, lt: 10}`). `in`/`not_in` take arrays; `exists` takes a boolean.",
@@ -322,13 +341,18 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             required: ["note_id"],
             description: "Scope results to notes within N hops of an anchor note",
           },
-          sort: { type: "string", enum: ["asc", "desc"], description: "Sort by created_at" },
+          sort: {
+            type: "string",
+            enum: ["asc", "desc"],
+            description:
+              'Sort by created_at. Under a structured query this is the only ordering (default "asc"). Under `search` (vault#551): omit for FTS5 relevance ranking (default, unchanged) — pass "asc"/"desc" to EXPLICITLY switch to created_at ordering instead of relevance.',
+          },
           limit: { type: "number", description: "Max results (default 50)" },
           offset: { type: "number", description: "Pagination offset (default 0)" },
           cursor: {
             type: "string",
             description:
-              "Opaque cursor for 'since last checked' agent loops (vault#313). First call: omit. The response will include `next_cursor` — pass it on the subsequent call to receive only notes created or updated since the prior page. The cursor binds to the query's filters (tag, path, metadata, etc.); changing them between calls returns a structured `cursor_query_mismatch` error. Pagination via cursor orders results by `updated_at ASC` and is mutually exclusive with `order_by` and `sort: \"desc\"`. The response shape switches to `{notes, next_cursor}` when this parameter is present.",
+              "Opaque cursor for 'since last checked' agent loops (vault#313). Bootstrap flow (vault#550): FIRST call passes `cursor: \"\"` (empty string) — this opts into cursor mode with no watermark yet and the response comes back as `{notes, next_cursor}`. Persist `next_cursor` and pass it back verbatim as `cursor` on every SUBSEQUENT call to receive only notes created or updated since the prior page. Omitting `cursor` entirely (not passing the key at all) is a DIFFERENT thing — a plain one-shot list with no cursor envelope and no way to resume; use that when you don't want pagination at all. The cursor binds to the query's filters (tag, path, metadata, etc.); changing them between calls returns a structured `cursor_query_mismatch` error, and a malformed/expired cursor returns `cursor_invalid` naming the bootstrap flow again. Pagination via cursor orders results by `updated_at ASC` and is mutually exclusive with `order_by` and `sort: \"desc\"`.",
           },
           include_content: { type: "boolean", description: "Include note content (default: true for single, false for list)" },
           content_offset: {
@@ -466,7 +490,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         // neighborhood every call to be cursor-stable; we punt for now).
         // Both surface as INVALID_QUERY rather than silently returning
         // wrong rows.
-        const cursorMode = typeof params.cursor === "string" && params.cursor.length > 0;
+        // Presence, not truthiness (vault#550 bootstrap fix) — `cursor: ""`
+        // is the bootstrap call ("I want to paginate, no watermark yet") and
+        // must still engage cursor mode. Before this fix `"".length > 0` was
+        // false, so the very first call could never obtain a `next_cursor`.
+        const cursorMode = typeof params.cursor === "string";
         if (cursorMode && params.search) {
           throw new QueryError(
             `cursor is incompatible with full-text search — FTS has its own ordering. Use date_filter on updated_at for since-last-checked search.`,
@@ -492,24 +520,85 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           expand = params.expand as TagExpandMode;
         }
 
+        // `search_mode` (vault#551) — validate loudly (same policy as
+        // `expand` above) so a typo'd value doesn't silently fall back to
+        // the default. Resolved here (before the search/structured branch)
+        // because BOTH branches need to know whether it was passed: the
+        // search branch to select escaping behavior, the structured branch
+        // to warn that it's being ignored.
+        let searchMode: SearchMode | undefined;
+        if (params.search_mode !== undefined && params.search_mode !== null) {
+          if (typeof params.search_mode !== "string" || !isValidSearchMode(params.search_mode)) {
+            throw new QueryError(
+              `invalid \`search_mode\` value ${JSON.stringify(params.search_mode)} — must be one of ${SEARCH_MODES.map((m) => `"${m}"`).join(", ")}. Omit for the default ("literal").`,
+              "INVALID_QUERY",
+              {
+                error_type: "invalid_query",
+                field: "search_mode",
+                got: params.search_mode,
+                hint: `pass "literal" or "advanced", or omit for the default ("literal")`,
+              },
+            );
+          }
+          searchMode = params.search_mode;
+        }
+
         // --- Full-text search ---
         let results: Note[];
         let nextCursor: string | null = null;
+        // Warnings channel (vault#550). `search=` warnings (`empty_search`,
+        // `ignored_param` for a stray `search_mode`) joined the channel at
+        // #551 — the rest (`unknown_tag`) stays structured-query only.
+        // Scope-unaware by design (see `core/src/query-warnings.ts` doc
+        // comment) — a tag-scoped MCP session gets these stripped by the
+        // `applyTagScopeWrappers` query-notes wrapper in `src/mcp-tools.ts`
+        // before the result reaches the caller, so an out-of-scope tag name
+        // never leaks via `did_you_mean`.
+        let queryWarnings: QueryWarning[] = [];
         if (params.search) {
           // Normalize tag param
           const tags = normalizeTags(params.tag);
-          // Route through `store.searchNotes` (not `noteOps.searchNotes`) so
-          // tag-hierarchy expansion fires for MCP callers the same as for
-          // HTTP REST callers — `tag: "manual"` matches descendants declared
-          // via `_tags/*` config notes. Mirrors the structured-query fix
-          // from #214; same class of bypass bug (tracked as #227).
-          results = await store.searchNotes(params.search as string, {
-            tags,
-            limit: (params.limit as number) ?? 50,
-            expand,
-          });
+          const mode: SearchMode = searchMode ?? "literal";
+          // "Only whitespace/quotes" (vault#551 edge case): short-circuit
+          // BEFORE ever calling FTS5 — an empty/all-punctuation phrase can
+          // be a syntax error (or a meaningless always-empty query)
+          // depending on exactly how it degenerates, so this is checked
+          // here rather than left to the DB layer to (maybe) reject.
+          if (mode === "literal" && buildLiteralSearchQuery(params.search as string).isEmpty) {
+            results = [];
+            queryWarnings.push(emptySearchWarning());
+          } else {
+            // Route through `store.searchNotes` (not `noteOps.searchNotes`) so
+            // tag-hierarchy expansion fires for MCP callers the same as for
+            // HTTP REST callers — `tag: "manual"` matches descendants declared
+            // via `_tags/*` config notes. Mirrors the structured-query fix
+            // from #214; same class of bypass bug (tracked as #227). A
+            // malformed advanced-mode query throws here (structured
+            // `invalid_search_syntax`, vault#551) — uncaught on purpose, it
+            // propagates to `src/mcp-http.ts`, which maps it to a JSON-RPC
+            // error the same way it maps `invalid_query`.
+            results = await store.searchNotes(params.search as string, {
+              tags,
+              limit: (params.limit as number) ?? 50,
+              expand,
+              mode,
+              sort: params.sort as "asc" | "desc" | undefined,
+            });
+          }
         } else {
           // --- Structured query ---
+          // `search_mode` only shapes how `search` text becomes an FTS5
+          // query — passing it without `search` is almost always a mistake
+          // (meant to pass `search` too), so flag it rather than silently
+          // doing nothing with it.
+          if (searchMode !== undefined) {
+            queryWarnings.push(
+              ignoredParamWarning(
+                "search_mode",
+                "no `search` was provided — search_mode only affects full-text search query parsing",
+              ),
+            );
+          }
           const tags = normalizeTags(params.tag);
           // Accept canonical `exclude_tags` plus camelCase / singular aliases.
           // LLM callers frequently pick the wrong name (training-data drift
@@ -556,6 +645,12 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             offset: params.offset as number | undefined,
             cursor: cursorMode ? (params.cursor as string) : undefined,
           };
+          // Concatenate (not overwrite) — `queryWarnings` may already carry
+          // the `ignored_param` warning for a stray `search_mode` pushed
+          // above (vault#551).
+          queryWarnings = queryWarnings.concat(
+            collectUnknownTagWarnings(db, queryOpts.tags, queryOpts.expand, store.getTagHierarchy()),
+          );
           if (cursorMode) {
             const page = await store.queryNotesPaged(queryOpts);
             results = page.notes;
@@ -637,13 +732,29 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
           // Cursor mode wraps the list in `{notes, next_cursor}` so callers can
           // chain calls without tracking a watermark client-side. Legacy
-          // callers (no `cursor` param) still get the flat array.
-          if (cursorMode) return { notes: enrichedOut, next_cursor: nextCursor };
-          return enrichedOut;
+          // callers (no `cursor` param, no warnings) still get the flat
+          // array (vault#550 — warnings channel is additive, never forces
+          // the envelope on its own outside cursor mode... except when
+          // there ARE warnings, in which case the envelope is the only way
+          // to attach them).
+          if (cursorMode) {
+            return {
+              notes: enrichedOut,
+              next_cursor: nextCursor,
+              ...(queryWarnings.length > 0 ? { warnings: queryWarnings } : {}),
+            };
+          }
+          return queryWarnings.length > 0 ? { notes: enrichedOut, warnings: queryWarnings } : enrichedOut;
         }
 
-        if (cursorMode) return { notes: output, next_cursor: nextCursor };
-        return output;
+        if (cursorMode) {
+          return {
+            notes: output,
+            next_cursor: nextCursor,
+            ...(queryWarnings.length > 0 ? { warnings: queryWarnings } : {}),
+          };
+        }
+        return queryWarnings.length > 0 ? { notes: output, warnings: queryWarnings } : output;
       },
     },
 
@@ -1353,7 +1464,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "list-tags",
       requiredVerb: "read",
-      description: `List tags with usage counts. Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps). Pass \`include_schema: true\` to include the full record for every tag.`,
+      description: `List tags with usage counts. Each row carries \`count\` (notes carrying the EXACT tag) and \`expanded_count\` (vault#550 — distinct notes matching the tag OR any transitive descendant under the default subtypes expansion; use this to see a parent tag's true rollup when its notes are actually tagged with a more specific child). Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps) — errors with \`error_type: "tag_not_found"\` (plus a \`did_you_mean\` hint when a close match exists) if the tag has no identity row and no notes. Pass \`include_schema: true\` to include the full record for every tag.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -1368,9 +1479,30 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           const allTags = noteOps.listTags(db);
           const found = allTags.find((t) => t.name === singleTag);
           const record = tagSchemaOps.getTagRecord(db, singleTag);
+          // vault#550 — a tag with no identity row AND no note carrying it
+          // isn't a legitimate (if empty) tag, it's a typo or a tag from a
+          // different vault. Return a structured miss instead of a
+          // synthesized all-null 200. `did_you_mean` searches the full
+          // vault-wide tag catalog — core is scope-unaware by architecture.
+          // Tag-scope enforcement lives in the server layer's list-tags
+          // wrapper (src/mcp-tools.ts:applyTagScopeWrappers): a scoped
+          // session's out-of-scope `tag` param short-circuits to
+          // tag_not_found BEFORE this executes, and an in-scope miss gets
+          // its `did_you_mean` dropped unless the suggestion is also
+          // in-scope.
+          if (!found && !record) {
+            const suggestion = suggestSimilarTag(allTags.map((t) => t.name), singleTag);
+            return {
+              error: "Tag not found",
+              error_type: "tag_not_found",
+              tag: singleTag,
+              ...(suggestion ? { did_you_mean: suggestion } : {}),
+            };
+          }
           return {
             name: singleTag,
             count: found?.count ?? 0,
+            expanded_count: found?.expanded_count ?? 0,
             description: record?.description ?? null,
             fields: record?.fields ?? null,
             relationships: record?.relationships ?? null,
@@ -1589,7 +1721,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "find-path",
       requiredVerb: "read",
-      description: "Find the shortest path between two notes in the link graph. Accepts IDs or paths. Returns the chain of note IDs and relationships, or null if no path exists.",
+      description: "Find the shortest path between two notes in the link graph. Accepts IDs or paths. Returns null if no path exists, else `{path, relationships, nodes, edges}`: `path` (note IDs, source→target) and `relationships` (relationships[i] connects path[i] to path[i+1]) are the original id-only shape; `nodes` (vault#550, additive) hydrates each id in `path` with the note's own `path` field — `[{id, path}]` in the same order; `edges` (additive) is the self-contained hop list — `[{source, target, relationship, sourcePath, targetPath}]` — for rendering the chain without cross-referencing `nodes`.",
       inputSchema: {
         type: "object",
         properties: {