@openparachute/vault 0.6.5-rc.2 → 0.6.5

package/src/export-watch.ts

@@ -10,7 +10,7 @@
  * cursor captured at the *start* of the previous cycle. Vault writes are
  * HTTP-mediated and don't surface to filesystem watchers (the bun:sqlite DB
  * is opaque), so polling on `updated_at >= cursor` is the simplest robust
- * detection. See `parachute-patterns/cookbook/vault-portable-export.md`.
+ * detection. See `docs/contracts/vault-portable-export.md`.
  */
 
 import { ensureGitAvailable } from "./git-preflight.ts";

package/src/live-frame-parity.test.ts

@@ -0,0 +1,201 @@
+/**
+ * Live-query frame PARITY + the pure WS helpers (WS-hibernation migration,
+ * self-host door).
+ *
+ * The load-bearing CROSS-DOOR conformance check: for the shared frame corpus
+ * (mirrored byte-for-byte from the cloud door), the self-host WS message folds
+ * the event name into a `type` discriminator (plus the snapshot `done` chunk
+ * flag) over an inner payload (`notes` / `note` / `id`) that serializes
+ * byte-IDENTICALLY to the corpus. Because the corpus AND the `wsFrame` formatter
+ * are byte-shaped identical to cloud's, this transitively proves: self-host WS
+ * bytes === corpus === cloud WS bytes. (SSE was the original transport; it was
+ * removed in Phase 5 — WebSocket is now the sole live transport, polling the
+ * client floor.)
+ *
+ * Plus unit coverage of the pure helpers that back the Bun.serve integration:
+ * snapshot chunking, first-message parsing, verb-rank, and the query rejects.
+ */
+import { describe, it, expect } from "bun:test";
+import { wsFrame, WsSink } from "./subscriptions.ts";
+import {
+  buildSnapshotFrames,
+  parseClientMessage,
+  vaultVerbRank,
+  sameTagScope,
+  validateWsSubscribeQuery,
+  subscriptionCapResponse,
+  urlFromQuery,
+  SNAPSHOT_CHUNK_MAX_NOTES,
+  WS_CLOSE,
+} from "./ws-subscribe.ts";
+import { unsupportedSubscriptionReason } from "./live-match.ts";
+import { FRAME_CORPUS, NOTE_A } from "./test-support/live-frame-corpus.ts";
+
+describe("live-frame parity — self-host WS bytes === corpus === cloud WS bytes", () => {
+  for (const c of FRAME_CORPUS) {
+    it(`${c.name}: WS message folds the event into \`type\` over the corpus payload`, () => {
+      const ws = wsFrame(c.event, c.data);
+
+      // WS message is `{ type, ...data }` — the event name folds into `type`.
+      const parsedWs = JSON.parse(ws) as Record<string, unknown>;
+      expect(parsedWs.type).toBe(c.event);
+      const { type, ...rest } = parsedWs;
+      void type;
+      expect(rest).toEqual(c.data);
+
+      // BYTE parity of the inner payload: whatever value the event carries
+      // (`notes` / `note` / `id`) serializes IDENTICALLY to the corpus
+      // serialization (the cross-door invariant).
+      const innerKey = c.event === "snapshot" ? "notes" : c.event === "upsert" ? "note" : "id";
+      const innerBytes = JSON.stringify((c.data as Record<string, unknown>)[innerKey]);
+      expect(ws.includes(innerBytes)).toBe(true);
+    });
+  }
+});
+
+describe("sink classes render through the ONE formatter", () => {
+  it("WsSink.send emits exactly wsFrame(event, data)", () => {
+    const sent: string[] = [];
+    const sink = new WsSink({ send: (d: string) => sent.push(d), close: () => {} });
+    for (const c of FRAME_CORPUS) {
+      sink.send(c.event, c.data);
+      expect(sent.at(-1)).toBe(wsFrame(c.event, c.data));
+    }
+  });
+});
+
+describe("buildSnapshotFrames — chunking + done flag", () => {
+  it("empty set → exactly one done:true frame", () => {
+    const frames = buildSnapshotFrames([]);
+    expect(frames.length).toBe(1);
+    expect(JSON.parse(frames[0]!)).toEqual({ type: "snapshot", notes: [], done: true });
+  });
+
+  it("small set → one done:true frame carrying every note", () => {
+    const frames = buildSnapshotFrames([NOTE_A as any, NOTE_A as any]);
+    expect(frames.length).toBe(1);
+    const f = JSON.parse(frames[0]!);
+    expect(f.done).toBe(true);
+    expect(f.notes.length).toBe(2);
+  });
+
+  it("> SNAPSHOT_CHUNK_MAX_NOTES → multiple frames, only the last done:true, concat = full set", () => {
+    const many = Array.from({ length: SNAPSHOT_CHUNK_MAX_NOTES + 5 }, (_, i) => ({ ...NOTE_A, id: `n-${i}` }));
+    const frames = buildSnapshotFrames(many as any);
+    expect(frames.length).toBeGreaterThan(1);
+    const parsed = frames.map((f) => JSON.parse(f));
+    expect(parsed.filter((p) => p.done).length).toBe(1);
+    expect(parsed[parsed.length - 1]!.done).toBe(true);
+    parsed.slice(0, -1).forEach((p) => expect(p.done).toBe(false));
+    const concat = parsed.flatMap((p) => p.notes);
+    expect(concat.map((n: any) => n.id)).toEqual(many.map((n) => n.id));
+  });
+
+  it("each frame stays under the WS message ceiling with large notes", () => {
+    const big = Array.from({ length: 8 }, (_, i) => ({ ...NOTE_A, id: `big-${i}`, content: "x".repeat(200_000) }));
+    const frames = buildSnapshotFrames(big as any);
+    expect(frames.length).toBeGreaterThan(1);
+    for (const f of frames) expect(new TextEncoder().encode(f).byteLength).toBeLessThan(1_000_000);
+    expect(frames.flatMap((f) => JSON.parse(f).notes).length).toBe(8);
+  });
+});
+
+describe("parseClientMessage", () => {
+  it("valid auth", () => {
+    expect(parseClientMessage(JSON.stringify({ type: "auth", token: "t" }))).toEqual({ kind: "auth", token: "t" });
+  });
+  it("auth without a token → malformed", () => {
+    expect(parseClientMessage(JSON.stringify({ type: "auth" })).kind).toBe("malformed");
+    expect(parseClientMessage(JSON.stringify({ type: "auth", token: "" })).kind).toBe("malformed");
+  });
+  it("non-json / non-object → malformed", () => {
+    expect(parseClientMessage("not json").kind).toBe("malformed");
+    expect(parseClientMessage(JSON.stringify([1, 2])).kind).toBe("malformed");
+  });
+  it("other typed message → other", () => {
+    expect(parseClientMessage(JSON.stringify({ type: "hello" }))).toEqual({ kind: "other", type: "hello" });
+  });
+  it("decodes a Uint8Array frame", () => {
+    const bytes = new TextEncoder().encode(JSON.stringify({ type: "auth", token: "b" }));
+    expect(parseClientMessage(bytes)).toEqual({ kind: "auth", token: "b" });
+  });
+});
+
+describe("vaultVerbRank — narrow-or-equal ordering", () => {
+  it("ranks read < write < admin, -1 for none/other-vault", () => {
+    expect(vaultVerbRank(["vault:v:read"], "v")).toBe(0);
+    expect(vaultVerbRank(["vault:v:write"], "v")).toBe(1);
+    expect(vaultVerbRank(["vault:v:admin"], "v")).toBe(2);
+    expect(vaultVerbRank(["vault:other:read"], "v")).toBe(-1);
+    expect(vaultVerbRank([], "v")).toBe(-1);
+  });
+  it("a widen is strictly greater (the 4403 trigger)", () => {
+    expect(vaultVerbRank(["vault:v:admin"], "v") > vaultVerbRank(["vault:v:read"], "v")).toBe(true);
+    expect(vaultVerbRank(["vault:v:read"], "v") > vaultVerbRank(["vault:v:admin"], "v")).toBe(false);
+  });
+});
+
+describe("sameTagScope — the WS re-auth tag-scope-delta gate", () => {
+  it("both unscoped (null) → same", () => {
+    expect(sameTagScope(null, null)).toBe(true);
+  });
+  it("null vs scoped → differ (a drop/gain of scoping)", () => {
+    expect(sameTagScope(null, ["work/eng"])).toBe(false);
+    expect(sameTagScope(["work/eng"], null)).toBe(false);
+  });
+  it("same set (order/dupe-insensitive) → same", () => {
+    expect(sameTagScope(["a", "b"], ["b", "a"])).toBe(true);
+    expect(sameTagScope(["a", "a", "b"], ["b", "a"])).toBe(true);
+  });
+  it("different membership → differ", () => {
+    expect(sameTagScope(["work/eng"], ["work/sales"])).toBe(false);
+    expect(sameTagScope(["a"], ["a", "b"])).toBe(false);
+  });
+});
+
+describe("validateWsSubscribeQuery — same rejects as the SSE route (byte-identical bodies)", () => {
+  const reject = async (q: string) => {
+    const v = validateWsSubscribeQuery(new URL(`http://x/vault/v/api/subscribe?${q}`));
+    expect("error" in v).toBe(true);
+    const body = await (v as { error: Response }).error.json();
+    expect((v as { error: Response }).error.status).toBe(400);
+    expect(body.code).toBe("UNSUPPORTED_SUBSCRIPTION_QUERY");
+  };
+  it("rejects the URL-reachable unsupported shapes: search / near / cursor / has_links", async () => {
+    await reject("search=hi");
+    await reject("near[note_id]=abc");
+    await reject("cursor=xyz");
+    await reject("has_links=true");
+  });
+  it("accepts a supported query", () => {
+    const v = validateWsSubscribeQuery(new URL("http://x/vault/v/api/subscribe?tag=chat&path_prefix=meetings/"));
+    expect("queryOpts" in v).toBe(true);
+  });
+  it("shares the SSE route's queryOpts-level guard (cursor/has_links/date filters)", () => {
+    // The belt-and-suspenders layer both doors + the SSE route route through:
+    // a date filter isn't expressible as a flat URL param (removed 0.6.4), but
+    // if one ever reaches queryOpts it is rejected identically.
+    expect(unsupportedSubscriptionReason({ cursor: "x" } as any)).toBeTruthy();
+    expect(unsupportedSubscriptionReason({ hasLinks: true } as any)).toBeTruthy();
+    expect(unsupportedSubscriptionReason({ dateFrom: "2026-01-01" } as any)).toBeTruthy();
+    expect(unsupportedSubscriptionReason({ dateFilter: { field: "created_at" } } as any)).toBeTruthy();
+    expect(unsupportedSubscriptionReason({ tags: ["chat"] } as any)).toBeNull();
+  });
+});
+
+describe("misc pure helpers", () => {
+  it("subscriptionCapResponse → 503 SUBSCRIPTION_CAP_REACHED", async () => {
+    const res = subscriptionCapResponse();
+    expect(res.status).toBe(503);
+    expect((await res.json()).code).toBe("SUBSCRIPTION_CAP_REACHED");
+  });
+  it("urlFromQuery reconstructs searchParams from a raw query string", () => {
+    expect(urlFromQuery("?tag=chat&a=b").searchParams.get("tag")).toBe("chat");
+    expect(urlFromQuery("").search).toBe("");
+  });
+  it("WS_CLOSE carries the four application close codes", () => {
+    expect([WS_CLOSE.PROTOCOL, WS_CLOSE.UNAUTHORIZED, WS_CLOSE.FORBIDDEN, WS_CLOSE.AUTH_TIMEOUT]).toEqual([
+      4400, 4401, 4403, 4408,
+    ]);
+  });
+});

