@openparachute/vault 0.4.0 → 0.4.4-rc.11

package/core/src/mcp.ts

@@ -6,7 +6,6 @@ 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,
@@ -69,7 +68,9 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Generate the 10 consolidated MCP tools for a vault.
+ * Generate the consolidated MCP tools for a vault. Post-v17 surface (9):
+ * query-notes, create-note, update-note, delete-note, list-tags, update-tag,
+ * delete-tag, find-path, vault-info.
  */
 export function generateMcpTools(store: Store): McpToolDef[] {
   const db: Database = (store as any).db;
@@ -143,11 +144,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           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`." },
+              field: { type: "string", description: "Field to filter on. Defaults to `created_at` (vault ingestion time). `updated_at` is also recognized as a real column — use it for incremental rebuilds (\"what changed since X\"). 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.",
+            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) rather than the vault ingestion time, or when paging by `updated_at` for incremental rebuilds. Mutually exclusive with the top-level `date_from` / `date_to` shorthand.",
           },
           near: {
             type: "object",
@@ -446,7 +447,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
         // 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.
+        // tag's `fields` declaration that applies to this note.
         const final = created.map((n) => attachValidationStatus(store, db, n));
         return batch ? final : final[0];
       },
@@ -467,7 +468,9 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 - \`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. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design).`,
+- **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).
+- **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
+- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -489,6 +492,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           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 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." },
+          if_missing: { type: "string", enum: ["fail", "create"], description: "What to do when the note (by `id`/path) doesn't exist. `\"fail\"` (default) — error, current behavior. `\"create\"` — create the note from this same payload (content/path/tags/metadata become the create fields; the response carries `created: true`). Skips the `if_updated_at` precondition on the create branch (nothing to conflict with). Idempotent for sync loops that don't know ahead of time whether the note exists. See vault#309." },
           tags: {
             type: "object",
             properties: {
@@ -525,6 +529,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             },
             description: "Links to add/remove",
           },
