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

package/core/src/onboarding.ts

@@ -91,6 +91,48 @@ schemas.** Start minimal — invent tags as real notes need them, declare a
 schema only when a query demands it. Over-designing an empty vault is the
 common mistake.
 
+Declaring a schema is one \`update-tag\` call — the \`fields\` object maps each
+field name to \`{ type, enum?, indexed? }\` (\`type\` is \`"string"\`, \`"boolean"\`,
+or \`"integer"\`):
+
+\`\`\`
+update-tag {
+  tag: "meeting",
+  description: "A meeting with notes",
+  fields: {
+    held_on: { type: "string", indexed: true },              // queryable with operators
+    status:  { type: "string", enum: ["scheduled", "done"] }, // first enum value is the default
+    rating:  { type: "integer" }
+  }
+}
+\`\`\`
+
+\`fields\` is **merged** (new keys added, existing replaced); \`parent_names\` and
+\`relationships\` are replaced wholesale when passed. Only \`indexed: true\` fields
+support operator queries (\`metadata: { held_on: { gte: "..." } }\`) and
+\`order_by\`; all tags declaring the same field must agree on its \`type\` and
+\`indexed\` flag.
+
+## Write gotchas
+
+A few behaviors worth knowing before you write at scale:
+
+- **\`update-note\` requires optimistic concurrency by default.** Pass
+  \`if_updated_at\` with the \`updated_at\` you last read; a mismatch returns a
+  conflict error (re-read, reconcile, retry). For bulk/scripted writes where
+  concurrency is known-safe, pass \`force: true\` to waive the *requirement to
+  supply* it. \`append\`/\`prepend\`-only updates are exempt (no-conflict-by-design).
+- **A schema field's default is filled in on write, so it shows up even when you
+  didn't set it.** When a note gets a tag whose schema declares a field, the
+  missing field is back-filled: an \`enum\` field → its **first listed value**, an
+  \`integer\` → \`0\`, a \`boolean\` → \`false\`, a plain string → \`""\`. So a
+  \`rating: { type: "integer" }\` reads as \`0\` on notes nobody rated — that \`0\`
+  is "unset," not "rated zero." Order an \`enum\`'s values so the first is a sane
+  default, and don't read a back-filled \`0\`/\`""\`/\`false\` as a real value.
+- **Validation is advisory, never blocking.** A type/enum mismatch comes back as
+  a \`validation_status\` warning on the write response — the write still lands.
+  Read those warnings and self-correct on the next turn.
+
 (Full design guide, with copy-paste examples: https://parachute.computer/scripting/)
 
 ## Importing existing notes
@@ -146,6 +188,17 @@ single-purpose tool. This note is a living starter for building one *with the
 operator*. Update it as you settle on a stack, conventions, or a deployed
 surface for this vault.
 
+## ⚠️ Build a surface in your editor, not from this session
+
+A surface runs **in a browser**: it needs a real OAuth round-trip (a redirect to
+the hub's consent screen and back), a dev server to serve the app, and a CORS
+origin the hub trusts. **None of that exists in this MCP/chat session** — there's
+no browser, no redirect, no dev server. So **don't try to "run" a surface from
+the vault session.** Build it in **Claude Code (or your editor)** against a local
+dev server (\`vite\`/\`bun dev\`), sign in through the browser there, and iterate.
+From *this* session you design the vault structure the surface will consume and
+write the code — you can't exercise the OAuth/render loop here.
+
 ## Don't hand-roll the plumbing
 
 Two published packages do the heavy lifting — import them instead of writing
@@ -158,10 +211,72 @@ OAuth, the vault API client, or note rendering by hand:
   content (Markdown, wikilinks, embeds) the way the rest of the ecosystem does,
   so your surface looks native without re-implementing the renderer.
 
+## Minimal end-to-end (config → sign-in → query → render)
+
+A React sketch wiring all four steps. \`createVaultSurface\` is the only required
+config (its \`clientName\` is the sole required option; \`hubUrl\` defaults to the
+page origin, \`vaultName\` to \`"default"\`, \`scope\` to \`"vault:read vault:write"\`).
+\`getClient()\` returns a \`VaultClient\` (or \`null\` until signed in) whose
+\`queryNotes()\` takes the same query grammar you use over MCP. See
+[[Getting Started]] / \`vault-info\` for this vault's NAME and hub origin.
+
+\`\`\`tsx
+import { useEffect, useState } from "react";
+import { createVaultSurface, type Note } from "@openparachute/surface-client";
+import { NoteRenderer } from "@openparachute/surface-render";
+
+// One surface per (hub, vault) config. clientName shows on the consent screen.
+const surface = createVaultSurface({
+  clientName: "My Vault Surface",
+  hubUrl: "https://your-hub.example",   // omit to default to window.location.origin
+  vaultName: "default",                 // this vault's name (see vault-info)
+});
+
+export function App() {
+  const [notes, setNotes] = useState<Note[] | null>(null);
+
+  useEffect(() => {
+    (async () => {
+      // OAuth: finish a redirect callback if we're on it, else send the browser
+      // off to sign in. handleCallback() needs BOTH code + state, so guard on
+      // both. (Real apps route /oauth/callback to its own component.)
+      const q = new URLSearchParams(location.search);
+      if (q.get("code") && q.get("state")) await surface.handleCallback();
+      // getClient() builds a FRESH VaultClient on each call — fine here (one-shot
+      // effect); in a real component keep it in state/ref, don't call it per render.
+      const client = surface.getClient(); // VaultClient | null (null = not signed in)
+      if (!client) return void surface.login();
+      setNotes(await client.queryNotes({ tag: "note", limit: 20 }));
+    })();
+  }, []);
+
+  if (!notes) return <p>Connecting…</p>;
+  return (
+    <>
+      {notes.map((n) => (
+        // resolve maps a [[wikilink]] target → { href, exists } (or null = inert).
+        // You own this href's trust boundary — keep it a fragment (or validate the
+        // target). Don't build a raw passthrough href: a vault note could carry a
+        // javascript: target.
+        <NoteRenderer
+          key={n.id}
+          note={n}
+          resolve={(target) => ({ href: \`#/n/\${encodeURIComponent(target)}\`, exists: true })}
+        />
+      ))}
+    </>
+  );
+}
+\`\`\`
+
+That's the whole spine. \`<NoteRenderer>\` also takes \`linkComponent\` (your
+router's \`<Link>\`) and \`fetchBlob\` (\`(url) => Promise<Blob>\`, for auth'd
+image/audio embeds) when you need them — both optional.
+
 ## Build order
 
 1. **Auth + data first.** Stand up \`createVaultSurface\` pointed at this vault;
-   confirm you can sign in and \`query-notes\` round-trips before any UI polish.
+   confirm you can sign in and \`queryNotes\` round-trips before any UI polish.
 2. **Render next.** Drop in \`<NoteRenderer>\` to display note content; wire
    wikilink/embed resolution through the package, not by hand.
 3. **UX last.** Layout, navigation, and the surface's actual purpose — now that

package/core/src/vault-projection.ts

@@ -273,8 +273,19 @@ export function projectionToMarkdown(args: {
   vaultName: string;
   description?: string | null;
   projection: VaultProjection;
+  /**
+   * This vault's own public coordinates, surfaced so a surface-builder never has
+   * to guess the vault NAME or reconstruct the REST/MCP URLs from the connector
+   * config. When `hubOrigin` is a known absolute origin (configured
+   * `PARACHUTE_HUB_ORIGIN` or an active expose-state FQDN), the absolute base
+   * URLs are rendered; when it's only the loopback fallback (no public origin
+   * known to the vault), relative path templates are rendered with a note that
+   * the origin is whatever the client connected through. The NAME is always
+   * known and always surfaced. See `chooseHubOrigin` (src/mcp-install.ts).
+   */
+  coordinates?: { hubOrigin: string; hubOriginKnown: boolean };
 }): string {
-  const { vaultName, description, projection } = args;
+  const { vaultName, description, projection, coordinates } = args;
   const stats = projection.stats;
 
   const lines: string[] = [];
@@ -284,6 +295,27 @@ export function projectionToMarkdown(args: {
     lines.push(description.trim());
   }
 
+  // GAP 3 / vault coordinates: state the vault's own NAME + REST/MCP URLs so a
+  // surface-builder (or any scripting client) doesn't have to learn them from
+  // the MCP connector config. Absolute when the vault knows its public origin;
+  // relative templates otherwise.
+  if (coordinates) {
+    lines.push("");
+    lines.push("## This vault's coordinates");
+    lines.push("");
+    lines.push(`- Name: \`${vaultName}\``);
+    if (coordinates.hubOriginKnown) {
+      const base = coordinates.hubOrigin.replace(/\/$/, "");
+      lines.push(`- REST API base: \`${base}/vault/${vaultName}/api/...\``);
+      lines.push(`- MCP endpoint: \`${base}/vault/${vaultName}/mcp\``);
+    } else {
+      lines.push(
+        `- REST API: \`<hub-origin>/vault/${vaultName}/api/...\` — \`<hub-origin>\` is the origin you connected through (the vault has no public origin configured to render here).`,
+      );
+      lines.push(`- MCP endpoint: \`<hub-origin>/vault/${vaultName}/mcp\``);
+    }
+  }
+
   // A2: surface the seeded onboarding guide so a connected AI can discover it
   // when setting up or orienting. A pointer only — the AI fetches the body on
   // demand. NOT a mandate to re-read every session; it's a start-here guide.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.3-rc.1",