package/src/module-manifest.ts

@@ -48,6 +48,14 @@ export interface VaultModuleManifest {
   readonly paths: readonly string[];
   readonly health: string;
   readonly stripPrefix?: boolean;
+  /**
+   * When `true`, vault's daemon accepts WebSocket upgrades (the live-query WS
+   * binding) and the hub's ws-bridge forwards `Upgrade: websocket` requests on
+   * vault's mounts. DENY BY DEFAULT on the hub side. Carried onto the
+   * self-registered services.json row too (`ServiceEntry.websocket`); the hub
+   * honors either source. See `parachute-hub/src/ws-bridge.ts`.
+   */
+  readonly websocket?: boolean;
 }
 
 /**

package/src/onboarding-seed.test.ts

@@ -1,10 +1,16 @@
 /**
- * Unit tests for the onboarding-guide seeding (demo-prep Workstream A — A1/A2/A3).
+ * Unit tests for the default-pack seeding (originally demo-prep Workstream A —
+ * A1/A2/A3; reshaped for named seed packs).
  *
  * Store-direct (no CLI subprocess) so they're fast. Covers:
- *   - A1: seedOnboardingNotes writes Getting Started + Surface Starter.
- *   - A3: Surface Starter is linked from Getting Started (wikilink).
+ *   - default seed = `welcome` (3-note web + the capture tag) + `getting-started`
+ *     — and NOT `surface-starter` (out of the default seed, ratified 2026-07-02).
+ *   - A1: the Getting Started doctrine markers.
+ *   - A3 (reshaped): the welcome web's wikilinks resolve; Getting Started
+ *     points at the surface-starter PACK without a dangling wikilink.
  *   - idempotency: a re-run never clobbers an edited note.
+ *   - applySeedPack(surface-starter): the add-pack path works + is idempotent,
+ *     and the guide carries the surface doctrine (GAP 1/2 markers).
  *   - A2: the projection / vault-info pointer steers the AI at Getting Started.
  */
 