+          include_content: {
+            type: "boolean",
+            description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize` and a whitespace-collapsed `preview`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
+          },
           // Batch
           notes: {
             type: "array",
@@ -548,6 +556,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                 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 or the item is `append`/`prepend`-only." },
                 force: { type: "boolean", description: "Override the required `if_updated_at` check for this item." },
+                if_missing: { type: "string", enum: ["fail", "create"], description: "Per-item: see top-level `if_missing` docs. Each batch item carries its own setting." },
                 tags: { type: "object" },
                 links: { type: "object" },
               },
@@ -566,6 +575,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         }
 
         const updated: Note[] = [];
+        // Track which note IDs were freshly created via `if_missing: "create"`
+        // so the response can carry `created: true|false` per-note. The
+        // sync-loop caller (Gitcoin Brain et al) reads this to know which
+        // path fired without doing a separate query. vault#309.
+        const createdIds = new Set<string>();
         // 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.
@@ -575,7 +589,77 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         if (batched) db.exec("BEGIN");
         try {
         for (const item of items) {
-          const note = requireNote(db, item.id as string);
+          // Try ID-then-path resolve. If not found AND
+          // `if_missing: "create"` is set, fall through to the create
+          // branch using this same item's payload. Otherwise mirror the
+          // existing `requireNote` behavior (throw "Note not found").
+          // vault#309.
+          const resolved = resolveNote(db, item.id as string);
+          if (!resolved) {
+            if (item.if_missing === "create") {
+              // Treat the update payload as a create payload. Minimum:
+              // content OR a path/id (something the createNote-empty-row
+              // invariant accepts). createNote enforces its own
+              // not-both-empty check — we leave that to the Store and
+              // surface any error to the caller verbatim.
+              //
+              // Field mapping (mirrors the create-note tool surface):
+              //   - `item.id` → both the note's `id` AND a fallback
+              //     `path` when `item.path` isn't set. Treating `id` as
+              //     the path-or-id lookup key matches Gitcoin's nightly
+              //     sync shape where the canonical key is a path string
+              //     like "Inbox/2026-05-13-meeting". If the caller
+              //     supplied an opaque ULID as `id` and no `path`, we
+              //     still create with that as `id` (path stays null).
+              //   - `item.content` / `item.path` / `item.tags` /
+              //     `item.metadata` / `item.created_at` → forwarded.
+              //   - `if_updated_at` / `force` / `content_edit` /
+              //     `append` / `prepend` / `links` are
+              //     update-only — silently ignored on the create branch.
+              //     (Content-edit on a non-existent note is a nonsense
+              //     combination; the caller's intent on missing-note is
+              //     "create the row", not "patch in this section".)
+              const idOrPath = item.id as string;
+              // Heuristic: if `path` isn't set AND the `id` looks like a
+              // path (contains "/" or doesn't match a typical opaque-id
+              // shape), use it as the path too. Otherwise treat it as a
+              // pure id. The shared `id` field for update is ID-or-path
+              // already (see `resolveNote`), so this preserves the
+              // caller's intent.
+              const idLooksLikePath = idOrPath.includes("/") || !/^[A-Za-z0-9_-]+$/.test(idOrPath);
+              const explicitPath = typeof item.path === "string" ? item.path as string : undefined;
+              const createOpts: Parameters<Store["createNote"]>[1] = {
+                ...(idLooksLikePath ? { path: explicitPath ?? idOrPath } : { id: idOrPath, ...(explicitPath !== undefined ? { path: explicitPath } : {}) }),
+                ...(item.tags && Array.isArray((item.tags as any).add)
+                  ? { tags: (item.tags as any).add as string[] }
+                  : Array.isArray(item.tags)
+                    ? { tags: item.tags as string[] }
+                    : {}),
+                ...(item.metadata !== undefined ? { metadata: item.metadata as Record<string, unknown> } : {}),
+                ...(item.created_at !== undefined ? { created_at: item.created_at as string } : {}),
+              };
+              const content = (item.content as string | undefined) ?? "";
+              const created = await store.createNote(content, createOpts);
+              await applySchemaDefaults(store, db, [created.id], created.tags ?? []);
+              // Apply links.add if the caller declared any.
+              const linksAdd = (item.links as any)?.add as { target: string; relationship: string; metadata?: Record<string, unknown> }[] | undefined;
+              if (linksAdd) {
+                for (const link of linksAdd) {
+                  const target = resolveNote(db, link.target);
+                  if (target) await store.createLink(created.id, target.id, link.relationship, link.metadata);
+                }
+              }
+              const fresh = noteOps.getNote(db, created.id) ?? created;
+              updated.push(fresh);
+              createdIds.add(fresh.id);
+              continue;
+            }
+            // Fallthrough: not-found + no if_missing → existing error
+            // contract. Match `requireNote`'s message shape so existing
+            // callers see no behavior change.
+            throw new Error(`Note not found: "${item.id}"`);
+          }
+          const note = resolved;
 
           // --- Validate mutual exclusion of content modes ---
           const hasContent = item.content !== undefined;
@@ -736,7 +820,26 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           throw e;
         }
 
-        const final = updated.map((n) => attachValidationStatus(store, db, n));
+        // Response shape: full Note (back-compat default) or lean NoteIndex
+        // (#285 friction point 2.response — opt-out for callers making
+        // frequent small edits to large notes). `validation_status` from
+        // `tags.fields` is preserved across either shape. `created: true|false`
+        // (vault#309) is attached to every response so callers using
+        // `if_missing: "create"` can tell which branch fired without a
+        // separate query. `false` for the (overwhelmingly common) update
+        // path; `true` only when this call took the create-on-missing
+        // branch.
+        const includeContent = params.include_content !== false;
+        const final = updated.map((n) => {
+          const validated = attachValidationStatus(store, db, n);
+          const created = createdIds.has(n.id);
+          if (includeContent) return { ...validated, created } as Note & { created: boolean };
+          const lean: any = noteOps.toNoteIndex(validated);
+          const vs = (validated as any).validation_status;
+          if (vs !== undefined) lean.validation_status = vs;
+          lean.created = created;
+          return lean;
+        });
         return batch ? final : final[0];
       },
     },
@@ -1002,180 +1105,6 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       },
     },
 
-    // =====================================================================
-    // 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
     // =====================================================================
@@ -1201,245 +1130,15 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     },
 
     // =====================================================================
-    // 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
+    // 9. vault-info — get/update vault description + stats
     // =====================================================================
     {
       name: "vault-info",
-      description: "Get vault description and optionally stats (note/tag/link counts, distribution). Pass `description` to update the vault description (changes how AI agents behave in future sessions).",
+      description: "Get a comprehensive vault projection: name, description, tags-with-schemas (own + effective parents/fields per #270 inheritance), indexed metadata fields catalog, and query hints. Pass `include_stats: true` to add note/tag/link counts and the monthly distribution. Pass `description` to update the vault description (changes how AI agents behave in future sessions). Call this anytime mid-session to refresh schema context.",
       inputSchema: {
         type: "object",
         properties: {
-          include_stats: { type: "boolean", description: "Include note count, tag count, distribution by month (default: false)" },
+          include_stats: { type: "boolean", description: "Include note count, tag count, attachment/link counts, and the monthly note distribution (default: false)" },
           description: { type: "string", description: "If provided, updates the vault description" },
         },
       },
@@ -1502,24 +1201,26 @@ function defaultForField(field: { type: string; enum?: string[] }): unknown {
 }
 
 // ---------------------------------------------------------------------------
-// `_schemas/*` validation — surface validation_status on create/update
+// `tags.fields` 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.
+ * Attach a `validation_status` field to the response when at least one tag
+ * on the note declares `fields` on its `tags` row. Validation is advisory
+ * only — writes are never blocked. The agent receives warnings (type
+ * mismatch, enum mismatch) so it can self-correct on the next turn.
+ *
+ * Returns the note unchanged when no tag declares fields, so callers
+ * without any tag schemas see no behavior change.
  *
- * Returns the note unchanged when no schemas apply, so callers without
- * `_schemas/*` config see no behavior change.
+ * Exported so both transports (MCP `update-note` here, HTTP `PATCH
+ * /api/notes/:id` in `src/routes.ts`) attach the same status field by
+ * the same recipe — see vault#287 for the asymmetry that motivated
+ * exposing it.
  */
-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.
+export function attachValidationStatus(store: Store, _db: Database, note: Note): Note {
+  // Short-circuit cheaply: when no tag declares fields, the resolver
+  // returns null without us paying a re-read of the note.
   const status = store.validateNoteAgainstSchemas({
     path: note.path,
     tags: note.tags,