+  "version": "0.6.3-rc.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/mcp-tools.ts

@@ -100,9 +100,23 @@ export async function getServerInstruction(
     vaultName,
     description: config?.description ?? null,
     projection,
+    coordinates: resolveVaultCoordinates(),
   });
 }
 
+/**
+ * Resolve this vault's own public coordinates for the projection. The vault
+ * always knows its NAME; its hub origin comes from `resolveHubOrigin()`
+ * (PARACHUTE_HUB_ORIGIN → expose-state FQDN → loopback). A loopback source
+ * means no public origin is configured — flagged via `hubOriginKnown: false`
+ * so the projection renders relative path templates rather than a loopback URL
+ * a remote surface-builder can't use.
+ */
+function resolveVaultCoordinates(): { hubOrigin: string; hubOriginKnown: boolean } {
+  const { url, source } = resolveHubOrigin();
+  return { hubOrigin: url, hubOriginKnown: source !== "loopback" };
+}
+
 /**
  * Generate MCP tools scoped to a single vault.
  *
@@ -482,9 +496,24 @@ function overrideVaultInfo(
     const includeStats = Boolean(params.include_stats);
     const projection = buildVaultProjection(store.db, { includeStats });
 
+    // GAP 3 / vault coordinates: surface the vault's own NAME + REST/MCP URL
+    // templates so a surface-builder doesn't have to learn them from the MCP
+    // connector config. `base_url` is absolute when the vault knows its public
+    // origin (PARACHUTE_HUB_ORIGIN / expose-state); null on a loopback-only
+    // box, where `rest_api` / `mcp` carry `<hub-origin>` placeholder templates
+    // resolved against whatever origin the client connected through.
+    const coords = resolveVaultCoordinates();
+    const coordBase = coords.hubOriginKnown ? coords.hubOrigin.replace(/\/$/, "") : "<hub-origin>";
+
     const result: Record<string, unknown> = {
       name: config.name,
       description: config.description ?? null,
+      coordinates: {
+        name: config.name,
+        base_url: coords.hubOriginKnown ? `${coordBase}/vault/${config.name}` : null,
+        rest_api: `${coordBase}/vault/${config.name}/api`,
+        mcp: `${coordBase}/vault/${config.name}/mcp`,
+      },
       tags: projection.tags,
       indexed_fields: projection.indexed_fields,
       query_hints: projection.query_hints,

package/src/onboarding-seed.test.ts

@@ -67,6 +67,35 @@ describe("seedOnboardingNotes (A1/A3)", () => {
     expect(ss!.content).toContain("@openparachute/surface-render");
     expect(ss!.content).toContain("createVaultSurface");
     expect(ss!.content).toContain("NoteRenderer");
+
+    // GAP 2: warn that a surface can't be run/developed from this MCP session.
+    expect(ss!.content).toContain("not from this");
+    expect(ss!.content.toLowerCase()).toContain("browser");
+
+    // GAP 1: a real, copy-paste end-to-end snippet — every load-bearing symbol
+    // present, verified against the surface-client / surface-render source.
+    expect(ss!.content).toContain("clientName"); // the one required createVaultSurface option
+    expect(ss!.content).toContain("getClient");
+    expect(ss!.content).toContain("queryNotes");
+    expect(ss!.content).toContain("handleCallback");
+    expect(ss!.content).toContain("resolve="); // NoteRenderer wikilink resolver prop
+  });
+
+  test("GAP 4: Getting Started shows a concrete update-tag fields example + write gotchas", async () => {
+    await seedOnboardingNotes(store);
+    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
+
+    // (a) a literal update-tag fields object: field name → { type, enum?, indexed? }.
+    expect(gs!.content).toContain("update-tag {");
+    expect(gs!.content).toContain('{ type: "string", indexed: true }');
+    expect(gs!.content).toContain('enum: ["scheduled", "done"]');
+
+    // (b) the write-gotchas subsection — each gotcha verified against mcp.ts.
+    expect(gs!.content).toContain("## Write gotchas");
+    expect(gs!.content).toContain("if_updated_at"); // optimistic concurrency
+    expect(gs!.content).toContain("force: true");
+    // schema-default back-fill: enum→first value, integer→0.
+    expect(gs!.content).toContain("first listed value");
   });
 
   test("A3: Getting Started links to Surface Starter via a resolved wikilink", async () => {
@@ -148,3 +177,46 @@ describe("vault-info / projection pointer (A2)", () => {
     expect(md).not.toContain("## Start here");
   });
 });
+
+describe("vault coordinates in the projection (GAP 3)", () => {
+  test("renders absolute REST + MCP URLs when the hub origin is known", () => {
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({
+      vaultName: "research",
+      description: null,
+      projection,
+      coordinates: { hubOrigin: "https://hub.example.com", hubOriginKnown: true },
+    });
+
+    expect(md).toContain("## This vault's coordinates");
+    expect(md).toContain("Name: `research`");
+    expect(md).toContain("https://hub.example.com/vault/research/api/...");
+    expect(md).toContain("https://hub.example.com/vault/research/mcp");
+  });
+
+  test("renders relative templates + connected-origin note when origin is unknown", () => {
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({
+      vaultName: "research",
+      description: null,
+      projection,
+      coordinates: { hubOrigin: "http://127.0.0.1:1940", hubOriginKnown: false },
+    });
+
+    expect(md).toContain("## This vault's coordinates");
+    expect(md).toContain("Name: `research`");
+    // The loopback URL is NOT leaked; relative templates carry a placeholder.
+    expect(md).not.toContain("127.0.0.1");
+    expect(md).toContain("<hub-origin>/vault/research/api/...");
+    expect(md).toContain("<hub-origin>/vault/research/mcp");
+  });
+
+  test("no coordinates block when coordinates are omitted; name still in the opening line", () => {
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({ vaultName: "research", description: null, projection });
+    // Without coordinates the dedicated block is absent; the vault NAME is still
+    // stated in the pre-existing opening line (the always-known coordinate).
+    expect(md).toContain('Parachute Vault "research"');
+    expect(md).not.toContain("## This vault's coordinates");
+  });
+});

package/src/vault.test.ts

@@ -578,6 +578,13 @@ describe("scoped MCP wrapper", async () => {
     const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
 
+    // The GAP-3 coordinates block reads PARACHUTE_HUB_ORIGIN; another test FILE
+    // in a shared `bun test ./src` run may have left it set (cross-file env
+    // pollution — e.g. hub-jwt.test.ts). Pin loopback so the coordinates
+    // assertion below is deterministic regardless of file order; restore after.
+    const prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+
     const vaultName = `proj-${Date.now()}`;
     writeVaultConfig({
       name: vaultName,
@@ -641,12 +648,24 @@ describe("scoped MCP wrapper", async () => {
     expect(Array.isArray(result.query_hints)).toBe(true);
     expect((result.query_hints as string[]).length).toBeGreaterThan(0);
 
+    // GAP 3 — coordinates block: the vault states its own NAME + REST/MCP URL
+    // templates so a surface-builder doesn't reconstruct them from the
+    // connector config. No public hub origin in this test fixture → loopback →
+    // `<hub-origin>` placeholder templates, `base_url` null.
+    const coords = result.coordinates as Record<string, unknown>;
+    expect(coords.name).toBe(vaultName);
+    expect(coords.rest_api).toBe(`<hub-origin>/vault/${vaultName}/api`);
+    expect(coords.mcp).toBe(`<hub-origin>/vault/${vaultName}/mcp`);
+    expect(coords.base_url).toBeNull();
+
     // stats omitted unless requested
     expect(result.stats).toBeUndefined();
 
     const withStats = await vaultInfo.execute({ include_stats: true }) as any;
     expect(withStats.stats).toBeTruthy();
 
+    if (prevHubOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
+    else process.env.PARACHUTE_HUB_ORIGIN = prevHubOrigin;
     closeAllStores();
   });