@openparachute/vault 0.7.0-rc.8 → 0.7.1

package/core/src/mcp.ts

@@ -1,8 +1,9 @@
 import { Database } from "bun:sqlite";
-import type { Store, Note } from "./types.js";
+import type { Store, Note, QueryOpts } from "./types.js";
 import { transactionAsync } from "./txn.js";
 import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
+import { normalizePath } from "./paths.js";
 import { QueryError } from "./query-operators.js";
 import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "./tag-hierarchy.js";
 import {
@@ -15,7 +16,13 @@ import {
 } from "./query-warnings.js";
 import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "./search-query.js";
 import * as linkOps from "./links.js";
-import { resolveOrQueueLink, resolveStructuredLinkNote } from "./wikilinks.js";
+import {
+  resolveOrQueueLink,
+  resolveStructuredLinkNote,
+  getUnresolvedLinksForNote,
+  getUnresolvedLinksForNotes,
+  getContentWikilinkWarnings,
+} from "./wikilinks.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
 import {
@@ -78,7 +85,9 @@ function structuredError(
 
 /**
  * Resolve a note identifier — tries ID first, then case-insensitive
- * path match. Works everywhere a note reference is accepted.
+ * path match, then (additive fallback) an H1-title match. Works
+ * everywhere a note reference is accepted (query-notes `id`, update-note
+ * `id`, delete-note `id`, find-path anchors).
  *
  * Path-with-extension form (vault#330 S1): a trailing `.<ext>` matching
  * the extension pattern (`/^[a-z0-9]{1,16}$/i`) is parsed as
@@ -89,6 +98,12 @@ function structuredError(
  * On ambiguous path with no extension hint, `getNoteByPath` throws
  * `AmbiguousPathError` — `resolveNote` propagates it so MCP / REST
  * handlers can surface a clear 4xx rather than picking arbitrarily.
+ *
+ * Title fallback (additive): reached only when id AND path/extension
+ * BOTH miss cleanly (no throw). Resolves via `noteOps.getNoteByTitle` —
+ * the note whose first `# ` content line equals `idOrPath`, exactly one
+ * match required. Same [[wikilink]] semantics as `resolveWikilink`; exact
+ * id/path always wins first.
  */
 function resolveNote(db: Database, idOrPath: string): Note | null {
   // Try ID match first (fast, indexed)
@@ -104,7 +119,9 @@ function resolveNote(db: Database, idOrPath: string): Note | null {
     const explicit = noteOps.getNoteByPath(db, extMatch[1]!, extMatch[2]!);
     if (explicit) return explicit;
   }
-  return noteOps.getNoteByPath(db, idOrPath);
+  const byPath = noteOps.getNoteByPath(db, idOrPath);
+  if (byPath) return byPath;
+  return noteOps.getNoteByTitle(db, idOrPath);
 }
 
 function requireNote(db: Database, idOrPath: string): Note {
@@ -195,19 +212,65 @@ export interface GenerateMcpToolsOpts {
    * Omitted (unscoped / internal callers) → the full graph is walked.
    */
   nearTraversable?: (noteId: string) => boolean;
+  /**
+   * `ifExistsVisible` (vault#555 auth-review must-fix) is an OPTIONAL per-note
+   * predicate gating the `create-note` `if_exists` upsert. `if_exists` resolves
+   * the target `path` VAULT-WIDE (`getNoteByPath`) and then returns (ignore) /
+   * updates / replaces the found note — so without a scope gate a tag-scoped
+   * caller could READ or OVERWRITE an out-of-scope note just by naming its
+   * path. When provided, `applyExistingNote` calls this predicate on the
+   * RESOLVED existing note and, if it returns false, throws `PathConflictError`
+   * instead (the path is taken but invisible to this caller — no content
+   * exposed, nothing mutated). It's applied INSIDE `applyExistingNote`, which
+   * BOTH the proactive-check site AND the concurrent-INSERT race-backstop site
+   * funnel through — so a TOCTOU race (both existence checks miss, the real
+   * INSERT then loses to a concurrent writer's out-of-scope note) can't slip a
+   * note past it. Core stays scope-unaware: it receives a plain
+   * `(note) => boolean` closure and never imports the server's tag-scope
+   * module. Omitted (unscoped / internal callers) → `if_exists` resolves
+   * against the full vault exactly as before.
+   */
+  ifExistsVisible?: (note: Note) => boolean;
+  /**
+   * `aggregateVisibility` is an OPTIONAL per-note visibility predicate for
+   * `query-notes`'s `aggregate` mode. When provided, the aggregate is
+   * computed by first fetching every note the OTHER filters match
+   * (unpaginated), narrowing to the notes the predicate accepts, and THEN
+   * aggregating over just that visible id set — rather than the (faster)
+   * direct SQL GROUP BY the unscoped path takes. This mirrors
+   * `expandVisibility`/`nearTraversable`: core stays scope-unaware, it only
+   * invokes a plain `(note) => boolean` closure the server injects. Omitted
+   * (unscoped / internal callers) → the aggregate runs the fast direct-SQL
+   * path with no extra fetch.
+   */
+  aggregateVisibility?: (note: Note) => boolean;
 }
 
 /**
  * Generate the consolidated MCP tools for a vault. Surface (13):
- * query-notes, create-note, update-note, delete-note, list-tags, update-tag,
- * delete-tag, rename-tag, merge-tags, find-path, vault-info, prune-schema
- * (admin), doctor (admin). `manage-token` (admin) is appended by the SERVER
- * layer (src/mcp-tools.ts), not here — see that file's doc comment.
+ * query-notes, list-tags, find-path, vault-info, doctor (read); create-note,
+ * update-note, delete-note (write); update-tag, delete-tag, rename-tag,
+ * merge-tags, prune-schema (admin). `manage-token` (admin) is appended by
+ * the SERVER layer (src/mcp-tools.ts), not here — see that file's doc
+ * comment.
+ *
+ * **Re-tier (this PR):** content-authorship (write) is now separate from
+ * structure/taxonomy/schema-curation (admin). `update-tag`/`delete-tag`/
+ * `rename-tag`/`merge-tags` moved write → admin — they define schemas and
+ * restructure the tag graph across ALL notes, not just author content.
+ * `doctor` moved admin → read — it's a read-only, tag-scope-restricted
+ * diagnostic (see `applyTagScopeWrappers` in src/mcp-tools.ts), and
+ * read-scoped monitoring/tending jobs need to be able to run it without an
+ * admin credential. BREAKING: a `vault:write` token that used to
+ * rename/merge/delete/update tags now gets `insufficient_scope`; a
+ * `vault:read` token can now call `doctor`. See CHANGELOG.
  */
 export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): McpToolDef[] {
   const db: Database = store.db;
   const expandVisibility = opts?.expandVisibility;
   const nearTraversable = opts?.nearTraversable;
+  const ifExistsVisible = opts?.ifExistsVisible;
+  const aggregateVisibility = opts?.aggregateVisibility;
   // Write-attribution (vault#298) — captured once at tool-generation time
   // (a fresh tool set is generated per MCP request, so this is request-scoped)
   // and folded into every create/update the tools perform.
@@ -257,7 +320,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
       requiredVerb: "read",
       description: `Query notes. Returns notes matching the given filters.
 
-- **Single note**: pass \`id\` (accepts note ID or path, e.g., "Projects/README")
+- **Single note**: pass \`id\` (accepts note ID, path, e.g., "Projects/README", or — as a last-resort fallback when id/path both miss cleanly and exactly one note matches — its H1 title, e.g. "Weekly Review")
 - **Filter**: pass \`tag\`, \`path\`, \`path_prefix\`, \`search\`, \`metadata\`, date range
 - **Graph neighborhood**: pass \`near\` to scope results to notes within N hops of an anchor note
 - **No filters**: returns all notes (paginated)
@@ -270,10 +333,15 @@ Large notes: pass \`content_offset\` / \`content_length\` (UTF-8 bytes) for a bo
 
 Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returned content. Tune with \`expand_depth\` (1–3, default 1) and \`expand_mode\` ("full" inlines full content, "summary" inlines only metadata.summary). Expansions are deduplicated across the query and cycle-guarded.
 
+Broken links (vault#555): a \`[[wikilink]]\` or structured \`links\` target that never resolved to a note used to be invisible — silently dropped from the response with no signal it existed. Pass \`has_broken_links: true\`/\`false\` to filter notes by whether they have any dangling outbound link, and/or \`include_broken_links: true\` to attach each note's pending targets as \`broken_links: [{target, relationship}]\` (empty array when none). Both read the vault's pending-resolution table — the same source \`create-note\`/\`update-note\`'s \`unresolved_link\` warning draws from; a target created later (this session or any future one) backfills the edge automatically and the note drops out of \`has_broken_links: true\`.
+
 Response shape (vault#550 — three variants, pick by what you passed):
 - Default (no \`cursor\`, no warnings): a bare array of notes.
 - Cursor mode (\`cursor\` param present — including \`cursor: ""\` to bootstrap): \`{notes: [...], next_cursor}\`. See \`cursor\` below for the bootstrap flow.
 - Warnings present (e.g. an unrecognized \`tag\`) and NOT in cursor mode: \`{notes: [...], warnings: [...]}\`. Cursor mode + warnings compose: \`{notes, next_cursor, warnings}\`. Absent \`warnings\` key means nothing to flag — don't assume its presence either way.
+- \`aggregate\` mode: \`[{group, value}]\` — a rollup row per group, NOT notes. See \`aggregate\` below.
+
+\`aggregate\` (group_by + count/sum): pass \`aggregate: {group_by, op, field?}\` to get counts/sums instead of note rows — e.g. "how many notes per status" (\`{group_by: "status", op: "count"}\`) or "total amount per category" (\`{group_by: "category", op: "sum", field: "amount"}\`). Every other filter (\`tag\`, \`metadata\`, date range, ...) narrows the input set FIRST, exactly like a normal query. \`group_by\` is either \"tag\" (group by tag membership) or an indexed metadata field; \`op: "sum"\` additionally requires \`field\` to be an indexed NUMERIC field. Mutually exclusive with \`search\`/\`near\`/\`cursor\`.
 
 \`search\` is literal-by-default (vault#551): your text is escaped and phrase-quoted before it reaches FTS5, so ordinary punctuation ("didn't", "eleven-day", "18.6") is matched as literal content instead of being parsed as query syntax (a bare hyphen used to mean NOT; an apostrophe or decimal point used to break the parse and silently return \`[]\`). Pass \`search_mode: "advanced"\` to opt back into raw FTS5 syntax (AND/OR/NOT, manual phrase quoting, prefix \`*\`) — a malformed advanced query now throws a structured error instead of silently returning \`[]\`. \`sort\` is honored under \`search\` too: omit it for relevance ranking (default), or pass "asc"/"desc" to order by \`created_at\` instead.
 
@@ -281,7 +349,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
       inputSchema: {
         type: "object",
         properties: {
-          id: { type: "string", description: "Get one note by ID or path" },
+          id: { type: "string", description: "Get one note by ID, path, or (fallback, only when id/path both miss and exactly one note matches) its H1 title" },
           tag: {
             oneOf: [
               { type: "string" },
@@ -322,6 +390,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
           },
           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)." },
+          has_broken_links: { type: "boolean", description: "Presence filter (vault#555): true = only notes with at least one dangling outbound link — a [[wikilink]] or structured `links` target that never resolved to a note; false = only notes with none. Backed by the unresolved_wikilinks table (same data `doctor`/list-unresolved surfaces); safe on a vault where no link has ever gone unresolved (true matches nothing, false is a no-op)." },
           path: { type: "string", description: "Exact path match (case-insensitive)" },
           path_prefix: { type: "string", description: "Path prefix match (e.g., 'Projects/')" },
           extension: {
@@ -362,10 +431,20 @@ Response shape (vault#550 — three variants, pick by what you passed):
             },
             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.",
           },
+          aggregate: {
+            type: "object",
+            properties: {
+              group_by: { type: "string", description: "What to group by: an indexed metadata field name (declared `indexed: true` in a tag schema — same FIELD_NOT_INDEXED contract as `metadata` operator queries / `order_by`), or the special value \"tag\" to group by tag membership. Under \"tag\", a note carrying N of the tags present in the filtered result set contributes to N separate groups (a membership rollup, not a partition)." },
+              op: { type: "string", enum: ["count", "sum"], description: "\"count\": number of matching notes per group. \"sum\": sum of `field` per group." },
+              field: { type: "string", description: "Required when `op` is \"sum\"; ignored for \"count\". Must be an indexed metadata field with a numeric storage type (declared `type: \"integer\"` or `type: \"boolean\"` — the only indexable numeric shapes; a bare `type: \"number\"` field is never indexed and a TEXT-backed field can't be summed)." },
+            },
+            required: ["group_by", "op"],
+            description: "Aggregation / rollup mode. Every OTHER filter above (tag, metadata, date range, write-attribution, ...) is applied FIRST, exactly as a normal query would; the matching notes are then grouped and the response becomes `[{group, value}]` instead of note rows — one row per group, `value` is the count/sum. A note whose group_by value is absent collects into one `{group: null, value: ...}` row rather than being dropped. Mutually exclusive with `search`, `near`, and `cursor` (a rollup has no pagination/ranking/graph-neighborhood shape). Tag-scoped sessions see the SAME visibility enforcement as every other read — the rollup is computed only over notes the token can see.",
+          },
           near: {
             type: "object",
             properties: {
-              note_id: { type: "string", description: "Anchor note ID or path" },
+              note_id: { type: "string", description: "Anchor note ID, path, or (fallback) H1 title" },
               depth: { type: "number", description: "Max hops from anchor (default 2, max 5)" },
               relationship: { type: "string", description: "Only follow links with this relationship" },
             },
@@ -404,6 +483,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
             description: "Control metadata in response: true (all, default), false (none), or array of field names to include",
           },
           include_links: { type: "boolean", description: "Include inbound + outbound links per note (default: false)" },
+          include_broken_links: { type: "boolean", description: "Include each note's dangling outbound links as `broken_links: [{target, relationship}]` (default: false; vault#555). `target` is the unresolved path/title the [[wikilink]] or structured `links` entry named; `relationship` is \"wikilink\" for content-parsed links or the caller's own relationship string for a structured link. Empty array when the note has none. One batched query per request regardless of page size — mirrors `has_broken_links` (same backing table) and `include_links`." },
           include_link_count: {
             type: "boolean",
             description:
@@ -492,6 +572,9 @@ Response shape (vault#550 — three variants, pick by what you passed):
           if (params.include_links) {
             result.links = linkOps.getLinksHydrated(db, note.id);
           }
+          if (params.include_broken_links) {
+            result.broken_links = getUnresolvedLinksForNote(db, note.id);
+          }
           if (params.include_attachments) {
             result.attachments = await store.getAttachments(note.id);
           }
@@ -569,6 +652,89 @@ Response shape (vault#550 — three variants, pick by what you passed):
           expand = params.expand as TagExpandMode;
         }
 
+        // --- Aggregation / rollup mode (top new-feature ask from a UX round) ---
+        // Mutually exclusive with `search`/`near`/`cursor` — a rollup returns
+        // one row per group, not a paginated / graph-scoped / ranked note
+        // list — so reject those combos loudly before touching the DB.
+        if (params.aggregate) {
+          if (params.search) {
+            throw new QueryError(
+              `aggregate is incompatible with full-text search — pick one.`,
+              "INVALID_QUERY",
+              { error_type: "invalid_query", field: "aggregate", hint: "drop `search` when using `aggregate`" },
+            );
+          }
+          if (params.near) {
+            throw new QueryError(
+              `aggregate is incompatible with near (graph neighborhood).`,
+              "INVALID_QUERY",
+              { error_type: "invalid_query", field: "aggregate", hint: "drop `near` when using `aggregate`" },
+            );
+          }
+          if (typeof params.cursor === "string") {
+            throw new QueryError(
+              `aggregate is incompatible with cursor pagination — a rollup has no watermark to page through.`,
+              "INVALID_QUERY",
+              { error_type: "invalid_query", field: "aggregate", hint: "drop `cursor` when using `aggregate`" },
+            );
+          }
+          const aggRaw = params.aggregate as Record<string, unknown>;
+          if (typeof aggRaw !== "object" || aggRaw === null || Array.isArray(aggRaw)) {
+            throw new QueryError(
+              `aggregate must be an object: {group_by, op, field?}`,
+              "INVALID_QUERY",
+              { error_type: "invalid_query", field: "aggregate", got: aggRaw },
+            );
+          }
+          // Shape coercion only — `group_by`/`op`/`field` validity (indexed
+          // field, numeric type, sum requires field, ...) is enforced by
+          // `aggregateNotes` itself, reusing the exact FIELD_NOT_INDEXED /
+          // INVALID_QUERY contract every other query surface uses.
+          const aggregateSpec = {
+            group_by: aggRaw.group_by as string,
+            op: aggRaw.op as "count" | "sum",
+            field: aggRaw.field as string | undefined,
+          };
+          const aggTags = normalizeTags(params.tag);
+          const aggExcludeTagsRaw = params.exclude_tags ?? params.excludeTags ?? params.exclude_tag;
+          const aggExcludeTags = normalizeTags(aggExcludeTagsRaw);
+          const aggFilterOpts: QueryOpts = {
+            tags: aggTags,
+            tagMatch: (params.tag_match as "all" | "any") ?? (aggTags && aggTags.length > 1 ? "any" : undefined),
+            expand,
+            excludeTags: aggExcludeTags,
+            hasTags: params.has_tags as boolean | undefined,
+            hasLinks: params.has_links as boolean | undefined,
+            hasBrokenLinks: params.has_broken_links as boolean | undefined,
+            path: params.path as string | undefined,
+            pathPrefix: params.path_prefix as string | undefined,
+            extension: params.extension as string | string[] | undefined,
+            metadata: params.metadata as Record<string, unknown> | undefined,
+            createdBy: params.created_by as string | undefined,
+            lastUpdatedBy: params.last_updated_by as string | undefined,
+            createdVia: params.created_via as string | undefined,
+            lastUpdatedVia: params.last_updated_via as string | 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,
+          };
+          if (!aggregateVisibility) {
+            return await store.aggregateNotes({ ...aggFilterOpts, aggregate: aggregateSpec });
+          }
+          // Tag-scoped: filter to visible notes FIRST — fetch every note the
+          // OTHER filters match (unpaginated, same `limit: 1000000` "get
+          // everything" convention `syncAllWikilinks` uses), narrow to what
+          // the injected predicate accepts, THEN aggregate over just that id
+          // set (reusing the `ids` semijoin `near` already pushes into SQL).
+          // Core stays scope-unaware — it only invokes the plain closure.
+          const aggAllMatches = await store.queryNotes({ ...aggFilterOpts, limit: 1000000 });
+          const aggVisibleIds = aggAllMatches.filter(aggregateVisibility).map((n) => n.id);
+          if (aggVisibleIds.length === 0) return [];
+          return await store.aggregateNotes({ ids: aggVisibleIds, aggregate: aggregateSpec });
+        }
+
         // `search_mode` (vault#551) — validate loudly (same policy as
         // `expand` above) so a typo'd value doesn't silently fall back to
         // the default. Resolved here (before the search/structured branch)
@@ -682,6 +848,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
             excludeTags,
             hasTags: params.has_tags as boolean | undefined,
             hasLinks: params.has_links as boolean | undefined,
+            hasBrokenLinks: params.has_broken_links as boolean | undefined,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
             extension: params.extension as string | string[] | undefined,
@@ -800,8 +967,8 @@ Response shape (vault#550 — three variants, pick by what you passed):
           for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
         }
 
-        // --- Hydrate links/attachments per note if requested ---
-        if (params.include_links || params.include_attachments) {
+        // --- Hydrate links/attachments/broken-links per note if requested ---
+        if (params.include_links || params.include_attachments || params.include_broken_links) {
           // Links hydrate for the WHOLE page in a constant number of
           // queries (see getLinksHydratedForNotes) — the per-note variant
           // cost (1 link query + 1 summary query + N tag queries) × page
@@ -809,10 +976,15 @@ Response shape (vault#550 — three variants, pick by what you passed):
           const linksByNote = params.include_links
             ? linkOps.getLinksHydratedForNotes(db, (output as any[]).map((n: any) => n.id))
             : null;
+          // Same one-batched-query-for-the-page shape as links (vault#555).
+          const brokenLinksByNote = params.include_broken_links
+            ? getUnresolvedLinksForNotes(db, (output as any[]).map((n: any) => n.id))
+            : null;
           const enrichedOut: any[] = [];
           for (const n of output as any[]) {
             const enriched: any = { ...n };
             if (linksByNote) enriched.links = linksByNote.get(n.id) ?? [];
+            if (brokenLinksByNote) enriched.broken_links = brokenLinksByNote.get(n.id) ?? [];
             if (params.include_attachments) enriched.attachments = await store.getAttachments(n.id);
             enrichedOut.push(enriched);
           }
@@ -850,7 +1022,17 @@ Response shape (vault#550 — three variants, pick by what you passed):
     {
       name: "create-note",
       requiredVerb: "write",
-      description: `Create one or more notes. Pass a single note's fields directly, or pass a \`notes\` array for batch creation. Each note accepts content, path, metadata, tags, links, and created_at.`,
+      description: `Create one or more notes. Pass a single note's fields directly, or pass a \`notes\` array for batch creation. Each note accepts content, path, metadata, tags, links, and created_at.
+
+**Path-conflict handling** — \`if_exists: "error"|"ignore"|"update"|"replace"\` (vault#555, default \`"error"\`): what to do when the note's \`path\` already names an existing note.
+- \`"error"\` (DEFAULT — unchanged behavior): the write is rejected with a \`path_conflict\` error (409); nothing is mutated.
+- \`"ignore"\`: return the existing note UNCHANGED — no error and no mutation of any kind (content/metadata/tags/links untouched; no schema-default backfill runs either). Response carries \`existed: true\`. The idempotent-retry primitive: a crash-replay or the losing side of a create-race gets back the same note a first-time caller would have created, safely, any number of times.
+- \`"update"\`: merge this payload into the existing note — \`content\` (if provided) fully replaces the existing content, exactly like \`update-note\`'s \`content\` field (omit to leave it untouched); \`metadata\` (if provided) is RFC-7386 merged — existing keys preserved, incoming keys overwrite, an incoming \`null\` value deletes a key — same semantics as \`update-note\`; \`tags\`/\`links\` (if provided) are ADDED to the existing set (union — nothing already there is removed). Response carries \`existed: true\`.
+- \`"replace"\`: overwrite \`content\` and \`metadata\` WHOLESALE — \`content\` becomes exactly the incoming value (or \`""\` if omitted) and \`metadata\` becomes exactly the incoming object (or \`{}\` if omitted), NOT merged, so a prior metadata key absent from this payload is dropped. \`tags\`/\`links\` stay additive (same union behavior as \`"update"\`) — a replace targets the free-form fields, not the taxonomy/graph, so it can't silently orphan links or detach tags the caller didn't mention. The note's \`id\` and \`created_at\` are preserved either way.
+
+A note's response carries \`existed\` (true/false) whenever ITS \`if_exists\` was one of \`"ignore"\`/\`"update"\`/\`"replace"\` — \`true\` when the collision branch fired, \`false\` when a normal fresh insert happened instead (including when \`path\` was never set, so there was nothing to conflict with — \`if_exists\` is a no-op without a \`path\`, but still reports \`existed: false\`). Absent entirely under the default \`"error"\` mode — a plain create-note call's response shape is byte-identical to before this feature. Batch-aware, per-item (like \`if_missing\` on \`update-note\`): set \`if_exists\` inside each \`notes[]\` entry — a top-level \`if_exists\` alongside a \`notes\` array is NOT inherited by items that omit their own (it only takes effect on the single-note form, where \`params\` IS the one item).
+
+**Batch summary** — pass \`summary: true\` (batch/\`notes\` calls only; ignored on a single-note call) to receive a compact \`{created, ids, failed}\` shape instead of N full note objects: \`created\` counts items that resulted in a BRAND-NEW insert (excludes \`if_exists\` collisions); \`ids\` lists every resulting note id in item order (fresh creates AND \`existed\` hits alike); \`failed\` is reserved for future partial-batch-failure reporting — today a batch create is all-or-nothing (any thrown error aborts and rolls back the WHOLE call, same with or without \`summary\`), so it's always \`[]\`.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -865,29 +1047,38 @@ Response shape (vault#550 — three variants, pick by what you passed):
             items: {
               type: "object",
               properties: {
-                target: { type: "string", description: "Target note ID or path" },
+                target: { type: "string", description: "Target note ID, path, or (fallback) H1 title" },
                 relationship: { type: "string", description: "Relationship type (e.g., mentions, related-to)" },
               },
               required: ["target", "relationship"],
             },
-            description: "Links to create from this note. `target` resolves with the SAME semantics as a [[wikilink]] (vault#555) — ID, then exact path, then basename/title. A target created LATER in the same `notes` batch, or by a future call, resolves automatically (queued + backfilled) — the response carries an `unresolved_link` warning naming the target in the meantime; never silently dropped.",
+            description: "Links to create from this note. `target` resolves with the SAME semantics as a [[wikilink]] (vault#555) — ID, then exact path, then basename, then (only on a clean miss, and only when exactly one note matches) an H1-title fallback. A target created LATER in the same `notes` batch, or by a future call, resolves automatically (queued + backfilled) — the response carries an `unresolved_link` warning naming the target in the meantime; never silently dropped.",
           },
           created_at: { type: "string", description: "ISO timestamp (defaults to now)" },
+          if_exists: {
+            type: "string",
+            enum: ["error", "ignore", "update", "replace"],
+            description: "What to do when `path` already names an existing note (vault#555). See the tool description for the full contract of each mode. Default \"error\" — unchanged path_conflict behavior.",
+          },
+          summary: {
+            type: "boolean",
+            description: "Batch calls only (a `notes` array): return a compact `{created, ids, failed}` shape instead of N full note objects. See the tool description. Ignored on a single-note call.",
+          },
           // Batch
           notes: {
             type: "array",
             items: {
               type: "object",
               properties: {
-                content: { type: "string" },
+                content: { type: "string", description: "Optional — defaults to \"\" (vault#555 fix: this item's schema previously marked it `required`, but it was never enforced; an empty-content batch item has always succeeded)." },
                 path: { type: "string" },
                 extension: { type: "string", description: "File extension (vault#328). See top-level docs." },
                 metadata: { type: "object" },
                 tags: { type: "array", items: { type: "string" } },
                 links: { type: "array" },
                 created_at: { type: "string" },
+                if_exists: { type: "string", enum: ["error", "ignore", "update", "replace"], description: "Per-item: see top-level `if_exists` docs. Each batch item carries its own setting." },
               },
-              required: ["content"],
             },
             description: "Array of notes for batch creation",
           },
@@ -909,19 +1100,166 @@ Response shape (vault#550 — three variants, pick by what you passed):
         // moment item 0's links were processed. Deferring makes
         // within-batch forward-refs resolve exactly like a same-content
         // [[wikilink]] already does. `pendingLinks` carries the SOURCE
-        // note id (known immediately — createNote assigns it synchronously)
-        // alongside each item's raw `links` array.
+        // note id (known immediately — createNote assigns it synchronously,
+        // and so does the `if_exists` existing-note branch below) alongside
+        // each item's raw `links` array.
         const pendingLinks: { sourceId: string; links: { target: string; relationship: string }[] }[] = [];
         // Per-note `unresolved_link` warnings (vault#555 — "never silent").
         // Populated in the second pass; folded into each note's response
         // below, same pattern as `validation_status`.
         const linkWarningsByNote = new Map<string, QueryWarning[]>();
+        const pushLinkWarning = (noteId: string, warning: QueryWarning): void => {
+          const list = linkWarningsByNote.get(noteId) ?? [];
+          list.push(warning);
+          linkWarningsByNote.set(noteId, list);
+        };
+        // Content wikilinks whose note+content pair needs an `unresolved_link`/
+        // `ambiguous_link` warning check (vault#570). Deferred to the same
+        // second pass as `pendingLinks` — a content `[[wikilink]]` to a
+        // sibling created LATER in this batch resolves via the same
+        // forward-ref backfill structured `links` use, so the classification
+        // must run only after every item in the batch exists.
+        const contentWikilinkNotes: { noteId: string; content: string }[] = [];
+        // `if_exists` bookkeeping (vault#555). `existedMap` is set ONLY for
+        // items whose `if_exists` engaged (ignore/update/replace) — absent
+        // means the default "error" path ran, so a plain create-note call
+        // sees zero response-shape change. `true` = the path already named
+        // a note and that branch fired; `false` = if_exists was set but no
+        // conflict occurred (a normal fresh insert). `noMutateIds` marks
+        // "ignore" hits so the schema-defaults pass below skips them
+        // entirely — "ignore" promises NO mutation, including backfill.
+        const existedMap = new Map<string, boolean>();
+        const noMutateIds = new Set<string>();
+        /** Record an `if_exists` collision outcome — shared by both call sites below. */
+        const recordExistedBranch = (resultNote: Note, noMutate: boolean): void => {
+          existedMap.set(resultNote.id, true);
+          if (noMutate) noMutateIds.add(resultNote.id);
+          created.push(resultNote);
+        };
+
+        /**
+         * Handle an `if_exists` collision against an already-resolved
+         * `existingNote` — shared by the proactive pre-check (the common,
+         * non-racing path) and the insert-time PathConflictError catch
+         * (the race-closing backstop: a concurrent writer's INSERT
+         * committed between our check and ours). Returns the note to put
+         * in the response and whether it must be excluded from the
+         * schema-defaults mutation pass ("ignore" — genuinely untouched).
+         */
+        const applyExistingNote = async (
+          item: any,
+          existingNote: Note,
+          mode: "ignore" | "update" | "replace",
+        ): Promise<{ note: Note; noMutate: boolean }> => {
+          // CRITICAL scope guard (vault#555 auth-review must-fix). `existingNote`
+          // was resolved VAULT-WIDE by path (getNoteByPath) at whichever call
+          // site reached here — the proactive check OR the concurrent-INSERT
+          // race backstop. A tag-scoped MCP session injects `ifExistsVisible`
+          // (see GenerateMcpToolsOpts); when the resolved note fails it, the
+          // caller must not read (ignore) / update / replace an out-of-scope
+          // note it named only by path — throw PathConflictError (path taken,
+          // invisible to this caller) BEFORE any read or mutation, so no
+          // content leaks and nothing is written. Placing it HERE — not only in
+          // the server-layer wrapper's pre-check — is what closes the
+          // race-backstop TOCTOU: the pre-check + core's proactive check can
+          // BOTH miss a note a concurrent writer then INSERTs, and the backstop
+          // re-resolves it into this exact call. Core stays scope-unaware: it
+          // only invokes the injected closure. Unscoped/internal callers pass no
+          // predicate → unchanged behavior.
+          if (ifExistsVisible && !ifExistsVisible(existingNote)) {
+            throw new noteOps.PathConflictError(existingNote.path ?? "");
+          }
+          if (mode === "ignore") {
+            // No error, no mutation of any kind — not even schema-default
+            // backfill. Return the existing note exactly as stored.
+            return { note: existingNote, noMutate: true };
+          }
+
+          // "update" / "replace" both apply tags/links additively (union) —
+          // they differ only in how content/metadata combine with the
+          // existing values. See the tool description for the full contract.
+          const updates: { content?: string; metadata?: Record<string, unknown> } = {};
+          if (mode === "update") {
+            if (item.content !== undefined) updates.content = item.content as string;
+            if (item.metadata !== undefined) {
+              updates.metadata = noteOps.mergeMetadata(
+                existingNote.metadata as Record<string, unknown> | null | undefined,
+                item.metadata as Record<string, unknown>,
+              );
+            }
+          } else {
+            // "replace" — PUT semantics: content/metadata become exactly
+            // this payload (empty default when omitted), never merged.
+            updates.content = (item.content as string | undefined) ?? "";
+            updates.metadata = (item.metadata as Record<string, unknown> | undefined) ?? {};
+          }
+
+          const incomingTags = (item.tags as string[] | undefined) ?? [];
+          const projectedTags = new Set<string>([...(existingNote.tags ?? []), ...incomingTags]);
+          const projectedMetadata =
+            updates.metadata ?? ((existingNote.metadata as Record<string, unknown>) ?? {});
+          // Strict-schema gate (vault#299) against the PROJECTED final shape
+          // (existing ∪ incoming), not the raw incoming item — a caller
+          // updating one field of an already-conforming note shouldn't have
+          // to re-supply every `required` field just to pass validation.
+          enforceStrict({ path: existingNote.path, tags: [...projectedTags], metadata: projectedMetadata });
+
+          // vault#555 fix 2 (W8 fix-2 bug class, generalist must-fix): a
+          // tags-only or links-only "update" leaves `updates` empty, so
+          // gating store.updateNote on `updates` ALONE would skip it — and
+          // then a genuine tag/link mutation (store.tagNote below) would never
+          // bump `updated_at`, breaking cursor polling (`ORDER BY updated_at`)
+          // and any since-last-check sync. Gate on the tag/link mutation too,
+          // mirroring the update-note/PATCH path's hasTagMutation||hasLinkMutation.
+          // store.updateNote with empty core fields still issues a real UPDATE
+          // that bumps updated_at (+ last_updated_by/via). "replace" always
+          // sets content+metadata, so it was never affected.
+          const hasLinkMutation = item.links !== undefined;
+          let result: Note = existingNote;
+          if (Object.keys(updates).length > 0 || incomingTags.length > 0 || hasLinkMutation) {
+            result = await store.updateNote(existingNote.id, {
+              ...updates,
+              actor: writeActor,
+              via: writeVia,
+            });
+          }
+
+          // Content-wikilink warnings (vault#570) — this branch's content
+          // update (if any) already ran `syncWikilinks` inside
+          // `store.updateNote` above; queue the (noteId, content) pair for
+          // the shared second-pass classification below (same treatment as
+          // a fresh create's content).
+          if (updates.content !== undefined) {
+            contentWikilinkNotes.push({ noteId: result.id, content: updates.content });
+          }
+
+          if (incomingTags.length > 0) {
+            await store.tagNote(result.id, incomingTags);
+            // Note: applySchemaDefaults also runs in the outer batch loop for
+            // this note (it's not in `noMutateIds` — only "ignore" hits are),
+            // so this inline call is redundant. Harmless (idempotent — fills
+            // only still-missing fields), kept so the update/replace branch is
+            // self-contained; left un-gated to avoid coupling to the outer loop.
+            await applySchemaDefaults(store, db, [result.id], incomingTags);
+          }
+
+          if (item.links) {
+            pendingLinks.push({ sourceId: result.id, links: item.links as { target: string; relationship: string }[] });
+          }
+
+          return { note: noteOps.getNote(db, result.id) ?? result, noMutate: false };
+        };
+
         // Wrap multi-item batches in a SQLite transaction so a mid-batch
         // failure rolls back every prior insert — see #236. 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.
+        // connection. Catching a PathConflictError INSIDE this callback
+        // (the if_exists race backstop below) does NOT roll back the
+        // transaction — only a throw that escapes `runBatch` does (see
+        // core/src/txn.ts) — so the fallback-to-existing-note path commits
+        // normally alongside every other item in the batch.
         const batched = items.length > 1;
         const runBatch = async (): Promise<void> => {
           for (const item of items) {
@@ -931,6 +1269,28 @@ Response shape (vault#550 — three variants, pick by what you passed):
             const extension = item.extension !== undefined
               ? validateExtension(item.extension)
               : undefined;
+            const effectiveExtension = extension ?? "md";
+            const ifExists = (item.if_exists as string | undefined) ?? "error";
+            const upsertMode = ifExists === "ignore" || ifExists === "update" || ifExists === "replace";
+
+            // Proactive existence check (vault#555) — only possible when a
+            // path is set (a pathless create can never conflict). Handles
+            // the common, non-racing case cleanly: skip the raw-item strict
+            // gate entirely (it would validate the wrong shape — see
+            // `applyExistingNote`) and go straight to the ignore/update/
+            // replace branch. The insert-time catch below is the backstop
+            // for the rare true race.
+            let existingNote: Note | null = null;
+            if (upsertMode && item.path) {
+              const normalized = normalizePath(item.path as string);
+              existingNote = normalized ? noteOps.getNoteByPath(db, normalized, effectiveExtension) : null;
+            }
+            if (existingNote) {
+              const { note: resultNote, noMutate } = await applyExistingNote(item, existingNote, ifExists as "ignore" | "update" | "replace");
+              recordExistedBranch(resultNote, noMutate);
+              continue;
+            }
+
             // Strict-schema gate (vault#299) — reject before any write so a
             // mid-batch violation rolls back the batch transaction.
             enforceStrict({
@@ -938,22 +1298,51 @@ Response shape (vault#550 — three variants, pick by what you passed):
               tags: item.tags as string[] | undefined,
               metadata: item.metadata as Record<string, unknown> | undefined,
             });
-            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,
-              ...(extension !== undefined ? { extension } : {}),
-              // Write-attribution (vault#298) — same actor/via for every item
-              // in a batch (the whole call came from one authenticated session).
-              actor: writeActor,
-              via: writeVia,
-            });
+            let note: Note;
+            try {
+              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,
+                ...(extension !== undefined ? { extension } : {}),
+                // Write-attribution (vault#298) — same actor/via for every item
+                // in a batch (the whole call came from one authenticated session).
+                actor: writeActor,
+                via: writeVia,
+              });
+            } catch (err) {
+              // Race backstop (vault#555): a concurrent writer's INSERT
+              // committed between our proactive check (skipped or missed
+              // above) and this one. Re-resolve the now-existing row and
+              // fall through to the SAME branch a proactive hit would have
+              // taken — closes the create-race gap even under true
+              // concurrency, not just the sequential common case.
+              if (upsertMode && err instanceof noteOps.PathConflictError) {
+                const winner = noteOps.getNoteByPath(db, err.path, effectiveExtension);
+                if (winner) {
+                  const { note: resultNote, noMutate } = await applyExistingNote(item, winner, ifExists as "ignore" | "update" | "replace");
+                  recordExistedBranch(resultNote, noMutate);
+                  continue;
+                }
+              }
+              throw err;
+            }
+
+            if (upsertMode) existedMap.set(note.id, false);
 
             if (item.links) {
               pendingLinks.push({ sourceId: note.id, links: item.links as { target: string; relationship: string }[] });
             }
 
+            // Content-wikilink warnings (vault#570) — `store.createNote`
+            // above already ran `syncWikilinks` (gated on `content` truthy,
+            // same condition here) — queue for the shared second-pass
+            // classification below.
+            if (item.content) {
+              contentWikilinkNotes.push({ noteId: note.id, content: item.content as string });
+            }
+
             created.push(noteOps.getNote(db, note.id) ?? note);
           }
 
@@ -963,24 +1352,44 @@ Response shape (vault#550 — three variants, pick by what you passed):
           // STILL doesn't resolve (typo, or a note that arrives in a later
           // call) is queued for lazy resolution — it backfills automatically
           // the moment a matching note is created — and surfaces an
-          // `unresolved_link` warning naming the target. Never silent.
+          // `unresolved_link` warning naming the target. A target that
+          // matched ≥2 notes (vault#570) is neither linked nor queued —
+          // surfaces a distinct `ambiguous_link` warning instead. Never silent.
           for (const { sourceId, links } of pendingLinks) {
             for (const link of links) {
-              const targetId = resolveOrQueueLink(db, sourceId, link.target, link.relationship);
-              if (targetId) {
-                await store.createLink(sourceId, targetId, link.relationship);
+              const outcome = resolveOrQueueLink(db, sourceId, link.target, link.relationship);
+              if (outcome.status === "resolved") {
+                await store.createLink(sourceId, outcome.note_id, link.relationship);
+              } else if (outcome.status === "ambiguous") {
+                pushLinkWarning(sourceId, {
+                  code: "ambiguous_link",
+                  message: `link target "${link.target}" (relationship "${link.relationship}") matched ${outcome.candidates.length} notes — ambiguous, no link created. Use a more specific path or the note's ID to disambiguate.`,
+                  target: link.target,
+                  relationship: link.relationship,
+                  candidate_count: outcome.candidates.length,
+                });
               } else {
-                const list = linkWarningsByNote.get(sourceId) ?? [];
-                list.push({
+                pushLinkWarning(sourceId, {
                   code: "unresolved_link",
                   message: `link target "${link.target}" (relationship "${link.relationship}") did not resolve to any note — queued and will backfill automatically if a matching note is created later.`,
                   target: link.target,
                   relationship: link.relationship,
                 });
-                linkWarningsByNote.set(sourceId, list);
               }
             }
           }
+
+          // --- Content-wikilink warnings (vault#570) ---
+          // Same forward-ref-aware timing as the structured-links pass above
+          // — every sibling in this batch exists by now, so a content
+          // `[[wikilink]]` to a later batch item already resolved via the
+          // pending-wikilink backfill (`resolveUnresolvedWikilinks`, run
+          // inside each `store.createNote`/`updateNote` call above).
+          for (const { noteId, content } of contentWikilinkNotes) {
+            for (const warning of getContentWikilinkWarnings(db, noteId, content)) {
+              pushLinkWarning(noteId, warning);
+            }
+          }
         };
         await (batched ? transactionAsync(db, runBatch) : runBatch());
 
@@ -991,9 +1400,12 @@ Response shape (vault#550 — three variants, pick by what you passed):
         // update-note path, which already re-reads post-defaults. The re-read
         // is batched (`getNotes` = one `WHERE id IN (...)`) and skipped
         // entirely when no defaults were applied, so the common no-defaults
-        // path adds zero extra reads.
+        // path adds zero extra reads. `noMutateIds` ("ignore" hits) are
+        // skipped entirely — "ignore" promises zero mutation, including
+        // backfill of a since-added default the existing note predates.
         const mutatedIds = new Set<string>();
         for (const note of created) {
+          if (noMutateIds.has(note.id)) continue;
           if (note.tags && note.tags.length > 0) {
             for (const id of await applySchemaDefaults(store, db, [note.id], note.tags)) {
               mutatedIds.add(id);
@@ -1014,14 +1426,33 @@ Response shape (vault#550 — three variants, pick by what you passed):
         // applies to this note, against the post-defaults state. Fold in any
         // `unresolved_link` warnings collected above (vault#555) — additive,
         // present only when this note's `links` had a target that didn't
-        // resolve.
+        // resolve. `existed` (vault#555) is attached ONLY for items whose
+        // `if_exists` actually engaged — the default "error" path's response
+        // shape is untouched.
         const final = refreshed.map((n) => {
           const validated = attachValidationStatus(store, db, n);
           const warnings = linkWarningsByNote.get(n.id);
-          return warnings && warnings.length > 0
-            ? ({ ...validated, warnings } as Note & { warnings: QueryWarning[] })
-            : validated;
+          const existed = existedMap.get(n.id);
+          let out: Note & { warnings?: QueryWarning[]; existed?: boolean } = validated;
+          if (warnings && warnings.length > 0) out = { ...out, warnings };
+          if (existed !== undefined) out = { ...out, existed };
+          return out;
         });
+
+        // Batch summary (vault#555) — compact shape instead of N full note
+        // objects. Batch-only (a `notes` array); `summary` is ignored on a
+        // single-note call, matching `if_exists`'s per-item batch scoping.
+        if (batch && params.summary === true) {
+          return {
+            created: final.filter((n: any) => n.existed !== true).length,
+            ids: final.map((n) => n.id),
+            // Reserved for future partial-batch-failure reporting — a batch
+            // create is all-or-nothing today (see the tool description), so
+            // this is always empty.
+            failed: [] as unknown[],
+          };
+        }
+
         return batch ? final : final[0];
       },
     },
@@ -1032,7 +1463,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
     {
       name: "update-note",
       requiredVerb: "write",
-      description: `Update one or more notes. Accepts ID or path. Supports content, path, metadata updates plus tag and link mutations.
+      description: `Update one or more notes. Accepts ID, path, or (fallback, only when id/path both miss and exactly one note matches) its H1 title. Supports content, path, metadata updates plus tag and link mutations.
 
 - Three content-modification modes (mutually exclusive):
   - \`content\` — full replace.
@@ -1050,7 +1481,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       inputSchema: {
         type: "object",
         properties: {
-          id: { type: "string", description: "Note ID or path" },
+          id: { type: "string", description: "Note ID, path, or (fallback, only when id/path both miss and exactly one note matches) its H1 title" },
           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." },
@@ -1096,7 +1527,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
                 items: {
                   type: "object",
                   properties: {
-                    target: { type: "string", description: "Target note ID or path" },
+                    target: { type: "string", description: "Target note ID, path, or (fallback) H1 title" },
                     relationship: { type: "string" },
                   },
                   required: ["target", "relationship"],
@@ -1107,14 +1538,14 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
                 items: {
                   type: "object",
                   properties: {
-                    target: { type: "string", description: "Target note ID or path" },
+                    target: { type: "string", description: "Target note ID, path, or (fallback) H1 title" },
                     relationship: { type: "string" },
                   },
                   required: ["target", "relationship"],
                 },
               },
             },
-            description: "Links to add/remove. `add[].target` resolves with the SAME semantics as a [[wikilink]] (vault#555) — ID, then exact path, then basename/title — and lazily backfills (queued) when the target arrives later; the response carries an `unresolved_link` warning naming the target in the meantime, never a silent drop.",
+            description: "Links to add/remove. `add[].target` resolves with the SAME semantics as a [[wikilink]] (vault#555) — ID, then exact path, then basename, then (only on a clean miss, and only when exactly one note matches) an H1-title fallback — and lazily backfills (queued) when the target arrives later; the response carries an `unresolved_link` warning naming the target in the meantime, never a silent drop.",
           },
           include_content: {
             type: "boolean",
@@ -1216,6 +1647,16 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
         const pendingLinks: { sourceId: string; links: { target: string; relationship: string; metadata?: Record<string, unknown> }[] }[] = [];
         // Per-note `unresolved_link` warnings (vault#555 — "never silent").
         const linkWarningsByNote = new Map<string, QueryWarning[]>();
+        const pushLinkWarning = (noteId: string, warning: QueryWarning): void => {
+          const list = linkWarningsByNote.get(noteId) ?? [];
+          list.push(warning);
+          linkWarningsByNote.set(noteId, list);
+        };
+        // Content wikilinks whose note+content pair needs an `unresolved_link`/
+        // `ambiguous_link` warning check (vault#570) — deferred to the same
+        // second pass as `pendingLinks` for the same forward-ref-within-batch
+        // reason.
+        const contentWikilinkNotes: { noteId: string; content: 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.
@@ -1312,6 +1753,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
                 if (linksAdd) {
                   pendingLinks.push({ sourceId: created.id, links: linksAdd });
                 }
+                // Content-wikilink warnings (vault#570) — same deferral as
+                // create-note's fresh-create branch.
+                if (content) {
+                  contentWikilinkNotes.push({ noteId: created.id, content });
+                }
                 const fresh = noteOps.getNote(db, created.id) ?? created;
                 updated.push(fresh);
                 createdIds.add(fresh.id);
@@ -1509,6 +1955,15 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             const hasLinkMutation = (item.links as any)?.add !== undefined
               || (item.links as any)?.remove !== undefined;
 
+            // Content-wikilink warnings (vault#570) gate on the SAME
+            // condition `store.updateNote`/`syncWikilinks` use to decide
+            // whether to re-sync content wikilinks at all — a tags/links-only
+            // update must not spuriously re-warn about pre-existing broken
+            // links this call never touched.
+            const contentChanged = updates.content !== undefined
+              || updates.append !== undefined
+              || updates.prepend !== undefined;
+
             let result: Note;
             if (Object.keys(updates).length > 0 || hasTagMutation || hasLinkMutation) {
               // Write-attribution (vault#298): stamp the most-recent-write
@@ -1562,7 +2017,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             }
 
             // Re-read for final state
-            updated.push(noteOps.getNote(db, note.id) ?? result);
+            const finalNote = noteOps.getNote(db, note.id) ?? result;
+            if (contentChanged) {
+              contentWikilinkNotes.push({ noteId: note.id, content: finalNote.content });
+            }
+            updated.push(finalNote);
           }
 
           // --- Resolve structured `links.add` (vault#555) ---
@@ -1575,21 +2034,35 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           // never silently dropped.
           for (const { sourceId, links } of pendingLinks) {
             for (const link of links) {
-              const targetId = resolveOrQueueLink(db, sourceId, link.target, link.relationship);
-              if (targetId) {
-                await store.createLink(sourceId, targetId, link.relationship, link.metadata);
+              const outcome = resolveOrQueueLink(db, sourceId, link.target, link.relationship);
+              if (outcome.status === "resolved") {
+                await store.createLink(sourceId, outcome.note_id, link.relationship, link.metadata);
+              } else if (outcome.status === "ambiguous") {
+                pushLinkWarning(sourceId, {
+                  code: "ambiguous_link",
+                  message: `link target "${link.target}" (relationship "${link.relationship}") matched ${outcome.candidates.length} notes — ambiguous, no link created. Use a more specific path or the note's ID to disambiguate.`,
+                  target: link.target,
+                  relationship: link.relationship,
+                  candidate_count: outcome.candidates.length,
+                });
               } else {
-                const list = linkWarningsByNote.get(sourceId) ?? [];
-                list.push({
+                pushLinkWarning(sourceId, {
                   code: "unresolved_link",
                   message: `link target "${link.target}" (relationship "${link.relationship}") did not resolve to any note — queued and will backfill automatically if a matching note is created later.`,
                   target: link.target,
                   relationship: link.relationship,
                 });
-                linkWarningsByNote.set(sourceId, list);
               }
             }
           }
+
+          // --- Content-wikilink warnings (vault#570) ---
+          // Same forward-ref-aware timing as the structured-links pass above.
+          for (const { noteId, content } of contentWikilinkNotes) {
+            for (const warning of getContentWikilinkWarnings(db, noteId, content)) {
+              pushLinkWarning(noteId, warning);
+            }
+          }
         };
         await (batched ? transactionAsync(db, runBatch) : runBatch());
 
@@ -1647,11 +2120,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       // genuinely append-only callers — gating WITHIN write rather
       // than promoting deletes out of it.
       requiredVerb: "write",
-      description: "Permanently delete a note and all its tags and links. Accepts ID or path.",
+      description: "Permanently delete a note and all its tags and links. Accepts ID, path, or (fallback, only when id/path both miss and exactly one note matches) its H1 title.",
       inputSchema: {
         type: "object",
         properties: {
-          id: { type: "string", description: "Note ID or path" },
+          id: { type: "string", description: "Note ID, path, or (fallback, only when id/path both miss and exactly one note matches) its H1 title" },
         },
         required: ["id"],
       },
@@ -1668,7 +2141,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "list-tags",
       requiredVerb: "read",
-      description: `List tags with usage counts. Each row carries \`count\` (notes carrying the EXACT tag) and \`expanded_count\` (vault#550 — distinct notes matching the tag OR any transitive descendant under the default subtypes expansion; use this to see a parent tag's true rollup when its notes are actually tagged with a more specific child). Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps) — errors with \`error_type: "tag_not_found"\` (plus a \`did_you_mean\` hint when a close match exists) if the tag has no identity row and no notes. Pass \`include_schema: true\` to include the full record for every tag.`,
+      description: `List tags with usage counts. Each row carries \`count\` (notes carrying the EXACT tag) and \`expanded_count\` (vault#550 — distinct notes matching the tag OR any transitive descendant under the default subtypes expansion; use this to see a parent tag's true rollup when its notes are actually tagged with a more specific child). Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps) — errors with \`error_type: "tag_not_found"\` (plus a \`did_you_mean\` hint when a close match exists) if the tag has no identity row and no notes. Pass \`include_schema: true\` to include the full record for every tag. NOTE (vault#555): this list includes zero-membership tags (\`count: 0\` — a declared schema never yet applied, or a tag every note was since untagged from), so its length can run higher than \`vault-info\`'s stats \`tagCount\`, which counts only tags at least one note currently carries.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -1743,7 +2216,14 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     // =====================================================================
     {
       name: "update-tag",
-      requiredVerb: "write",
+      // `admin` (was `write`) — this PR: update-tag defines a tag's SCHEMA
+      // (description, indexed-field types, relationship vocabulary,
+      // hierarchy parents), which every note carrying the tag inherits.
+      // That's structure/taxonomy curation, not content authorship — the
+      // same distinction that keeps content out of admin and structure out
+      // of write. See the `generateMcpTools` doc comment above for the full
+      // re-tier rationale + BREAKING note.
+      requiredVerb: "admin",
       description: "Create or update a tag's identity row: description, indexed-field schemas, relationship-vocabulary map, 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-vault/docs/contracts/tag-data-model.md.",
       inputSchema: {
         type: "object",
@@ -1756,11 +2236,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             additionalProperties: {
               type: "object",
               properties: {
-                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object — all six are accepted for storage + advisory validation; any OTHER value is rejected outright (error_type invalid_field_type, vault#555 — bundled with every other violation in the same call, see the `update-tag` tool description). Only string/integer/boolean are INDEXABLE (see `indexed` below); declaring `indexed: true` with number/array/object is rejected (unsupported_indexed_type / invalid_indexed_field)." },
+                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object, reference — all seven are accepted for storage + advisory validation; any OTHER value is rejected outright (error_type invalid_field_type, vault#555 — bundled with every other violation in the same call, see the `update-tag` tool description). Only string/integer/boolean/reference are INDEXABLE (see `indexed` below); declaring `indexed: true` with number/array/object is rejected (unsupported_indexed_type / invalid_indexed_field). `reference` is a DUAL-WRITE type (typed-reference-field): the value is stored + validated exactly like `string` (pass a note id, path, or title), AND create-note/update-note additionally resolve that value to a note and maintain a graph `links` edge from this note to it, with `relationship` set to the field name — kept in sync on every write that changes the field (a new value re-points the link; clearing the field drops it). A target that doesn't resolve yet is queued and backfills automatically, same as a structured `links` entry — see `docs/design/typed-reference-field.md`." },
                 description: { type: "string" },
                 enum: { type: "array", items: { type: "string" }, description: "Allowed values. Does NOT auto-backfill — a note that omits this field stays without it unless `default` is also set (vault#553; the pre-0.7.0 behavior of silently defaulting to the first enum value is retired). Set `default` explicitly if you want backfill." },
                 default: { description: "Explicit backfill value (vault#553) applied when a note gains this tag without setting the field. Must conform to this field's own `type` (and `enum`, if declared) — a non-conforming default is rejected (invalid_default / invalid_field_default) rather than silently stored. Omit entirely to leave the field ABSENT (not backfilled) on notes that don't set it — this is what makes `exists:false` a trustworthy \"never set\" query." },
-                indexed: { type: "boolean", description: "When true, a generated column + index are maintained on notes.metadata.<field>, making it queryable via metadata operator objects and order_by. Global: all tags declaring the field must agree on both type and indexed. Only string/integer/boolean are indexable. Indexed ⇒ a type-mismatched write is HARD-REJECTED (schema_validation), not just warned — vault#553." },
+                indexed: { type: "boolean", description: "When true, a generated column + index are maintained on notes.metadata.<field>, making it queryable via metadata operator objects and order_by. Global: all tags declaring the field must agree on both type and indexed. Only string/integer/boolean/reference are indexable. Indexed ⇒ a type-mismatched write is HARD-REJECTED (schema_validation), not just warned — vault#553." },
                 strict: { type: "boolean", description: "vault#299. Default false (advisory). When true, ALL of this field's declared constraints (type + enum + required + cardinality) are ENFORCED — a violating write is rejected with a schema_validation error, not just warned. All-or-nothing per field; free-form fields on a strict tag simply leave strict off. Note: `indexed: true` fields enforce their TYPE constraint regardless of this flag (vault#553)." },
                 required: { type: "boolean", description: "vault#299. The field must be present + non-null on a note with this tag. Advisory unless `strict: true`." },
                 cardinality: { type: "string", enum: ["one", "many"], description: "vault#299. 'one' (scalar, default) or 'many' (array). Advisory unless `strict: true`." },
@@ -1879,11 +2359,16 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     // =====================================================================
     {
       name: "delete-tag",
-      // `write` — Aaron's call 2026-05-27: admin reserved for token
-      // mgmt + future config writes; deletes are write-tier mutations.
-      // See delete-note rationale.
-      requiredVerb: "write",
-      description: "Delete a tag, remove it from all notes, and delete its schema. Notes themselves are NOT deleted — just untagged. Refused with error_type \"tag_referenced_as_parent\" (vault#552) when another tag's parent_names still names this one — pass cascade OR detach (either — both mean the same thing: strip the stale reference from the referencing tag(s)' parent_names, never delete them) to proceed anyway.",
+      // `admin` (was `write` — Aaron's 2026-05-27 call reserved admin for
+      // token mgmt + future config writes; deletes were write-tier
+      // mutations, see delete-note's rationale). Superseded by this PR:
+      // delete-tag removes a tag's identity row + schema and untags it
+      // vault-wide — that's structure/taxonomy curation, the same class as
+      // update-tag/rename-tag/merge-tags, not content authorship. See the
+      // `generateMcpTools` doc comment above for the full re-tier rationale
+      // + BREAKING note.
+      requiredVerb: "admin",
+      description: "Delete a tag, remove it from all notes, and delete its schema. Notes themselves are NOT deleted — just untagged. Refused with error_type \"tag_referenced_as_parent\" (vault#552) when another tag's parent_names still names this one — pass cascade OR detach (either — both mean the same thing: strip the stale reference from the referencing tag(s)' parent_names, never delete them) to proceed anyway. Also refused with error_type \"tag_in_use_by_tokens\" (vault#555 fix — this case existed pre-#555 but was undocumented here; see \"merge-tags\" for the identical guard) when the tag is referenced by a tag-scoped token's allowlist — revoke or re-mint the token(s) first. A no-op on a tag with no identity row and no notes returns {deleted: false, notes_untagged: 0} rather than erroring.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1917,7 +2402,13 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     // =====================================================================
     {
       name: "rename-tag",
-      requiredVerb: "write",
+      // `admin` (was `write`) — this PR: an atomic cascading rename across
+      // note memberships, other tags' parent_names, tokens' allowlists,
+      // indexed-field declarer lists, and inline #tag mentions is structural
+      // taxonomy surgery, not content authorship. Same tier as
+      // update-tag/delete-tag/merge-tags. See the `generateMcpTools` doc
+      // comment above for the full re-tier rationale + BREAKING note.
+      requiredVerb: "admin",
       description:
         "Atomically rename a tag across EVERY surface that references it: note memberships, OTHER tags' parent_names, tag-scoped tokens' allowlists, indexed-field declarer lists, inline #tag mentions in note bodies, and _tags/<name> config-note paths — all in one transaction. THIS is the fix for the manual retag→delete dance (create the new tag, retag notes, delete the old one): that dance silently orphans parent_names references (the renamed-away tag stays a live query surface via subtype expansion while list-tags reports it at count 0, and the new tag misses every child-tagged note) and leaves stale #tag mentions behind. Sub-tags rename recursively — renaming \"task\" to \"todo\" also renames \"task/work\" to \"todo/work\". Does NOT rewrite metadata values that happen to equal the old tag name (e.g. metadata.epic: \"task\") — that's a distinct drift class the doctor tool's dead_tag_metadata_reference finding flags heuristically; rename-tag's job is structural (tags/note_tags/parent_names/tokens/content), not a blind string search-and-replace over arbitrary metadata.",
       inputSchema: {
@@ -1974,7 +2465,12 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     // =====================================================================
     {
       name: "merge-tags",
-      requiredVerb: "write",
+      // `admin` (was `write`) — this PR: merging N source tags into a
+      // target (retagging every note, dropping the sources' identity rows)
+      // is structural taxonomy surgery, not content authorship. Same tier
+      // as update-tag/delete-tag/rename-tag. See the `generateMcpTools` doc
+      // comment above for the full re-tier rationale + BREAKING note.
+      requiredVerb: "admin",
       description:
         "Atomically merge one or more source tags into a target tag: every note carrying any source is retagged with the target, then the source tags (and their identity rows — description/fields/relationships/parent_names) are dropped. target is created if it doesn't exist yet; target's own schema is preserved (sources' schemas are consumed, not merged field-by-field). Sources that don't exist are reported at count 0. Refused with error_type \"tag_in_use_by_tokens\" if a source is referenced by a tag-scoped token — revoke or re-mint it first.",
       inputSchema: {
@@ -2010,12 +2506,12 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "find-path",
       requiredVerb: "read",
-      description: "Find the shortest path between two notes in the link graph. Accepts IDs or paths. Returns null if no path exists, else `{path, relationships, nodes, edges}`: `path` (note IDs, source→target) and `relationships` (relationships[i] connects path[i] to path[i+1]) are the original id-only shape; `nodes` (vault#550, additive) hydrates each id in `path` with the note's own `path` field — `[{id, path}]` in the same order; `edges` (additive) is the self-contained hop list — `[{source, target, relationship, sourcePath, targetPath}]` — for rendering the chain without cross-referencing `nodes`.",
+      description: "Find the shortest path between two notes in the link graph. Accepts IDs, paths, or (fallback, only when id/path both miss and exactly one note matches) H1 titles. Returns null if no path exists, else `{path, relationships, nodes, edges}`: `path` (note IDs, source→target) and `relationships` (relationships[i] connects path[i] to path[i+1]) are the original id-only shape; `nodes` (vault#550, additive) hydrates each id in `path` with the note's own `path` field — `[{id, path}]` in the same order; `edges` (additive) is the self-contained hop list — `[{source, target, relationship, sourcePath, targetPath}]` — for rendering the chain without cross-referencing `nodes`.",
       inputSchema: {
         type: "object",
         properties: {
-          source: { type: "string", description: "Starting note ID or path" },
-          target: { type: "string", description: "Destination note ID or path" },
+          source: { type: "string", description: "Starting note ID, path, or (fallback) H1 title" },
+          target: { type: "string", description: "Destination note ID, path, or (fallback) H1 title" },
           max_depth: { type: "number", description: "Max path length (default 5)" },
         },
         required: ["source", "target"],
@@ -2035,11 +2531,15 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "vault-info",
       // `read` so vault:read callers can fetch stats. The
-      // description-update branch performs an inner write-check (see
+      // description-update branch performs an inner ADMIN-check (see
       // overrideVaultInfo in src/mcp-tools.ts) — do not promote this to
-      // `write` or read-only callers lose the stats projection.
+      // `admin` or read-only callers lose the stats projection. Was an
+      // inner write-check pre-this-PR; writing the vault's own
+      // description/config is curation, not content, so it moved to the
+      // same admin tier as the other structure-curation tools (update-tag
+      // et al) — see the `generateMcpTools` doc comment above.
       requiredVerb: "read",
-      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.",
+      description: "Get a comprehensive vault projection: name, description, `coordinates` (this vault's own REST/MCP URL templates — `{name, base_url, rest_api, mcp}`, always present), tags-with-schemas (own + effective parents/fields per #270 inheritance), indexed metadata fields catalog, query hints, `map` (front-door structural orientation, always present — see below), and (when a seeded onboarding guide exists) a `getting_started` note pointer. Pass `include_stats: true` to add note/tag/link counts and the monthly distribution as a `stats` field. Pass `description` to update the vault description (changes how AI agents behave in future sessions) — requires the `vault:admin` scope for this vault even though the tool itself is read-gated (vault#555 originally required `vault:write` here; a later PR tightened it to `vault:admin` since a description edit is curation, not content — a `vault:read`-or-`vault:write`-only caller passing `description` gets a `Forbidden` rejection, not a silent no-op). Call this anytime mid-session to refresh schema context. NOTE (vault#555): the stats `tagCount` counts only tags at least one note currently carries (`COUNT(DISTINCT tag_name)` over note-tag memberships) — `list-tags`'s row count can run higher because it also lists zero-membership tags (an identity row from a declared schema or a since-untagged tag). Neither is wrong; they answer different questions. `map` — `{ total_notes, tags: [{name, count}], path_buckets: [{name, count}], unfiled_notes }` — is a compact, counts-only structural rollup (no content) meant to orient a fresh reader in this ONE call, no `include_stats` needed: every tag currently in use with its membership count, and every top-level path segment (the text before the first `/`) with how many notes live under it, plus how many notes carry no path at all. For a tag-scoped token, `map.tags`/`map.path_buckets`/`map.total_notes`/`map.unfiled_notes` cover only notes reachable through an in-scope tag — same confidentiality posture as the `tags`/`indexed_fields` catalogs above.",
       inputSchema: {
         type: "object",
         properties: {
@@ -2095,11 +2595,19 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     // =====================================================================
     {
       name: "doctor",
-      // `admin` — same tier as prune-schema: a diagnostic over the WHOLE
-      // vault's taxonomy, not scoped to any one tag's write authority.
-      requiredVerb: "admin",
+      // `read` (was `admin` — the original reasoning: same tier as
+      // prune-schema, a diagnostic over the WHOLE vault's taxonomy, not
+      // scoped to any one tag's write authority). Superseded by this PR:
+      // doctor never mutates and is ALREADY tag-scope-restricted at the MCP
+      // layer (see `applyTagScopeWrappers`'s `doctor` wrapper in
+      // src/mcp-tools.ts, which re-runs the scan against the caller's
+      // allowlist) — it's a read, not a curation op, and read-scoped
+      // monitoring/tending jobs need to be able to run it without an admin
+      // credential. The REST `GET /api/doctor` endpoint (routing.ts) is
+      // re-tiered to `read` too, so both doors agree — no MCP/REST divergence.
+      requiredVerb: "read",
       description:
-        "Read-only integrity scan across the tag/metadata taxonomy — run this after any bulk tag reorg (rename/merge/delete/subtree move) to confirm nothing leaked. Reports, per finding, {type, severity, subject, detail, remedy} — NEVER auto-fixes; apply the suggested remedy (usually rename-tag/merge-tags/update-tag/prune-schema) yourself. Finding types: dangling_parent_name (a parent_names entry naming a tag with no identity row), parent_names_cycle (a tag reaching itself through its ancestor chain — traversal tolerates this, but it's dishonest hierarchy state), mixed_type_indexed_field (a note's metadata value for an indexed field has a JSON type disagreeing with the field's declared storage type — the ordering/filtering-goes-silently-wrong precursor), orphaned_indexed_field_declarer (an indexed field naming a dead declarer tag — see prune-schema), and dead_tag_metadata_reference (HEURISTIC, always carries heuristic:true — a metadata value that looks like a stale reference to a renamed/merged/deleted tag, inferred from sibling notes using the same metadata key with values that ARE live tags; can never be certain since vault keeps no tag-rename history).",
+        "Read-only integrity scan across the tag/metadata taxonomy — run this after any bulk tag reorg (rename/merge/delete/subtree move) to confirm nothing leaked. Returns {findings, summary, scanned_at} — findings is an array, each entry {type, severity, subject, detail, remedy} — NEVER auto-fixes; apply the suggested remedy (usually rename-tag/merge-tags/update-tag/prune-schema) yourself. Finding types: dangling_parent_name (a parent_names entry naming a tag with no identity row), parent_names_cycle (a tag reaching itself through its ancestor chain — traversal tolerates this, but it's dishonest hierarchy state), mixed_type_indexed_field (a note's metadata value for an indexed field has a JSON type disagreeing with the field's declared storage type — the ordering/filtering-goes-silently-wrong precursor), orphaned_indexed_field_declarer (an indexed field naming a dead declarer tag — see prune-schema), and dead_tag_metadata_reference (HEURISTIC, always carries heuristic:true — a metadata value that looks like a stale reference to a renamed/merged/deleted tag, inferred from sibling notes using the same metadata key with values that ARE live tags; can never be certain since vault keeps no tag-rename history).",
       inputSchema: { type: "object", properties: {} },
       execute: async () => {
         return await store.doctor();