@@ -16,14 +22,33 @@ import { tmpdir } from "os";
 import { BunStore } from "./vault-store.ts";
 import { seedOnboardingNotes } from "./onboarding-seed.ts";
 import {
+  applySeedPack,
+  CAPTURE_ANYTHING_PATH,
+  CONNECT_AI_PATH,
   GETTING_STARTED_PATH,
+  NOTES_REQUIRED_TAGS,
+  SURFACE_STARTER_PACK,
   SURFACE_STARTER_PATH,
-} from "../core/src/onboarding.ts";
+  TAGS_GRAPH_PATH,
+  WELCOME_PATH,
+  YOURS_TO_KEEP_PATH,
+} from "../core/src/seed-packs.ts";
 import {
   buildVaultProjection,
   projectionToMarkdown,
 } from "../core/src/vault-projection.ts";
 
+/** Every note path the default seed writes on a blank vault (the five-guide
+ *  welcome ring + the AI-facing Getting Started). */
+const DEFAULT_SEED_PATHS = [
+  WELCOME_PATH,
+  CAPTURE_ANYTHING_PATH,
+  TAGS_GRAPH_PATH,
+  CONNECT_AI_PATH,
+  YOURS_TO_KEEP_PATH,
+  GETTING_STARTED_PATH,
+];
+
 let db: Database;
 let store: BunStore;
 let tmpDir: string;
