@openparachute/vault 0.3.3 → 0.4.0

package/core/src/mcp.ts

@@ -1,11 +1,12 @@
 import { Database } from "bun:sqlite";
 import type { Store, Note } from "./types.js";
 import * as noteOps from "./notes.js";
-import { filterMetadata } from "./notes.js";
+import { filterMetadata, MAX_BATCH_SIZE } from "./notes.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
 import * as indexedFieldOps from "./indexed-fields.js";
+import { MAPPING_KINDS, type SchemaMappingKind, type NoteSchemaField } from "./note-schemas.js";
 import {
   expandContent,
   DEFAULT_EXPAND_DEPTH,
@@ -68,7 +69,7 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Generate the 9 consolidated MCP tools for a vault.
+ * Generate the 10 consolidated MCP tools for a vault.
  */
 export function generateMcpTools(store: Store): McpToolDef[] {
   const db: Database = (store as any).db;
@@ -102,7 +103,31 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             description: "Filter by tag(s)",
           },
           tag_match: { type: "string", enum: ["any", "all"], description: "How to match multiple tags: 'any' (OR, default) or 'all' (AND)" },
-          exclude_tags: { type: "array", items: { type: "string" }, description: "Exclude notes with these tags" },
+          exclude_tags: {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } },
+            ],
+            description: "Exclude notes with these tag(s). Accepts a single tag or an array. Aliases `excludeTags` and `exclude_tag` are also accepted. If multiple alias forms are provided, `exclude_tags` takes precedence (then `excludeTags`, then `exclude_tag`).",
+          },
+          // The runtime alias-fallback chain accepts these too. Declared
+          // here so schema-introspecting clients (Claude, MCP clients
+          // that surface tool schemas) see them as valid inputs rather
+          // than thinking the canonical is the only option.
+          excludeTags: {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } },
+            ],
+            description: "Alias for `exclude_tags` (camelCase). Same shape and semantics — pick whichever is more natural for your client.",
+          },
+          exclude_tag: {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } },
+            ],
+            description: "Alias for `exclude_tags` (singular). Same shape and semantics — accepts a single tag or an array.",
+          },
           has_tags: { type: "boolean", description: "Presence filter: true = only notes with at least one tag; false = only untagged notes. Ignored when `tag` is set." },
           has_links: { type: "boolean", description: "Presence filter: true = only notes with at least one inbound or outbound link; false = only orphaned notes (no links in either direction)." },
           path: { type: "string", description: "Exact path match (case-insensitive)" },
@@ -113,8 +138,17 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             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.",
           },
           order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. Direction is taken from `sort` (default 'asc'); `created_at` is appended as a stable tiebreaker." },
