@openparachute/vault 0.4.3 → 0.4.4-rc.12

package/README.md

@@ -139,7 +139,7 @@ Password and 2FA secrets live in `~/.parachute/vault/config.yaml` at mode 0600 (
 
 Where `{name}` is `default` on a fresh install, or whatever vault you pointed `vault init` at. **First MCP call after `vault init` requires no browser handoff — Claude Code uses the baked-in token and the vault's tools show up in your next session.** This is intentional: for an owner connecting their own machine's vault to their own Claude Code, the token is already there and OAuth would add friction.
 
-To re-point Claude Code at a different vault, change `default_vault` in `~/.parachute/vault/config.yaml` and re-run `parachute-vault init` — which re-mints an API token and re-writes the `~/.claude.json` entry end-to-end. To rotate the token only, edit `~/.claude.json` and replace the `Authorization` header value with a fresh token from `parachute-vault tokens create`. (Running `parachute-vault mcp-install` on its own overwrites the MCP entry *without* an `Authorization` header and is intended for the rare case where you want to drop the token and connect via OAuth instead.)
+To re-point Claude Code at a different vault, change `default_vault` in `~/.parachute/vault/config.yaml` and re-run `parachute-vault init` — which re-mints an API token and re-writes the `~/.claude.json` entry end-to-end. To rotate the token only, run `parachute-vault mcp-install` (defaults to `--mint`, which mints a fresh scope-narrow hub JWT via `~/.parachute/operator.token` and writes it into `~/.claude.json` with an `Authorization: Bearer …` header). See the [cookbook](#install-vault-mcp-into-a-client-config) section below for the full flag surface — token paste, scope narrowing, project-level install, multi-vault.
 
 ### Claude Desktop (OAuth)
 
@@ -190,7 +190,13 @@ parachute-vault uninstall --yes --wipe     # scripted destructive wipe (prints a
 parachute-vault create work                # create a new vault
 parachute-vault list                       # list all vaults (alias: `ls`)
 parachute-vault remove work --yes          # delete a vault (alias: `rm`)
-parachute-vault mcp-install                # (re)write the ~/.claude.json MCP entry for the default vault
+parachute-vault mcp-install                # (re)write the MCP client entry; defaults to --mint (hub-issued JWT) at local scope
+parachute-vault mcp-install --token <t>    # paste an existing bearer instead of minting
+parachute-vault mcp-install --legacy-pat   # mint a vault-DB pvt_* (self-hosted-without-hub)
+parachute-vault mcp-install --install-scope user      # write ~/.claude.json top-level (every project)
+parachute-vault mcp-install --install-scope local     # write ~/.claude.json projects[<cwd>] (this directory only — default)
+parachute-vault mcp-install --install-scope project   # write ./.mcp.json (checked into the repo)
+parachute-vault mcp-install --vault work   # target the "work" vault (keyed as parachute-vault-work)
 
 # OAuth — owner password + 2FA
 parachute-vault set-password               # set/change the owner password (OAuth consent page)
@@ -565,6 +571,56 @@ Atomic at the SQL layer: two concurrent appends both land in some order, never c
 
 The shortest path to a public HTTPS URL for a vault you control — useful for SSG rebuilds running on GitHub Actions, Vercel, or any runner that isn't on your tailnet. See [Remote access via Tailscale Funnel](#remote-access-via-tailscale-funnel) below for the full setup.
 
+### Install vault MCP into a client config
+
+Bare `parachute-vault mcp-install` from a terminal **walks you through a short contextual conversation** — picks defaults informed by your environment (how many vaults you have, whether the hub is reachable, whether you're in a project directory, whether vault is already installed somewhere), shows the JSON shape it will write before doing anything, and asks before each non-obvious choice. The patterns below are the non-interactive shapes — pass any flag (`--mint`, `--token`, `--scope`, `--install-scope`, `--vault`, `--legacy-pat`) and the walkthrough is skipped.
+
+#### Install scopes
+
+`--install-scope` accepts three values, matching Claude Code's own `claude mcp add --scope`:
+
+| Scope | Where the entry lives | Visibility |
+|---|---|---|
+| `local` *(default)* | `~/.claude.json` under `projects[<absolute-cwd>].mcpServers` | private to your machine, scoped to this directory |
+| `user` | `~/.claude.json` top-level `mcpServers` | every project, every directory on this machine |
+| `project` | `<cwd>/.mcp.json` | checked into the repo, shared with anyone who clones it |
+
+The default is **`local`** — Claude Code only loads the entry when launched from the directory you ran the install from. Pick `user` for a global install (every project sees the vault); pick `project` to commit the entry to the repo so collaborators get it on `git pull`.
+
+#### Cookbook
+
+```bash
+# 1. Default — mint a scope-narrow hub JWT (vault:<vault>:read) via your
+#    operator token; write it into ~/.claude.json under projects[<cwd>]
+#    (local scope, this directory only). Requires:
+#      - ~/.parachute/operator.token (run `parachute auth rotate-operator` if missing)
+#      - PARACHUTE_HUB_ORIGIN set OR an active `parachute expose` session
+parachute-vault mcp-install --mint
+
+# 2. Global install — write the entry at top-level ~/.claude.json so
+#    Claude Code loads it from every project, every directory.
+parachute-vault mcp-install --install-scope user
+
+# 3. Project-level install — write ./.mcp.json (committed to the repo,
+#    shared with the team). Pair with --scope vault:write when the
+#    project actually mutates the vault.
+parachute-vault mcp-install --install-scope project --scope vault:write
+
+# 4. Paste an existing token — useful when you already have a pvt_* in hand
+#    or want to re-use a long-lived bearer from another machine. Skips the
+#    mint step entirely.
+parachute-vault mcp-install --token pvt_abc123...
+
+# 5. Self-hosted-without-hub — mint a vault-DB pvt_* token (the legacy
+#    path; preserved so deployments without a hub keep working). Prints a
+#    deprecation notice.
+parachute-vault mcp-install --legacy-pat
+```
+
+**Multi-vault.** `--vault <name>` targets a specific vault and writes the entry under `parachute-vault-<name>` so multiple vaults coexist. Without `--vault`, the singular `parachute-vault` slot is used and one install clobbers another — that's intentional for the common single-vault case.
+
+**Doctor.** `parachute-vault doctor` checks `~/.claude.json` (both top-level and `projects[<cwd>]`) and `./.mcp.json`, and reports which one holds the entry, plus port-match and reachability of the MCP URL.
+
 ## Data model
 
 ```

package/core/src/core.test.ts

@@ -3678,6 +3678,238 @@ describe("schema validation (tags.fields)", async () => {
     const result = await create.execute({ content: "x", tags: ["task"] }) as any;
     expect(result.validation_status).toBeUndefined();
   });
+
+  // vault#310 — integer type validation. JSON has no separate integer
+  // type, so a JSON number with zero fractional part (`5`, `5.0`) must
+  // pass an `integer`-typed field. Pre-fix, the validator had no
+  // `"integer"` case at all — falling through the switch returned
+  // undefined and every integer-typed field warned `type_mismatch` on
+  // legitimate values. Gitcoin Brain's drift detector emits JSON for
+  // diffs; every `kpi: 3` triggered the false-positive and buried the
+  // real warnings.
+
+  it("integer-typed field: JSON integer (5) passes (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5 },
+    }) as any;
+    expect(result.validation_status?.warnings ?? []).toEqual([]);
+  });
+
+  it("integer-typed field: JSON `5.0` (zero-fractional) passes (vault#310)", async () => {
+    // 5.0 is the canonical Gitcoin shape — JSON.parse decodes the
+    // emitted JSON number as a JS Number; the JS Number for `5.0` is
+    // identical to `5` so Number.isInteger reports true. This is the
+    // load-bearing assertion for the Gitcoin drift-detector use case.
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5.0 },
+    }) as any;
+    expect(result.validation_status?.warnings ?? []).toEqual([]);
+  });
+
+  it("integer-typed field: JSON `5.5` (non-zero fractional) warns type_mismatch (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5.5 },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+    expect(result.validation_status.warnings[0].field).toBe("count");
+  });
+
+  it("integer-typed field: string `\"5\"` warns type_mismatch (no string→number coercion) (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: "5" },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+  });
+
+  it("integer-typed field: edge `5.0000000000001` warns type_mismatch (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5.0000000000001 },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+  });
+
+  it("integer-typed field: boolean warns type_mismatch (vault#310)", async () => {
+    // Pin that boolean is rejected (Number.isInteger(true) returns
+    // false, but extra coverage in case anyone "improves" the check
+    // with a looser predicate later).
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: true },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+  });
+
+  // Note on NaN/Infinity: those values pass through
+  // JSON.stringify as `null`, then the validator's null short-circuit
+  // (schema-defaults.ts:327 — "value === null → skip") filters them out
+  // before reaching the type check. We can't observe them in
+  // validation_status from this layer; a dedicated unit test against
+  // `valueMatchesType` would catch the case at the inner boundary.
+  // Pinned at the next layer down:
+
+  it("valueMatchesType('integer', ...) rejects NaN / Infinity (vault#310)", async () => {
+    // Reach the unexported helper indirectly via validateNote on a
+    // hand-built resolved-schemas + metadata where the value is the
+    // actual NaN/Infinity (no JSON round-trip).
+    const { validateNote, loadSchemaConfig } = await import("./schema-defaults.js");
+    // Seed via the public surface, then load the resolved schemas
+    // snapshot.
+    await store.upsertTagSchema("k", { fields: { c: { type: "integer" } } });
+    const resolved = loadSchemaConfig((store as any).db);
+    expect(validateNote(resolved, { tags: ["k"], metadata: { c: Number.NaN } })?.warnings[0]?.reason)
+      .toBe("type_mismatch");
+    expect(validateNote(resolved, { tags: ["k"], metadata: { c: Number.POSITIVE_INFINITY } })?.warnings[0]?.reason)
+      .toBe("type_mismatch");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// update-note `if_missing: "create"` — idempotent upsert (vault#309)
+// ---------------------------------------------------------------------------
+
+describe("update-note if_missing=create (vault#309)", async () => {
+  let store: SqliteStore;
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("creates the note when missing + carries created: true", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: "Inbox/2026-05-13-meeting",
+      content: "agenda body",
+      tags: ["meeting"],
+      metadata: { priority: "high" },
+      if_missing: "create",
+    }) as any;
+    expect(result.created).toBe(true);
+    expect(result.path).toBe("Inbox/2026-05-13-meeting");
+    expect(result.content).toBe("agenda body");
+    expect(result.tags).toContain("meeting");
+    expect(result.metadata?.priority).toBe("high");
+
+    // And the row landed.
+    const fetched = await store.getNoteByPath("Inbox/2026-05-13-meeting");
+    expect(fetched).not.toBeNull();
+  });
+
+  it("updates the note when present + carries created: false", async () => {
+    await store.createNote("original", { path: "p", metadata: { v: 1 } });
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: "p",
+      content: "updated body",
+      metadata: { v: 2 },
+      if_missing: "create",
+      force: true, // bypass OC since this is an unconditional update
+    }) as any;
+    expect(result.created).toBe(false);
+    expect(result.content).toBe("updated body");
+    expect(result.metadata?.v).toBe(2);
+  });
+
+  it("without if_missing, missing note errors (current behavior — back-compat)", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    await expect(update.execute({
+      id: "nope",
+      content: "x",
+      force: true,
+    })).rejects.toThrow(/Note not found/);
+  });
+
+  it("create branch applies tag-schema defaults when the new tag declares fields", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: "Inbox/new-task",
+      content: "do the thing",
+      tags: ["task"],
+      if_missing: "create",
+    }) as any;
+    expect(result.created).toBe(true);
+    // Schema defaults populated metadata.priority on insert.
+    expect(result.metadata?.priority).toBeDefined();
+  });
+
+  it("create branch surfaces validation warnings just like create-note", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: "Inbox/bad-task",
+      content: "x",
+      tags: ["task"],
+      metadata: { priority: "ULTRA" },
+      if_missing: "create",
+    }) as any;
+    expect(result.created).toBe(true);
+    expect(result.validation_status?.warnings?.[0]?.reason).toBe("enum_mismatch");
+  });
+
+  it("idempotent: second call with same id + same content updates without error", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const first = await update.execute({
+      id: "Inbox/sync-target",
+      content: "v1",
+      if_missing: "create",
+    }) as any;
+    expect(first.created).toBe(true);
+
+    const second = await update.execute({
+      id: "Inbox/sync-target",
+      content: "v2",
+      if_missing: "create",
+      force: true,
+    }) as any;
+    expect(second.created).toBe(false);
+    expect(second.content).toBe("v2");
+
+    // Only one row exists.
+    const all = await store.queryNotes({ limit: 100 });
+    expect(all.filter((n) => n.path === "Inbox/sync-target")).toHaveLength(1);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/core/src/mcp.ts

@@ -469,6 +469,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 - 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).
+- **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",
@@ -491,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: {
@@ -554,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" },
               },
@@ -572,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.
@@ -581,7 +589,87 @@ 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` 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".)
+              //   - `links.remove` is also ignored on create (nothing
+              //     to remove on a fresh note).
+              //   - `links.add` IS applied below — the drift sync can
+              //     declare typed links at upsert time and have them
+              //     materialize alongside the create. See vault#320
+              //     reviewer F1 — the prior comment claimed all
+              //     `links` were ignored, but `links.add` was already
+              //     processed and used by Gitcoin's sync; the
+              //     misleading wording is fixed here so a future
+              //     reader doesn't trust it and break the workflow.
+              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;
@@ -745,14 +833,21 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         // 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.
+        // `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);
-          if (includeContent) return validated;
+          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];
@@ -1127,8 +1222,13 @@ function defaultForField(field: { type: string; enum?: string[] }): unknown {
  *
  * Returns the note unchanged when no tag declares fields, so callers
  * without any tag schemas 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 {
+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({