@@ -40,14 +65,15 @@ afterEach(() => {
   rmSync(tmpDir, { recursive: true, force: true });
 });
 
-describe("seedOnboardingNotes (A1/A3)", () => {
-  test("seeds Getting Started + Surface Starter on a blank vault", async () => {
+describe("seedOnboardingNotes — default packs (welcome + getting-started)", () => {
+  test("seeds the welcome web + Getting Started on a blank vault — and NOT Surface Starter", async () => {
     const result = await seedOnboardingNotes(store);
-    expect(result.seeded.sort()).toEqual(
-      [GETTING_STARTED_PATH, SURFACE_STARTER_PATH].sort(),
-    );
+    expect(result.seeded.sort()).toEqual([...DEFAULT_SEED_PATHS].sort());
     expect(result.skipped).toEqual([]);
 
+    // Surface Starter is OUT of the default seed (button/CLI only).
+    expect(await store.getNoteByPath(SURFACE_STARTER_PATH)).toBeNull();
+
     const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
     expect(gs).not.toBeNull();
     expect(gs!.content).toContain("# Getting Started");
@@ -56,29 +82,75 @@ describe("seedOnboardingNotes (A1/A3)", () => {
     expect(gs!.content).toContain("Tags = types");
     expect(gs!.content).toContain("Paths = organization");
     expect(gs!.content).toContain("Schemas = typed metadata fields");
-    expect(gs!.content).toContain("parachute-vault import");
+    // Data-in leads with the import UI + MCP bridge; the old `parachute-vault
+    // import` CLI line (a live bug on cloud) is gone (2026-07-06 rewrite).
+    expect(gs!.content).not.toContain("parachute-vault import");
+    expect(gs!.content).toContain("Bringing existing notes in");
     expect(gs!.content).toContain("Adapt this note");
 
-    const ss = await store.getNoteByPath(SURFACE_STARTER_PATH);
-    expect(ss).not.toBeNull();
-    expect(ss!.content).toContain("# Surface Starter");
-    // A3: the two surface packages by name.
-    expect(ss!.content).toContain("@openparachute/surface-client");
-    expect(ss!.content).toContain("@openparachute/surface-render");
-    expect(ss!.content).toContain("createVaultSurface");
-    expect(ss!.content).toContain("NoteRenderer");
+    // The welcome ring: five person-voiced guide notes.
+    for (const path of [
+      WELCOME_PATH,
+      CAPTURE_ANYTHING_PATH,
+      TAGS_GRAPH_PATH,
+      CONNECT_AI_PATH,
+      YOURS_TO_KEEP_PATH,
+    ]) {
+      expect(await store.getNoteByPath(path)).not.toBeNull();
+    }
+  });
 
-    // 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");
+  test("seeds the capture tag Notes requires (byte-equal semantics) + the guide tag", async () => {
+    const result = await seedOnboardingNotes(store);
+    // welcome upserts [capture, guide]; getting-started re-upserts [guide]
+    // (converges). applySeedPack reports every declared tag per pack, so the
+    // concatenation carries guide twice — deterministic.
+    expect(result.tags).toEqual(["capture", "guide", "guide"]);
 
-    // 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
+    for (const decl of NOTES_REQUIRED_TAGS) {
+      const record = await store.getTagRecord(decl.name);
+      expect(record).not.toBeNull();
+      expect(record!.description).toBe(decl.description);
+      expect(record!.parent_names ?? []).toEqual(decl.parent_names ?? []);
+    }
+
+    // The guide tag lands with no metadata schema — guides are for you and your
+    // AI alike, plain markdown, so no per-guide audience field (written_for dropped).
+    const guide = await store.getTagRecord("guide");
+    expect(guide).not.toBeNull();
+    expect(guide!.fields?.written_for).toBeUndefined();
+    // #pinned is NOT seeded (dropped 2026-07-07 — did nothing visible on a fresh
+    // vault). Pinning still works when the user pins a note in the app.
+    expect(await store.getTagRecord("pinned")).toBeNull();
+
+    // The retired subtype tags are NOT seeded — entry method is note
+    // metadata.source (text|voice), not taxonomy (2026-07-03). Existing
+    // vaults carrying these tags stay valid; new vaults don't get them.
+    expect(await store.getTagRecord("capture/text")).toBeNull();
+    expect(await store.getTagRecord("capture/voice")).toBeNull();
+  });
+
+  test("seeded guides carry #guide (create-time tag write-through)", async () => {
+    await seedOnboardingNotes(store);
+
+    // Welcome guide: tagged guide (no longer pinned).
+    const welcome = await store.getNoteByPath(WELCOME_PATH);
+    expect([...(welcome!.tags ?? [])].sort()).toEqual(["guide"]);
+
+    // The four sibling guides: guide only.
+    for (const path of [
+      CAPTURE_ANYTHING_PATH,
+      TAGS_GRAPH_PATH,
+      CONNECT_AI_PATH,
+      YOURS_TO_KEEP_PATH,
+    ]) {
+      const note = await store.getNoteByPath(path);
+      expect(note!.tags).toEqual(["guide"]);
+    }
+
+    // The AI-facing Getting Started guide: guide.
+    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
+    expect(gs!.tags).toEqual(["guide"]);
   });
 
   test("GAP 4: Getting Started shows a concrete update-tag fields example + write gotchas", async () => {
@@ -98,29 +170,51 @@ describe("seedOnboardingNotes (A1/A3)", () => {
     expect(gs!.content).toContain("first listed value");
   });
 
-  test("A3: Getting Started links to Surface Starter via a resolved wikilink", async () => {
+  test("A3 (reshaped): the welcome ring resolves to real link edges; Getting Started has no dangling Surface Starter link", async () => {
     await seedOnboardingNotes(store);
+
+    const welcome = await store.getNoteByPath(WELCOME_PATH);
+    const capture = await store.getNoteByPath(CAPTURE_ANYTHING_PATH);
+    const tags = await store.getNoteByPath(TAGS_GRAPH_PATH);
+    const connectAi = await store.getNoteByPath(CONNECT_AI_PATH);
+    const yours = await store.getNoteByPath(YOURS_TO_KEEP_PATH);
     const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
-    expect(gs!.content).toContain("[[Surface Starter]]");
 
-    // Wikilink auto-resolution: Getting Started → Surface Starter link row.
-    const ss = await store.getNoteByPath(SURFACE_STARTER_PATH);
-    const outbound = await store.getLinks(gs!.id, { direction: "outbound" });
-    expect(outbound.some((l) => l.targetId === ss!.id)).toBe(true);
+    const outbound = async (id: string) =>
+      (await store.getLinks(id, { direction: "outbound" })).map((l) => l.targetId);
+
+    // Welcome → all four siblings.
+    const welcomeOut = await outbound(welcome!.id);
+    for (const t of [capture!.id, tags!.id, connectAi!.id, yours!.id]) {
+      expect(welcomeOut).toContain(t);
+    }
+    // The chain forward: capture → tags → connect → yours → welcome.
+    expect(await outbound(capture!.id)).toContain(tags!.id);
+    expect(await outbound(tags!.id)).toContain(connectAi!.id);
+    const connectOut = await outbound(connectAi!.id);
+    expect(connectOut).toContain(yours!.id);
+    // Connect your AI also links the AI-facing Getting Started note (seeded by
+    // the getting-started pack) — the ring's cross-link resolves, no dangle.
+    expect(connectOut).toContain(gs!.id);
+    expect(await outbound(yours!.id)).toContain(welcome!.id);
+
+    // Getting Started mentions the surface-starter PACK — not a wikilink to a
+    // note that the default seed no longer creates.
+    expect(gs!.content).not.toContain("[[Surface Starter]]");
+    expect(gs!.content).toContain("add-pack");
   });
 
-  test("idempotent: a second seed run skips both (does not duplicate)", async () => {
+  test("idempotent: a second seed run skips all notes (does not duplicate)", async () => {
     await seedOnboardingNotes(store);
     const second = await seedOnboardingNotes(store);
     expect(second.seeded).toEqual([]);
-    expect(second.skipped.sort()).toEqual(
-      [GETTING_STARTED_PATH, SURFACE_STARTER_PATH].sort(),
-    );
+    expect(second.skipped.sort()).toEqual([...DEFAULT_SEED_PATHS].sort());
 
     // Exactly one note per path — no duplicates.
     const all = await store.queryNotes({});
-    expect(all.filter((n) => n.path === GETTING_STARTED_PATH)).toHaveLength(1);
-    expect(all.filter((n) => n.path === SURFACE_STARTER_PATH)).toHaveLength(1);
+    for (const path of DEFAULT_SEED_PATHS) {
+      expect(all.filter((n) => n.path === path)).toHaveLength(1);
+    }
   });
 
   test("idempotent: never clobbers an operator-edited Getting Started", async () => {
@@ -139,6 +233,60 @@ describe("seedOnboardingNotes (A1/A3)", () => {
   });
 });
 
+describe("applySeedPack — surface-starter via add-pack", () => {
+  test("applies the Surface Starter guide onto a default-seeded vault", async () => {
+    await seedOnboardingNotes(store);
+    const result = await applySeedPack(store, SURFACE_STARTER_PACK);
+    expect(result.pack).toBe("surface-starter");
+    expect(result.seededNotes).toEqual([SURFACE_STARTER_PATH]);
+    expect(result.skippedNotes).toEqual([]);
+    // surface-starter now declares GUIDE_TAG (it's a guide).
+    expect(result.tags).toEqual(["guide"]);
+
+    const ss = await store.getNoteByPath(SURFACE_STARTER_PATH);
+    expect(ss).not.toBeNull();
+    expect(ss!.content).toContain("# Surface Starter");
+    // A3: the two surface packages by name.
+    expect(ss!.content).toContain("@openparachute/surface-client");
+    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
+
+    // Its [[Getting Started]] wikilink resolves against the default seed.
+    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
+    const outbound = await store.getLinks(ss!.id, { direction: "outbound" });
+    expect(outbound.some((l) => l.targetId === gs!.id)).toBe(true);
+  });
+
+  test("idempotent: a re-apply skips and never clobbers an edited note", async () => {
+    await applySeedPack(store, SURFACE_STARTER_PACK);
+    const ss = await store.getNoteByPath(SURFACE_STARTER_PATH);
+    const edited = "# Surface Starter\n\nWe built ours with Solid.";
+    await store.updateNote(ss!.id, { content: edited });
+
+    const rerun = await applySeedPack(store, SURFACE_STARTER_PACK);
+    expect(rerun.seededNotes).toEqual([]);
+    expect(rerun.skippedNotes).toEqual([SURFACE_STARTER_PATH]);
+
+    const after = await store.getNoteByPath(SURFACE_STARTER_PATH);
+    expect(after!.content).toBe(edited);
+    const all = await store.queryNotes({});
+    expect(all.filter((n) => n.path === SURFACE_STARTER_PATH)).toHaveLength(1);
+  });
+});
+
 describe("vault-info / projection pointer (A2)", () => {
   test("projection carries getting_started when the note exists", async () => {
     // Absent before seeding → no pointer.

package/src/onboarding-seed.ts

@@ -1,74 +1,69 @@
 /**
- * Seed the in-vault onboarding guide on vault creation.
+ * Seed the default packs on vault creation.
  *
- * A freshly-created vault gets a `Getting Started` note (AI-legible doctrine)
- * and a linked `Surface Starter` note, so a connected AI can read the guide and
- * help the operator set the vault up — and keep growing it over time.
+ * A freshly-created vault gets the `welcome` pack (the five-guide welcome ring
+ * + the `capture` / `guide` / `pinned` tags the Notes surface expects) and
+ * the `getting-started` pack (the AI-legible start-here doctrine) — so the
+ * first minute shows a small living graph, and a connected AI can read the
+ * guide and help the operator set the vault up.
  *
- * IDEMPOTENT + create-time only: each note is written ONLY when absent. A
- * re-init, restart, or re-run never clobbers a note the operator/AI has since
- * edited. Existing vaults are unaffected — this runs on the create path, not as
- * a sweep over existing vaults.
+ * The `surface-starter` pack is deliberately NOT part of the default seed
+ * (ratified 2026-07-02): it's added on demand via
+ * `parachute-vault add-pack surface-starter` or a console affordance.
  *
- * Best-effort + non-fatal: seeding must NEVER fail a vault create. Any error is
- * caught and logged; the vault is still usable without the guide.
+ * IDEMPOTENT + create-time only: each note is written ONLY when absent (tag
+ * upserts converge on the same rows). A re-init, restart, or re-run never
+ * clobbers a note the operator/AI has since edited. Existing vaults are
+ * unaffected — this runs on the create path, not as a sweep over existing
+ * vaults.
  *
- * See the demo-prep Workstream A (A1/A2/A3).
+ * Best-effort + non-fatal: seeding must NEVER fail a vault create. Any error
+ * is caught and logged; the vault is still usable without the starter content.
+ *
+ * Pack contents live in core/src/seed-packs.ts (shared with the cloud vault).
  */
 
 import {
-  GETTING_STARTED_PATH,
-  GETTING_STARTED_CONTENT,
-  SURFACE_STARTER_PATH,
-  SURFACE_STARTER_CONTENT,
-} from "../core/src/onboarding.ts";
+  applySeedPack,
+  GETTING_STARTED_PACK,
+  welcomePack,
+} from "../core/src/seed-packs.ts";
 import type { Store } from "../core/src/types.ts";
 
 interface SeedResult {
-  /** Paths actually written this run (absent ones). Empty when both pre-existed. */
+  /** Note paths actually written this run (absent ones). Empty when all pre-existed. */
   seeded: string[];
-  /** Paths skipped because the note already existed (idempotency). */
+  /** Note paths skipped because the note already existed (idempotency). */
   skipped: string[];
+  /** Tag names upserted (idempotent by nature). */
+  tags: string[];
 }
 
 /**
- * Write a single onboarding note only if no note already lives at `path`.
- * Returns true when it wrote (was absent), false when it skipped (present).
- */
-async function seedNoteIfAbsent(
-  store: Store,
-  path: string,
-  content: string,
-): Promise<boolean> {
-  const existing = await store.getNoteByPath(path);
-  if (existing) return false;
-  await store.createNote(content, { path });
-  return true;
-}
-
-/**
- * Seed the onboarding notes into `store`, idempotently. Surface Starter is
- * created first so the `[[Surface Starter]]` wikilink in Getting Started
- * resolves immediately (the create path also auto-resolves later, but this
- * keeps the link live from the first write).
+ * Seed the default packs (`welcome` + `getting-started`) into `store`,
+ * idempotently. Welcome first so the welcome web exists before the guide
+ * lands (wikilinks auto-resolve either way; this just keeps the seed's
+ * unresolved-link window minimal).
  */
 export async function seedOnboardingNotes(store: Store): Promise<SeedResult> {
   const seeded: string[] = [];
   const skipped: string[] = [];
+  const tags: string[] = [];
 
-  for (const [path, content] of [
-    [SURFACE_STARTER_PATH, SURFACE_STARTER_CONTENT],
-    [GETTING_STARTED_PATH, GETTING_STARTED_CONTENT],
-  ] as const) {
-    const wrote = await seedNoteIfAbsent(store, path, content);
-    (wrote ? seeded : skipped).push(path);
+  // No consoleOrigin: create-time runs are often pre-expose, and a baked-in
+  // loopback origin would go stale — the generic line is the safe default.
+  for (const pack of [welcomePack(), GETTING_STARTED_PACK]) {
+    const result = await applySeedPack(store, pack);
+    seeded.push(...result.seededNotes);
+    skipped.push(...result.skippedNotes);
+    tags.push(...result.tags);
   }
 
-  return { seeded, skipped };
+  return { seeded, skipped, tags };
 }
 
 /**
- * Best-effort wrapper for the create path: seed the onboarding notes, swallow
+ * Best-effort wrapper for the create path: seed the default packs, swallow
  * and log any error so a seeding failure never fails the vault create.
  */
 export async function seedOnboardingNotesBestEffort(store: Store): Promise<void> {
@@ -76,7 +71,7 @@ export async function seedOnboardingNotesBestEffort(store: Store): Promise<void>
     await seedOnboardingNotes(store);
   } catch (err) {
     console.error(
-      `Note: onboarding guide not seeded (${(err as Error)?.message ?? err}). ` +
+      `Note: starter content not seeded (${(err as Error)?.message ?? err}). ` +
         `The vault was still created; you can connect an AI and ask it to set things up.`,
     );
   }