-          date_from: { type: "string", description: "Start date (ISO, inclusive)" },
-          date_to: { type: "string", description: "End date (ISO, exclusive)" },
+          date_from: { type: "string", description: "Start date (ISO, inclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', from }`." },
+          date_to: { type: "string", description: "End date (ISO, exclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', to }`." },
+          date_filter: {
+            type: "object",
+            properties: {
+              field: { type: "string", description: "Field to filter on. Defaults to `created_at` (vault ingestion time). Any other field must be declared `indexed: true` in a tag schema — same contract as metadata operator queries and `order_by`." },
+              from: { type: "string", description: "Inclusive lower bound (ISO date)." },
+              to: { type: "string", description: "Exclusive upper bound (ISO date)." },
+            },
+            description: "Generalized date-range filter. Use this when the date that matters is the *content* date (e.g. an email's received date, a meeting's scheduled date), not the vault ingestion time — set `field` to the indexed metadata field that holds it. Mutually exclusive with the top-level `date_from` / `date_to` shorthand.",
+          },
           near: {
             type: "object",
             properties: {
@@ -198,24 +232,49 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         if (params.search) {
           // Normalize tag param
           const tags = normalizeTags(params.tag);
-          results = noteOps.searchNotes(db, params.search as string, {
+          // 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,
           });
         } else {
           // --- Structured query ---
           const tags = normalizeTags(params.tag);
-          results = noteOps.queryNotes(db, {
+          // Accept canonical `exclude_tags` plus camelCase / singular aliases.
+          // LLM callers frequently pick the wrong name (training-data drift
+          // toward camelCase across MCP tools) and the JSON-RPC layer drops
+          // unknown keys silently; aliasing here closes the silent-no-op gap.
+          const excludeTagsRaw = params.exclude_tags ?? params.excludeTags ?? params.exclude_tag;
+          const excludeTags = normalizeTags(excludeTagsRaw);
+          // Route through `store.queryNotes` (not `noteOps.queryNotes`) so
+          // tag-hierarchy expansion fires for MCP callers the same as for
+          // HTTP REST callers — `tag: "manual"` matches descendants declared
+          // via `_tags/*` config notes. The previous direct-noteOps call
+          // bypassed the wrapper and silently dropped hierarchy expansion.
+          results = await store.queryNotes({
             tags,
             tagMatch: (params.tag_match as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
-            excludeTags: params.exclude_tags as string[] | undefined,
+            excludeTags,
             hasTags: params.has_tags as boolean | undefined,
             hasLinks: params.has_links as boolean | undefined,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
+            // Push the near-scope into the SQL WHERE so that LIMIT and ORDER
+            // BY apply to the neighborhood. Without this, queryNotes would
+            // fetch the first `limit` notes by created_at and then post-
+            // filter to the few in-scope ones — which silently empties the
+            // result whenever the neighborhood lies outside that prefix.
+            ids: nearScope ? [...nearScope] : undefined,
             metadata: params.metadata as Record<string, unknown> | undefined,
             dateFrom: params.date_from as string | undefined,
             dateTo: params.date_to as string | undefined,
+            dateFilter: params.date_filter as
+              | { field?: string; from?: string; to?: string }
+              | undefined,
             sort: params.sort as "asc" | "desc" | undefined,
             orderBy: params.order_by as string | undefined,
             limit: (params.limit as number) ?? 50,
@@ -223,8 +282,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           });
         }
 
-        // --- Apply near-scope filter ---
-        if (nearScope) {
+        // For full-text search the post-filter is still the right shape — FTS
+        // owns its own ranked LIMIT and we just narrow to the neighborhood
+        // afterwards. Structured queries already pushed `ids` into SQL above.
+        if (nearScope && params.search) {
           results = results.filter((n) => nearScope!.has(n.id));
         }
 
@@ -315,26 +376,65 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         const batch = params.notes as any[] | undefined;
         const items = batch ?? [params];
 
+        if (items.length > MAX_BATCH_SIZE) {
+          throw new BatchTooLargeError(items.length);
+        }
+
+        // Empty-note pre-validation (#213): make mixed batches atomic for
+        // the empty-note case. The Store will throw EmptyNoteError on the
+        // empty entry, but in a sequential batch loop the prefix would have
+        // already committed before we hit it. Pre-walk so the whole call
+        // either creates everything or nothing. The error carries
+        // `item_index` so MCP callers with multi-item batches can pinpoint
+        // the bad entry — parity with the HTTP route's response shape.
+        // TODO: tighten batch input type — `items[i] as any` mirrors the
+        // top-of-call cast at `params.notes as any[]`. A typed McpCreateNoteInput
+        // would let us drop both casts.
+        for (let i = 0; i < items.length; i++) {
+          const item = items[i] as any;
+          const content = ((item?.content as string | undefined) ?? "").toString();
+          const rawPath = item?.path;
+          const pathEmpty = rawPath === undefined || rawPath === null
+            || (typeof rawPath === "string" && rawPath.trim() === "");
+          if (!content.trim() && pathEmpty) {
+            throw new noteOps.EmptyNoteError(null, batch ? i : null);
+          }
+        }
+
         const created: Note[] = [];
-        for (const item of items) {
-          const note = await store.createNote(item.content as string ?? "", {
-            path: item.path as string | undefined,
-            tags: item.tags as string[] | undefined,
-            metadata: item.metadata as Record<string, unknown> | undefined,
-            created_at: item.created_at as string | undefined,
-          });
+        // Wrap multi-item batches in a SQLite transaction so a mid-batch
+        // failure rolls back every prior insert — see #236. The pre-walk
+        // above catches empty-note cases; this guards anything thrown from
+        // store.createNote / createLink (path conflict, etc.). Single-item
+        // calls skip the wrap to avoid colliding with concurrent callers
+        // on the shared bun:sqlite connection.
+        const batched = items.length > 1;
+        if (batched) db.exec("BEGIN");
+        try {
+          for (const item of items) {
+            const note = await store.createNote(item.content as string ?? "", {
+              path: item.path as string | undefined,
+              tags: item.tags as string[] | undefined,
+              metadata: item.metadata as Record<string, unknown> | undefined,
+              created_at: item.created_at as string | undefined,
+            });
 
-          // Create explicit links (not wikilinks — those are automatic)
-          if (item.links) {
-            for (const link of item.links as { target: string; relationship: string }[]) {
-              const target = resolveNote(db, link.target);
-              if (target) {
-                await store.createLink(note.id, target.id, link.relationship);
+            // Create explicit links (not wikilinks — those are automatic)
+            if (item.links) {
+              for (const link of item.links as { target: string; relationship: string }[]) {
+                const target = resolveNote(db, link.target);
+                if (target) {
+                  await store.createLink(note.id, target.id, link.relationship);
+                }
               }
             }
-          }
 
-          created.push(noteOps.getNote(db, note.id) ?? note);
+            created.push(noteOps.getNote(db, note.id) ?? note);
+          }
+          if (batched) db.exec("COMMIT");
+        } catch (e) {
+          if (batched) db.exec("ROLLBACK");
+          throw e;
         }
 
         // Apply tag schema effects
@@ -344,7 +444,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
         }
 
-        return batch ? created : created[0];
+        // Re-read after schema-default population so the response reflects the
+        // final on-disk state, then attach `validation_status` from any
+        // `_schemas/*` config notes that match this note's path or tags.
+        const final = created.map((n) => attachValidationStatus(store, db, n));
+        return batch ? final : final[0];
       },
     },
 
@@ -355,20 +459,35 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       name: "update-note",
       description: `Update one or more notes. Accepts ID or path. Supports content, path, metadata updates plus tag and link mutations.
 
+- Three content-modification modes (mutually exclusive):
+  - \`content\` — full replace.
+  - \`append\` / \`prepend\` — atomic concatenation at the SQL layer. Multiple agents appending to the same note never overwrite each other. No separator is added; include trailing/leading whitespace yourself if needed. May be combined with each other.
+  - \`content_edit: { old_text, new_text }\` — surgical find-and-replace. \`old_text\` must occur exactly once; zero or multiple matches return an error. Add surrounding context to disambiguate.
 - \`tags: { add: ["x"], remove: ["y"] }\` — add/remove tags
 - \`links: { add: [{ target, relationship }], remove: [{ target, relationship }] }\` — add/remove links
 - When removing a wikilink-type link, \`[[brackets]]\` are also removed from content.
 - For batch: pass a \`notes\` array, each with an \`id\` field.
-- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally.`,
+- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design).`,
       inputSchema: {
         type: "object",
         properties: {
           id: { type: "string", description: "Note ID or path" },
-          content: { type: "string", description: "New content" },
+          content: { type: "string", description: "New content (full replace). Mutually exclusive with `append`/`prepend` and `content_edit`." },
+          append: { type: "string", description: "Text to append to the end of the note. Atomic at the SQL layer — concurrent appends are safe. Mutually exclusive with `content` and `content_edit`. No precondition required." },
+          prepend: { type: "string", description: "Text to prepend to the start of the note. Atomic at the SQL layer. Mutually exclusive with `content` and `content_edit`. May combine with `append`. No precondition required." },
+          content_edit: {
+            type: "object",
+            properties: {
+              old_text: { type: "string", description: "Exact text to find. Must match exactly once in the note's current content." },
+              new_text: { type: "string", description: "Replacement text." },
+            },
+            required: ["old_text", "new_text"],
+            description: "Find-and-replace one occurrence. Errors if `old_text` is not found or matches multiple locations. Mutually exclusive with `content` and `append`/`prepend`.",
+          },
           path: { type: "string", description: "New path" },
           metadata: { type: "object", description: "Metadata to merge (keys are merged, not replaced wholesale)" },
           created_at: { type: "string", description: "New created_at timestamp" },
-          if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since. Required unless `force: true` is set." },
+          if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since. Required unless `force: true` is set or the call is `append`/`prepend`-only." },
           force: { type: "boolean", description: "Override the required `if_updated_at` check and run the update unconditionally. Use only for bulk migrations or scripted writes where concurrency is known-safe." },
           tags: {
             type: "object",
@@ -414,10 +533,20 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               properties: {
                 id: { type: "string" },
                 content: { type: "string" },
+                append: { type: "string" },
+                prepend: { type: "string" },
+                content_edit: {
+                  type: "object",
+                  properties: {
+                    old_text: { type: "string" },
+                    new_text: { type: "string" },
+                  },
+                  required: ["old_text", "new_text"],
+                },
                 path: { type: "string" },
                 metadata: { type: "object" },
                 created_at: { type: "string" },
-                if_updated_at: { type: "string", description: "Optimistic concurrency check for this item; rejects with a conflict error if the note has been modified since. Required unless `force: true` is set on this item." },
+                if_updated_at: { type: "string", description: "Optimistic concurrency check for this item; rejects with a conflict error if the note has been modified since. Required unless `force: true` is set on this item or the item is `append`/`prepend`-only." },
                 force: { type: "boolean", description: "Override the required `if_updated_at` check for this item." },
                 tags: { type: "object" },
                 links: { type: "object" },
@@ -432,24 +561,91 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         const batch = params.notes as any[] | undefined;
         const items = batch ?? [params];
 
+        if (items.length > MAX_BATCH_SIZE) {
+          throw new BatchTooLargeError(items.length);
+        }
+
         const updated: Note[] = [];
+        // Wrap multi-item batches in a SQLite transaction so any mid-batch
+        // failure (precondition error, content_edit miss, ConflictError, …)
+        // rolls back every prior mutation in the batch — see #236.
+        // Single-item calls skip the wrap so concurrent callers don't
+        // collide on the shared bun:sqlite connection.
+        const batched = items.length > 1;
+        if (batched) db.exec("BEGIN");
+        try {
         for (const item of items) {
           const note = requireNote(db, item.id as string);
 
+          // --- Validate mutual exclusion of content modes ---
+          const hasContent = item.content !== undefined;
+          const hasAppendPrepend = item.append !== undefined || item.prepend !== undefined;
+          const hasContentEdit = item.content_edit !== undefined;
+          const contentModes = (hasContent ? 1 : 0) + (hasAppendPrepend ? 1 : 0) + (hasContentEdit ? 1 : 0);
+          if (contentModes > 1) {
+            throw new Error(
+              `update-note: \`content\`, \`append\`/\`prepend\`, and \`content_edit\` are mutually exclusive — pick one mode of content update for note "${note.id}".`,
+            );
+          }
+
           // --- Safety-by-default: refuse mutations without a precondition ---
           // The caller must either echo the note's last-seen `updated_at`
           // (`if_updated_at`) so the conditional UPDATE can catch lost
           // writes, or explicitly opt out with `force: true`. This runs
           // *before* any DB writes so a rejection leaves the note untouched.
-          if (item.if_updated_at === undefined && item.force !== true) {
+          //
+          // Append/prepend-only updates are exempt: they're SQL-atomic
+          // concatenations that can't lose data on a stale read, so the
+          // precondition would be ceremony for no benefit. Tag and link
+          // mutations are *not* exempt — they're idempotent set-ops at
+          // the SQL layer but still represent a non-content change the
+          // caller should have observed before re-asserting (#201).
+          const isAppendOnly = hasAppendPrepend
+            && !hasContent
+            && !hasContentEdit
+            && item.path === undefined
+            && item.metadata === undefined
+            && item.created_at === undefined
+            && item.tags === undefined
+            && item.links === undefined;
+          if (!isAppendOnly && item.if_updated_at === undefined && item.force !== true) {
             throw new PreconditionRequiredError(note.id, note.path ?? null);
           }
 
+          // --- Resolve content_edit into a full content string ---
+          // We do the find-and-replace at the JS level (read note.content,
+          // validate occurrence count, replace). The race window between
+          // this read and the UPDATE is closed by `if_updated_at` for
+          // strict callers; without it, content_edit is fail-closed —
+          // a stale read where someone else removed `old_text` produces
+          // a "not found" error instead of silently overwriting.
+          let contentOverride = item.content as string | undefined;
+          if (hasContentEdit) {
+            const ce = item.content_edit as { old_text: string; new_text: string };
+            if (typeof ce?.old_text !== "string" || typeof ce?.new_text !== "string") {
+              throw new Error(
+                "update-note: `content_edit` requires { old_text: string, new_text: string }.",
+              );
+            }
+            const idx = note.content.indexOf(ce.old_text);
+            if (idx < 0) {
+              throw new Error(
+                `update-note content_edit: \`old_text\` not found in note "${note.id}". The note may have been edited — re-read and retry.`,
+              );
+            }
+            const second = note.content.indexOf(ce.old_text, idx + 1);
+            if (second >= 0) {
+              throw new Error(
+                `update-note content_edit: \`old_text\` matches multiple times in note "${note.id}" — must match exactly once. Add surrounding context to disambiguate.`,
+              );
+            }
+            contentOverride = note.content.slice(0, idx) + ce.new_text + note.content.slice(idx + ce.old_text.length);
+          }
+
           // --- Plan bracket cleanup for wikilink removals (no DB writes yet) ---
           // We compute the cleaned content so we can do the core UPDATE first
           // (with if_updated_at atomically) before any link deletions. If the
           // UPDATE fails on a conflict, nothing has been mutated.
-          let contentOverride = item.content as string | undefined;
           const linksRemove = (item.links as any)?.remove as { target: string; relationship: string }[] | undefined;
           const resolvedLinksToRemove: { targetId: string; relationship: string }[] = [];
           if (linksRemove) {
@@ -458,7 +654,15 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               if (!target) continue;
               resolvedLinksToRemove.push({ targetId: target.id, relationship: link.relationship });
               if (link.relationship === "wikilink" && target.path) {
-                const currentContent = contentOverride ?? note.content;
+                // Wikilink-removal bracket cleanup operates on the prospective
+                // *full* content. Coexists with content_edit; would fight
+                // append/prepend (which leave existing content untouched at
+                // the JS layer), so we pre-materialize the would-be content
+                // for those callers and switch to a `content`-style update.
+                const currentContent = contentOverride
+                  ?? (hasAppendPrepend
+                    ? (item.prepend as string ?? "") + note.content + (item.append as string ?? "")
+                    : note.content);
                 const cleaned = removeWikilinkBrackets(currentContent, target.path);
                 if (cleaned !== currentContent) {
                   contentOverride = cleaned;
@@ -469,7 +673,14 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
           // --- Core update (content, path, metadata, created_at + concurrency check) ---
           const updates: any = {};
-          if (contentOverride !== undefined) updates.content = contentOverride;
+          if (contentOverride !== undefined) {
+            updates.content = contentOverride;
+          } else if (hasAppendPrepend) {
+            // No content_edit and no wikilink-removal pre-materialization —
+            // route the append/prepend down to the SQL-atomic path.
+            if (item.append !== undefined) updates.append = item.append;
+            if (item.prepend !== undefined) updates.prepend = item.prepend;
+          }
           if (item.path !== undefined) updates.path = item.path;
           if (item.metadata !== undefined) {
             // Merge metadata (don't replace wholesale)
@@ -519,8 +730,14 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           // Re-read for final state
           updated.push(noteOps.getNote(db, note.id) ?? result);
         }
+          if (batched) db.exec("COMMIT");
+        } catch (e) {
+          if (batched) db.exec("ROLLBACK");
+          throw e;
+        }
 
-        return batch ? updated : updated[0];
+        const final = updated.map((n) => attachValidationStatus(store, db, n));
+        return batch ? final : final[0];
       },
     },
 
@@ -549,39 +766,50 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "list-tags",
-      description: `List tags with usage counts. Pass \`tag\` to get a single tag's details including its schema (description + fields). Pass \`include_schema: true\` to include schemas for all tags.`,
+      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.`,
       inputSchema: {
         type: "object",
         properties: {
           tag: { type: "string", description: "Get details for a single tag" },
-          include_schema: { type: "boolean", description: "Include schema (description + fields) for each tag (default: false)" },
+          include_schema: { type: "boolean", description: "Include full tag record (description, fields, relationships, parent_names, timestamps) for each tag (default: false)" },
         },
       },
       execute: (params) => {
         const singleTag = params.tag as string | undefined;
 
         if (singleTag) {
-          // Single tag detail
           const allTags = noteOps.listTags(db);
           const found = allTags.find((t) => t.name === singleTag);
-          const schema = tagSchemaOps.getTagSchema(db, singleTag);
+          const record = tagSchemaOps.getTagRecord(db, singleTag);
           return {
             name: singleTag,
             count: found?.count ?? 0,
-            description: schema?.description ?? null,
-            fields: schema?.fields ?? null,
+            description: record?.description ?? null,
+            fields: record?.fields ?? null,
+            relationships: record?.relationships ?? null,
+            parent_names: record?.parent_names ?? null,
+            created_at: record?.created_at ?? null,
+            updated_at: record?.updated_at ?? null,
           };
         }
 
-        // All tags
         const tags = noteOps.listTags(db);
         if (params.include_schema) {
-          const schemas = tagSchemaOps.getTagSchemaMap(db);
-          return tags.map((t) => ({
-            ...t,
-            description: schemas[t.name]?.description ?? null,
-            fields: schemas[t.name]?.fields ?? null,
-          }));
+          const records = new Map(
+            tagSchemaOps.listTagRecords(db).map((r) => [r.tag, r] as const),
+          );
+          return tags.map((t) => {
+            const r = records.get(t.name);
+            return {
+              ...t,
+              description: r?.description ?? null,
+              fields: r?.fields ?? null,
+              relationships: r?.relationships ?? null,
+              parent_names: r?.parent_names ?? null,
+              created_at: r?.created_at ?? null,
+              updated_at: r?.updated_at ?? null,
+            };
+          });
         }
         return tags;
       },
@@ -592,7 +820,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "update-tag",
-      description: "Create or update a tag's description and schema fields. If the tag doesn't exist, it's created. Fields are merged — new keys are added, existing keys are replaced.",
+      description: "Create or update a tag's identity row: description, indexed-field schemas, typed-link relationships, and hierarchy parents. If the tag doesn't exist, it's created. Fields are merged (new keys added, existing keys replaced); relationships and parent_names are replaced wholesale when provided. Pass null for fields/relationships/parent_names to clear that column. See parachute-patterns/patterns/tag-data-model.md.",
       inputSchema: {
         type: "object",
         properties: {
@@ -612,12 +840,32 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               required: ["type"],
             },
           },
+          relationships: {
+            type: "object",
+            description: 'Typed-link declarations. Each value declares { target_tag, cardinality, description? }. Cardinality is one of: one | optional | many | many-required. Phase 1: informational, not enforced at write time. E.g., { "lives_in": { "target_tag": "place", "cardinality": "one" } }',
+            additionalProperties: {
+              type: "object",
+              properties: {
+                target_tag: { type: "string", description: "Tag the relationship points at" },
+                cardinality: { type: "string", enum: ["one", "optional", "many", "many-required"], description: "How many targets this relationship may have" },
+                description: { type: "string", description: "Why this relationship exists; surfaced to AI clients" },
+              },
+              required: ["target_tag", "cardinality"],
+            },
+          },
+          parent_names: {
+            type: "array",
+            items: { type: "string" },
+            description: "Tag names this tag is a child of, for the query-time hierarchy. Replaces any prior parent list. Pass [] (empty array) or null to clear. E.g., parent_names: [\"manual\", \"note\"] makes this tag a descendant of both.",
+          },
         },
         required: ["tag"],
       },
-      execute: (params) => {
+      execute: async (params) => {
         const tag = params.tag as string;
-        const existing = tagSchemaOps.getTagSchema(db, tag);
+        const existing = tagSchemaOps.getTagRecord(db, tag);
+
+        // ---- fields: shallow-merge into existing (preserves prior keys).
         const incomingFields = (params.fields as Record<string, TagFieldSchema> | undefined) ?? {};
         const mergedFields: Record<string, TagFieldSchema> = {
           ...(existing?.fields ?? {}),
@@ -626,7 +874,6 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
         // Validate cross-tag consistency on fields being (re)declared in this
         // call. `type` and `indexed` are global — all declarers must agree.
-        // `description` and `enum` are per-tag, so we don't compare them.
         const otherSchemas = tagSchemaOps
           .listTagSchemas(db)
           .filter((s) => s.tag !== tag);
@@ -657,15 +904,47 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
         }
 
-        // Persist the schema first, then reconcile indexing lifecycle. An
-        // error here would leave the on-disk schema untouched, matching
-        // prior behavior.
-        const result = tagSchemaOps.upsertTagSchema(db, tag, {
-          description: (params.description as string | undefined) ?? existing?.description,
-          fields: Object.keys(mergedFields).length > 0 ? mergedFields : undefined,
+        // ---- relationships: replace wholesale when provided. Validate
+        // shape + cardinality vocabulary before persisting so a malformed
+        // payload can't leave the row in an inconsistent state.
+        let relationshipsPatch: Record<string, tagSchemaOps.TagRelationship> | null | undefined;
+        if (params.relationships === null) {
+          relationshipsPatch = null;
+        } else if (params.relationships !== undefined) {
+          relationshipsPatch = tagSchemaOps.validateRelationships(params.relationships);
+        }
+
+        // ---- parent_names: replace wholesale when provided. Empty array
+        // collapses to null (clear) — a tag with `parent_names = []` and
+        // a tag with `parent_names = null` are indistinguishable at the
+        // hierarchy layer.
+        let parentNamesPatch: string[] | null | undefined;
+        if (params.parent_names === null) {
+          parentNamesPatch = null;
+        } else if (params.parent_names !== undefined) {
+          if (!Array.isArray(params.parent_names)) {
+            throw new Error("parent_names must be an array of tag names");
+          }
+          const cleaned = (params.parent_names as unknown[])
+            .filter((p): p is string => typeof p === "string" && p.length > 0);
+          parentNamesPatch = cleaned.length > 0 ? cleaned : null;
+        }
+
+        // ---- Persist via the store wrapper so the hierarchy cache is
+        // invalidated when parent_names is touched.
+        const fieldsPatch = Object.keys(mergedFields).length > 0
+          ? mergedFields
+          : (params.fields !== undefined ? null : undefined);
+        const descriptionPatch =
+          params.description === undefined ? undefined : (params.description as string);
+        const result = await store.upsertTagRecord(tag, {
+          ...(descriptionPatch !== undefined ? { description: descriptionPatch } : {}),
+          ...(fieldsPatch !== undefined ? { fields: fieldsPatch } : {}),
+          ...(relationshipsPatch !== undefined ? { relationships: relationshipsPatch } : {}),
+          ...(parentNamesPatch !== undefined ? { parent_names: parentNamesPatch } : {}),
         });
 
-        // Diff indexed state for this tag: what it indexed before vs. now.
+        // ---- Reconcile indexed-field lifecycle for this tag.
         const priorIndexed = new Set(
           Object.entries(existing?.fields ?? {})
             .filter(([, v]) => v.indexed === true)
@@ -706,9 +985,9 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       },
       execute: async (params) => {
         const tag = params.tag as string;
-        // Release any indexed fields this tag declared before the schema
-        // row disappears. releaseField drops the generated column + index
-        // when the declarer set empties.
+        // Release any indexed fields this tag declared before the row
+        // drops. releaseField drops the generated column + index when the
+        // declarer set empties.
         const schema = tagSchemaOps.getTagSchema(db, tag);
         if (schema?.fields) {
           for (const [fieldName, spec] of Object.entries(schema.fields)) {
@@ -717,12 +996,186 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             }
           }
         }
-        // Delete schema first (FK cascade would handle it, but be explicit)
-        tagSchemaOps.deleteTagSchema(db, tag);
+        // Drop the row outright — description/fields/relationships/parents
+        // travel with it. (No more sidecar table to clear separately.)
         return await store.deleteTag(tag);
       },
     },
 
+    // =====================================================================
+    // 7a. list-note-schemas — read note_schemas + their mappings
+    // =====================================================================
+    {
+      name: "list-note-schemas",
+      description: "List note schemas (description, fields, required, timestamps). Pass `name` to get a single schema with its applied mapping rules. Schemas drive the validation_status warnings surfaced on create-note / update-note.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Get a single schema by name (with its mappings)" },
+          include_mappings: { type: "boolean", description: "When listing all schemas, include each schema's mappings (default: false)" },
+        },
+      },
+      execute: async (params) => {
+        const single = params.name as string | undefined;
+        if (single) {
+          const schema = await store.getNoteSchema(single);
+          if (!schema) return null;
+          const mappings = await store.listSchemaMappings({ schema_name: single });
+          return { ...schema, mappings };
+        }
+        const schemas = await store.listNoteSchemas();
+        if (params.include_mappings) {
+          const allMappings = await store.listSchemaMappings();
+          const byName = new Map<string, typeof allMappings>();
+          for (const m of allMappings) {
+            const list = byName.get(m.schema_name) ?? [];
+            list.push(m);
+            byName.set(m.schema_name, list);
+          }
+          return schemas.map((s) => ({ ...s, mappings: byName.get(s.name) ?? [] }));
+        }
+        return schemas;
+      },
+    },
+
+    // =====================================================================
+    // 7b. update-note-schema — partial-upsert a schema definition
+    // =====================================================================
+    {
+      name: "update-note-schema",
+      description: "Create or update a note schema's definition: description, allowed/expected fields (type + enum + description), and a list of required field names. Auto-creates the schema row if missing. Pass null for description/fields/required to clear that column. Empty `required: []` collapses to null.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Schema name (e.g., 'meeting', 'project')" },
+          description: { type: "string", description: "Human-readable description of what this schema describes" },
+          fields: {
+            type: "object",
+            description: 'Field declarations. E.g., { "title": { "type": "string" }, "status": { "type": "string", "enum": ["active", "done"] } }. Replaces fields wholesale when provided.',
+            additionalProperties: {
+              type: "object",
+              properties: {
+                type: { type: "string", enum: ["string", "number", "boolean", "array", "object"], description: "Expected JS type for this field" },
+                enum: { type: "array", items: { type: "string" }, description: "Allowed values (string fields only)" },
+                description: { type: "string" },
+              },
+            },
+          },
+          required: {
+            type: "array",
+            items: { type: "string" },
+            description: "Field names that must be present on a note matching this schema. Pass [] or null to clear.",
+          },
+        },
+        required: ["name"],
+      },
+      execute: async (params) => {
+        const name = params.name as string;
+        const patch: { description?: string | null; fields?: Record<string, NoteSchemaField> | null; required?: string[] | null } = {};
+        if (params.description === null) patch.description = null;
+        else if (params.description !== undefined) patch.description = params.description as string;
+        if (params.fields === null) patch.fields = null;
+        else if (params.fields !== undefined) patch.fields = params.fields as Record<string, NoteSchemaField>;
+        if (params.required === null) patch.required = null;
+        else if (params.required !== undefined) {
+          if (!Array.isArray(params.required)) {
+            throw new Error("required must be an array of field names");
+          }
+          patch.required = (params.required as unknown[]).filter((x): x is string => typeof x === "string");
+        }
+        return await store.upsertNoteSchema(name, patch);
+      },
+    },
+
+    // =====================================================================
+    // 7c. delete-note-schema — drop schema + cascade its mappings
+    // =====================================================================
+    {
+      name: "delete-note-schema",
+      description: "Delete a note schema. Cascades: any schema_mappings pointing at it are removed via FK ON DELETE CASCADE. Notes themselves are untouched.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Schema name to delete" },
+        },
+        required: ["name"],
+      },
+      execute: async (params) => {
+        const name = params.name as string;
+        const deleted = await store.deleteNoteSchema(name);
+        return { deleted, name };
+      },
+    },
+
+    // =====================================================================
+    // 7d. list-schema-mappings — read mapping rules
+    // =====================================================================
+    {
+      name: "list-schema-mappings",
+      description: "List schema mapping rules (path_prefix or tag → schema_name). Optionally filter by `schema_name` or `match_kind`. Mappings decide which schemas apply to a note at validation time.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          schema_name: { type: "string", description: "Restrict to mappings for this schema" },
+          match_kind: { type: "string", enum: [...MAPPING_KINDS], description: "Restrict to one match kind" },
+        },
+      },
+      execute: async (params) => {
+        const opts: { schema_name?: string; match_kind?: SchemaMappingKind } = {};
+        if (typeof params.schema_name === "string") opts.schema_name = params.schema_name;
+        if (typeof params.match_kind === "string") opts.match_kind = params.match_kind as SchemaMappingKind;
+        return await store.listSchemaMappings(opts);
+      },
+    },
+
+    // =====================================================================
+    // 7e. set-schema-mapping — add a mapping rule
+    // =====================================================================
+    {
+      name: "set-schema-mapping",
+      description: "Bind a schema to a path-prefix or tag. Idempotent — re-setting the same triple is a no-op. The schema must already exist (FK enforced). E.g., {schema_name: 'meeting', match_kind: 'path_prefix', match_value: 'Meetings/'} or {schema_name: 'project', match_kind: 'tag', match_value: 'project'}.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          schema_name: { type: "string", description: "Schema name to bind" },
+          match_kind: { type: "string", enum: [...MAPPING_KINDS], description: "Match by path prefix or by tag" },
+          match_value: { type: "string", description: "The path prefix or tag value to match" },
+        },
+        required: ["schema_name", "match_kind", "match_value"],
+      },
+      execute: async (params) => {
+        const schema_name = params.schema_name as string;
+        const match_kind = params.match_kind as SchemaMappingKind;
+        const match_value = params.match_value as string;
+        await store.setSchemaMapping(schema_name, match_kind, match_value);
+        return { ok: true, schema_name, match_kind, match_value };
+      },
+    },
+
+    // =====================================================================
+    // 7f. delete-schema-mapping — remove a mapping rule
+    // =====================================================================
+    {
+      name: "delete-schema-mapping",
+      description: "Remove a single schema mapping rule. The schema definition is untouched.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          schema_name: { type: "string", description: "Schema name" },
+          match_kind: { type: "string", enum: [...MAPPING_KINDS], description: "Match kind" },
+          match_value: { type: "string", description: "The path prefix or tag value to remove" },
+        },
+        required: ["schema_name", "match_kind", "match_value"],
+      },
+      execute: async (params) => {
+        const schema_name = params.schema_name as string;
+        const match_kind = params.match_kind as SchemaMappingKind;
+        const match_value = params.match_value as string;
+        const deleted = await store.deleteSchemaMapping(schema_name, match_kind, match_value);
+        return { deleted, schema_name, match_kind, match_value };
+      },
+    },
+
     // =====================================================================
     // 8. find-path — BFS between two notes
     // =====================================================================
@@ -748,7 +1201,237 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     },
 
     // =====================================================================
-    // 9. vault-info — get/update vault description + stats
+    // 9. synthesize-notes — gather a coherent neighborhood for a topic
+    // =====================================================================
+    {
+      name: "synthesize-notes",
+      description: `Gather the notes that, taken together, tell the story of a topic — for the agent to read and synthesize.
+
+This is the graph-aware sibling of \`query-notes\`. Where \`query-notes\` returns flat matches, \`synthesize-notes\` pulls a *neighborhood*: anchor + linked notes + search hits + tag distribution + an oldest-first timeline, so the agent can write a coherent narrative without needing 4 separate calls.
+
+**Inputs.** Pass at least one of \`anchor\` (note ID/path to seed graph traversal) or \`query\` (FTS search string). Optionally narrow with \`scope.tags\` / \`scope.path\` (path prefix). \`depth\` (1–3, default 2) caps anchor traversal hops. \`limit\` (default 25, max 50) caps the returned note count.
+
+**What you get back.**
+  - \`notes\`: ranked candidates with \`sources\` (which seed brought them in: \`anchor\` / \`neighbor\` / \`search\`), \`distance\` (hops from anchor), and a short \`snippet\`. Pass \`include_content: true\` to inline the full note body.
+  - \`connections\`: direct links between notes in the result set — the edge structure of the neighborhood.
+  - \`tags\`: tag distribution across the result set (count desc) — quickly shows the conceptual axes.
+  - \`timeline\`: the same notes sorted oldest → newest by \`created_at\` — surfaces evolution of the topic.
+  - \`truncated\`: true when more candidates were available than \`limit\` allowed.
+
+**Synthesis is the caller's job.** The vault returns *what to read*; the agent writes the narrative. No LLM call is made server-side.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          anchor: { type: "string", description: "Note ID or path to seed graph traversal. Optional if `query` is set." },
+          query: { type: "string", description: "Full-text search query. Optional if `anchor` is set." },
+          scope: {
+            type: "object",
+            properties: {
+              tags: { type: "array", items: { type: "string" }, description: "Restrict to notes carrying any of these tags." },
+              path: { type: "string", description: "Restrict to notes whose path starts with this prefix (case-insensitive)." },
+            },
+            description: "Optional filters applied after seeding.",
+          },
+          depth: { type: "number", description: "Max graph hops from anchor (1–3, default 2). Ignored when no anchor is set." },
+          limit: { type: "number", description: "Max notes returned (default 25, hard cap 50)." },
+          include_content: { type: "boolean", description: "Inline full note content (default false — only a short snippet is included)." },
+        },
+      },
+      execute: async (params) => {
+        const anchorParam = typeof params.anchor === "string" && params.anchor.trim() ? params.anchor.trim() : null;
+        const queryParam = typeof params.query === "string" && params.query.trim() ? params.query.trim() : null;
+        if (!anchorParam && !queryParam) {
+          return { error: "synthesize-notes requires at least one of `anchor` or `query`." };
+        }
+
+        const depth = Math.max(1, Math.min((params.depth as number | undefined) ?? 2, 3));
+        const limit = Math.max(1, Math.min((params.limit as number | undefined) ?? 25, 50));
+        const includeContent = params.include_content === true;
+        const scope = (params.scope as { tags?: string[]; path?: string } | undefined) ?? {};
+        const scopeTags = Array.isArray(scope.tags) && scope.tags.length > 0 ? scope.tags : null;
+        const scopePathPrefix = typeof scope.path === "string" && scope.path.trim() ? scope.path.trim().toLowerCase() : null;
+
+        // Pre-resolve the anchor so a bad ID/path errors out cheaply.
+        let anchorNote: Note | null = null;
+        if (anchorParam) {
+          anchorNote = resolveNote(db, anchorParam);
+          if (!anchorNote) {
+            return { error: "Anchor note not found", anchor: anchorParam };
+          }
+        }
+
+        // ----- Candidate seeding -----
+        // Each candidate tracks every signal that surfaced it (so the agent
+        // can see whether a note came from the search hit, the graph, or
+        // both) plus enough provenance to score it.
+        type Candidate = {
+          sources: Set<"anchor" | "neighbor" | "search">;
+          distance: number | null;       // hops from anchor; null if not on the graph
+          ftsRank: number | null;        // 0 = best FTS hit; null if not a search hit
+        };
+        const candidates = new Map<string, Candidate>();
+
+        const upsert = (id: string, patch: Partial<Candidate> & { source: "anchor" | "neighbor" | "search" }): void => {
+          const existing = candidates.get(id);
+          if (!existing) {
+            candidates.set(id, {
+              sources: new Set([patch.source]),
+              distance: patch.distance ?? null,
+              ftsRank: patch.ftsRank ?? null,
+            });
+            return;
+          }
+          existing.sources.add(patch.source);
+          if (patch.distance !== undefined && patch.distance !== null) {
+            existing.distance = existing.distance === null ? patch.distance : Math.min(existing.distance, patch.distance);
+          }
+          if (patch.ftsRank !== undefined && patch.ftsRank !== null) {
+            existing.ftsRank = existing.ftsRank === null ? patch.ftsRank : Math.min(existing.ftsRank, patch.ftsRank);
+          }
+        };
+
+        if (anchorNote) {
+          upsert(anchorNote.id, { source: "anchor", distance: 0 });
+          const traversed = linkOps.traverseLinks(db, anchorNote.id, { max_depth: depth });
+          for (const t of traversed) upsert(t.noteId, { source: "neighbor", distance: t.depth });
+        }
+
+        if (queryParam) {
+          // Cap the FTS pull at 2× limit so the post-scope filter still leaves
+          // enough headroom to fill the result set with real hits.
+          // Direct noteOps.searchNotes (no tag-hierarchy expansion) is intentional
+          // here — synthesize-notes uses the FTS result only as a candidate seed,
+          // and scope filtering happens post-hydration. Don't route through the
+          // store.searchNotes wrapper for this specific tool.
+          const searchHits = noteOps.searchNotes(db, queryParam, { limit: Math.min(limit * 2, 100) });
+          searchHits.forEach((n, idx) => upsert(n.id, { source: "search", ftsRank: idx }));
+        }
+
+        // ----- Hydrate + scope filter -----
+        const ids = [...candidates.keys()];
+        const noteMap = new Map<string, Note>();
+        for (const id of ids) {
+          const n = noteOps.getNote(db, id);
+          if (n) noteMap.set(id, n);
+        }
+
+        const passesScope = (note: Note): boolean => {
+          if (scopeTags) {
+            const tags = note.tags ?? [];
+            if (!scopeTags.some((t) => tags.includes(t))) return false;
+          }
+          if (scopePathPrefix) {
+            const p = (note.path ?? "").toLowerCase();
+            if (!p.startsWith(scopePathPrefix)) return false;
+          }
+          return true;
+        };
+
+        const inScope: { id: string; note: Note; cand: Candidate }[] = [];
+        for (const [id, cand] of candidates) {
+          const note = noteMap.get(id);
+          if (!note) continue;
+          if (!passesScope(note)) continue;
+          inScope.push({ id, note, cand });
+        }
+
+        // ----- Score + rank -----
+        // Heuristic: anchor wins outright (5), search hits decay with FTS rank
+        // toward 0 (max ≈ 3), graph proximity contributes 0–3 (1 hop = 2,
+        // 2 hops = 1). Multi-source notes naturally rise — both axes add up.
+        const scoreOf = (c: Candidate): number => {
+          let s = 0;
+          if (c.sources.has("anchor")) s += 5;
+          if (c.sources.has("search") && c.ftsRank !== null) {
+            const decay = Math.max(0, 1 - c.ftsRank / 50);
+            s += 3 * decay;
+          }
+          if (c.sources.has("neighbor") && c.distance !== null) {
+            s += Math.max(0, 3 - c.distance);
+          }
+          return s;
+        };
+
+        inScope.sort((a, b) => {
+          const sa = scoreOf(a.cand);
+          const sb = scoreOf(b.cand);
+          if (sb !== sa) return sb - sa;
+          // Tie-break on recency so the agent surfaces the freshest take.
+          return (b.note.updatedAt ?? b.note.createdAt).localeCompare(a.note.updatedAt ?? a.note.createdAt);
+        });
+
+        const truncated = inScope.length > limit;
+        const top = inScope.slice(0, limit);
+
+        // ----- Snippet (cheap: first ~200 chars of content, single-line) -----
+        const snippetOf = (content: string): string => {
+          const flat = content.replace(/\s+/g, " ").trim();
+          return flat.length > 200 ? `${flat.slice(0, 197)}...` : flat;
+        };
+
+        const notesOut = top.map(({ id, note, cand }) => {
+          const out: Record<string, unknown> = {
+            id,
+            path: note.path ?? null,
+            tags: note.tags ?? [],
+            created_at: note.createdAt,
+            updated_at: note.updatedAt ?? null,
+            sources: [...cand.sources],
+            score: Number(scoreOf(cand).toFixed(3)),
+          };
+          if (cand.distance !== null) out.distance = cand.distance;
+          if (cand.ftsRank !== null) out.fts_rank = cand.ftsRank;
+          if (includeContent) {
+            out.content = note.content;
+          } else {
+            out.snippet = snippetOf(note.content);
+          }
+          return out;
+        });
+
+        // ----- Connections (direct links among returned notes only) -----
+        const idSet = new Set(top.map((t) => t.id));
+        const connections: { source: string; target: string; relationship: string }[] = [];
+        if (idSet.size > 1) {
+          const placeholders = [...idSet].map(() => "?").join(",");
+          const rows = db.prepare(
+            `SELECT source_id, target_id, relationship FROM links
+             WHERE source_id IN (${placeholders}) AND target_id IN (${placeholders})`,
+          ).all(...idSet, ...idSet) as { source_id: string; target_id: string; relationship: string }[];
+          for (const r of rows) {
+            connections.push({ source: r.source_id, target: r.target_id, relationship: r.relationship });
+          }
+        }
+
+        // ----- Tag distribution + timeline -----
+        const tagCounts = new Map<string, number>();
+        for (const { note } of top) {
+          for (const t of note.tags ?? []) tagCounts.set(t, (tagCounts.get(t) ?? 0) + 1);
+        }
+        const tags = [...tagCounts.entries()]
+          .map(([name, count]) => ({ name, count }))
+          .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+
+        const timeline = [...top]
+          .sort((a, b) => a.note.createdAt.localeCompare(b.note.createdAt))
+          .map(({ id, note }) => ({ id, created_at: note.createdAt }));
+
+        return {
+          topic: {
+            ...(anchorNote ? { anchor: { id: anchorNote.id, path: anchorNote.path ?? null } } : {}),
+            ...(queryParam ? { query: queryParam } : {}),
+          },
+          notes: notesOut,
+          connections,
+          tags,
+          timeline,
+          truncated,
+        };
+      },
+    },
+
+    // =====================================================================
+    // 10. vault-info — get/update vault description + stats
     // =====================================================================
     {
       name: "vault-info",
@@ -818,19 +1501,50 @@ function defaultForField(field: { type: string; enum?: string[] }): unknown {
   }
 }
 
+// ---------------------------------------------------------------------------
+// `_schemas/*` validation — surface validation_status on create/update
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach a `validation_status` field to the response when one or more
+ * `_schemas/*` config notes match this note's path or tags. Validation is
+ * advisory only — writes are never blocked. The agent receives warnings
+ * (missing required, type mismatch, enum mismatch) so it can self-correct
+ * on the next turn.
+ *
+ * Returns the note unchanged when no schemas apply, so callers without
+ * `_schemas/*` config see no behavior change.
+ */
+function attachValidationStatus(store: Store, _db: Database, note: Note): Note {
+  // Short-circuit cheaply: when no `_schemas/*` notes are configured, the
+  // resolver returns null without us paying a re-read of the note. The
+  // re-read used to happen up-front and was wasteful on every write in
+  // vaults that don't use schemas at all.
+  const status = store.validateNoteAgainstSchemas({
+    path: note.path,
+    tags: note.tags,
+    metadata: note.metadata as Record<string, unknown> | undefined,
+  });
+  if (!status) return note;
+  return { ...note, validation_status: status } as Note & { validation_status: typeof status };
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 function normalizeTags(tag: unknown): string[] | undefined {
   if (!tag) return undefined;
-  if (Array.isArray(tag)) return tag;
+  // Defensive copy: callers downstream sometimes mutate the array (sort,
+  // splice, push for hierarchy expansion). Returning a fresh array keeps
+  // the original `params` object untouched.
+  if (Array.isArray(tag)) return [...tag];
   return [tag as string];
 }
 
 // Re-exported for backward compat; defined in notes.ts alongside the
 // conditional-UPDATE implementation that raises it.
-export { ConflictError } from "./notes.js";
+export { ConflictError, PathConflictError, EmptyNoteError, MAX_BATCH_SIZE } from "./notes.js";
 
 /**
  * Thrown by the `update-note` MCP tool (and the REST PATCH handler) when a
@@ -854,3 +1568,23 @@ export class PreconditionRequiredError extends Error {
   }
 }
 
+/**
+ * Thrown by `create-note` / `update-note` when a batch exceeds
+ * `MAX_BATCH_SIZE` (re-exported from `./notes.js` — single source of truth).
+ * Bounds the blast radius of a runaway client — see #213, where one MCP
+ * burst created 7,453 empty notes in minutes. Surfaces as 413 at the HTTP
+ * layer.
+ */
+export class BatchTooLargeError extends Error {
+  code = "BATCH_TOO_LARGE" as const;
+  limit: number;
+  got: number;
+
+  constructor(got: number) {
+    super(`batch_too_large: max ${MAX_BATCH_SIZE} notes per call, got ${got}`);
+    this.name = "BatchTooLargeError";
+    this.limit = MAX_BATCH_SIZE;
+    this.got = got;
+  }
+}
+