@openparachute/vault 0.6.5-rc.9 → 0.7.0-rc.1

package/src/contract-honest-queries.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Contract suite — honest queries at the REST boundary (Wave 1 of the
+ * Reliability & Usability Program, umbrella #556). Encodes the 2026-07-09
+ * nine-persona deep test's WS1 findings (#550) as executable tests: PASSING
+ * tests lock in behavior that is correct today; `test.todo` entries describe
+ * the target behavior for confirmed-broken cases, to be flipped to real
+ * assertions in a later wave. See #550 for the full write-up — this file
+ * covers the `src/routes.ts` REST surface specifically (the cursor-bootstrap
+ * gap lives at routes.ts:1102/1106, the tags/{name} 404 gap at the GET /tags
+ * handler in `handleTags`).
+ */
+
+import { describe, it, test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunStore } from "./vault-store.ts";
+import { handleNotes, handleTags } from "./routes.ts";
+
+let db: Database;
+let store: BunStore;
+
+const BASE = "http://localhost/api";
+
+function getNotes(qs: string): Promise<Response> {
+  return handleNotes(new Request(`${BASE}/notes?${qs}`, { method: "GET" }), store, "");
+}
+
+function getTags(qs: string): Promise<Response> {
+  return handleTags(new Request(`${BASE}/tags?${qs}`, { method: "GET" }), store, "");
+}
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new BunStore(db);
+});
+
+afterEach(() => {
+  db.close();
+});
+
+describe("contract: honest queries — passing (lock in current behavior)", () => {
+  it("querying a nonexistent tag returns 200 with an empty array, not an error", async () => {
+    const res = await getNotes("tag=zzznonexistenttag");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    // Shape may gain a `warnings` field later (#550) — assert only status +
+    // array shape now so that addition doesn't break this contract test.
+    expect(Array.isArray(body)).toBe(true);
+    expect(body).toEqual([]);
+  });
+
+  it("a metadata operator query on a non-indexed field errors loudly with FIELD_NOT_INDEXED (existing behavior)", async () => {
+    const res = await getNotes("meta[not_a_real_field][gt]=5");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.code).toBe("FIELD_NOT_INDEXED");
+  });
+
+  it("a `near` query against a nonexistent anchor note errors cleanly with 404, not a silent []", async () => {
+    const res = await getNotes("near[note_id]=does-not-exist");
+    expect(res.status).toBe(404);
+    const body: any = await res.json();
+    expect(body.error).toBeDefined();
+    expect(body.note_id).toBe("does-not-exist");
+  });
+
+  // removed in W2 — once #550's cursor-bootstrap fix lands, an omitted
+  // `cursor` param will (per the documented intent) still return a flat
+  // array for callers who never opt into cursor pagination, so this
+  // specific assertion should survive; the paired todo below is the one
+  // that flips when the bootstrap gap closes. Kept both here so the fix
+  // is a conscious, reviewed change rather than an incidental snapshot.
+  it("a cursor-less limit query returns a flat array (today's shape) — removed in W2", async () => {
+    await store.createNote("only note");
+    const res = await getNotes("limit=5");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+  });
+});
+
+describe("contract: honest queries — todo (#550)", () => {
+  test.todo(
+    "#550: limit=-1 returns a structured error instead of silently meaning \"unlimited\" (today: SQLite's negative-LIMIT-means-no-limit semantics leak straight through to the caller)",
+  );
+  test.todo(
+    "#550: query responses carry a warnings: [] channel, populated with a did_you_mean suggestion for an unknown tag name",
+  );
+  test.todo(
+    "#550: an invalid date_filter value (unparseable date string) returns a structured error instead of silently matching nothing or everything",
+  );
+  test.todo(
+    "#550: GET /api/tags/{nonexistent} returns 404 instead of 200 with an all-null synthesized record",
+  );
+  test.todo(
+    "#550: list-tags reports expanded_count (rollup through parent_names descendants) alongside the literal per-tag count — today a parent tag with only child-tagged notes reports count: 0",
+  );
+  test.todo(
+    "#550: cursor bootstrap — a first call that expresses cursor intent (no `cursor` param yet, but pagination is desired) returns a {notes, next_cursor} envelope, and a second call passing that cursor back sees only notes written since the first call (today: routes.ts only wraps the response in {notes, next_cursor} when a cursor param is ALREADY present, so the very first call can never obtain one — core/src/mcp.ts:331 documents a bootstrap flow that is not actually reachable)",
+  );
+});

package/src/contract-search.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Contract suite — search (Wave 1 of the Reliability & Usability Program,
+ * umbrella #556). Encodes the 2026-07-09 nine-persona deep test's search
+ * findings (WS2, #551) as executable tests: PASSING tests lock in behavior
+ * that is correct today; `test.todo` entries describe the target behavior
+ * for confirmed-broken cases, to be flipped to real assertions in a later
+ * wave. See #551 for the full write-up.
+ *
+ * Ground truth for every assertion here was re-verified live against this
+ * repo's FTS5 search path (`core/src/notes.ts` searchNotes → REST `GET
+ * /notes?search=`) before writing — see the PR description for the probe
+ * transcript.
+ */
+
+import { describe, it, test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunStore } from "./vault-store.ts";
+import { handleNotes } from "./routes.ts";
+
+let db: Database;
+let store: BunStore;
+
+const BASE = "http://localhost/api";
+
+function search(qs: string): Promise<Response> {
+  return handleNotes(new Request(`${BASE}/notes?${qs}`, { method: "GET" }), store, "");
+}
+
+/** Planted corpus — each note exists to exercise exactly one FTS5 quirk. */
+const NOTES = {
+  hyphenPhrase: "The rollout had an eleven-day capping delay before it shipped.",
+  contraction: "She said she didn't know about the capping delay.",
+  decimal: "The measurement came out to 18.6 percent this quarter.",
+  bothWords: "A plain keyword note about widgets and gadgets.",
+  widgetsOnly: "Only widgets here, no other word.",
+  gadgetsOnly: "Gadgets alone, nothing else notable.",
+  filler1: "Quarterly report drafted for the finance team.",
+  filler2: "Meeting notes from the Tuesday standup.",
+  filler3: "Grocery list: eggs, bread, oat milk.",
+  filler4: "Project plan for the Q3 roadmap.",
+  filler5: "Weekly retro: wins and blockers for the sprint.",
+  filler6: "Random thoughts on the trip itinerary.",
+};
+
+beforeEach(async () => {
+  db = new Database(":memory:");
+  store = new BunStore(db);
+  for (const content of Object.values(NOTES)) {
+    await store.createNote(content);
+  }
+});
+
+afterEach(() => {
+  db.close();
+});
+
+async function bodyOf(res: Response): Promise<any> {
+  return res.json();
+}
+
+describe("contract: search — passing (lock in current behavior)", () => {
+  it("plain keyword search finds the matching notes", async () => {
+    const res = await search("search=widgets&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    const contents = new Set(body.map((n: any) => n.content));
+    expect(contents.has(NOTES.bothWords)).toBe(true);
+    expect(contents.has(NOTES.widgetsOnly)).toBe(true);
+    expect(contents.has(NOTES.gadgetsOnly)).toBe(false);
+  });
+
+  it("two-word unquoted search is implicit AND — only the note containing BOTH terms matches", async () => {
+    const res = await search("search=widgets+gadgets&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.bothWords]);
+  });
+
+  it('quoted phrase finds hyphenated phrase text: "eleven-day capping delay"', async () => {
+    const res = await search(`search=${encodeURIComponent('"eleven-day capping delay"')}&include_content=true`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.hyphenPhrase]);
+  });
+
+  it('quoted decimal literal finds it: "18.6"', async () => {
+    const res = await search(`search=${encodeURIComponent('"18.6"')}&include_content=true`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.decimal]);
+  });
+
+  it('quoted contraction finds it: "didn\'t"', async () => {
+    const res = await search(`search=${encodeURIComponent(`"didn't"`)}&include_content=true`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.contraction]);
+  });
+
+  it("unknown-word search returns []", async () => {
+    const res = await search("search=zzzznonexistentword&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+  });
+});
+
+describe("contract: search — todo (#551, literal-by-default + recall + ranking)", () => {
+  test.todo(
+    `#551: unquoted search: "didn't" finds the contraction content (literal-by-default — today the bare apostrophe splits into two AND'd tokens and returns [])`,
+  );
+  test.todo(
+    `#551: unquoted search: "eleven-day capping delay" finds the hyphenated-phrase note (literal-by-default — today the bare hyphenated word tokenizes into separate AND'd terms and returns [])`,
+  );
+  test.todo(
+    `#551: unquoted search: "18.6" finds the decimal note (literal-by-default — today the bare decimal tokenizes into separate AND'd terms and returns [])`,
+  );
+  test.todo(
+    `#551: search_mode:"advanced" preserves raw FTS5 query syntax (AND/OR/NOT, phrase, prefix) once literal-by-default escaping ships as the new default`,
+  );
+  test.todo(
+    `#551: sort:"asc"/"desc" changes result order under search (today silently ignored — FTS5 rank order wins regardless of the sort param)`,
+  );
+  test.todo(
+    `#551: malformed FTS syntax (e.g. an unbalanced quote) yields a structured warning or error, not a silently swallowed [] (today searchNotes catches every FTS5 syntax error and returns [])`,
+  );
+});

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

@@ -23,24 +23,29 @@ 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,
-  TRY_LINKING_PATH,
+  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. */
+/** 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,
-  TRY_LINKING_PATH,
+  CAPTURE_ANYTHING_PATH,
+  TAGS_GRAPH_PATH,
   CONNECT_AI_PATH,
+  YOURS_TO_KEEP_PATH,
   GETTING_STARTED_PATH,
 ];
 
@@ -77,18 +82,30 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
     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");
 
-    // The welcome web: three person-voiced notes.
-    for (const path of [WELCOME_PATH, TRY_LINKING_PATH, CONNECT_AI_PATH]) {
+    // 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();
     }
   });
 
-  test("seeds the ONE capture tag Notes requires (byte-equal semantics)", async () => {
+  test("seeds the capture tag Notes requires (byte-equal semantics) + the guide tag", async () => {
     const result = await seedOnboardingNotes(store);
-    expect(result.tags).toEqual(["capture"]);
+    // 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"]);
 
     for (const decl of NOTES_REQUIRED_TAGS) {
       const record = await store.getTagRecord(decl.name);
@@ -97,6 +114,15 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
       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.
@@ -104,6 +130,29 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
     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 () => {
     await seedOnboardingNotes(store);
     const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
@@ -121,26 +170,38 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
     expect(gs!.content).toContain("first listed value");
   });
 
-  test("A3 (reshaped): the welcome web's wikilinks resolve; Getting Started has no dangling Surface Starter link", async () => {
+  test("A3 (reshaped): the welcome ring resolves to real link edges; Getting Started has no dangling Surface Starter link", async () => {
     await seedOnboardingNotes(store);
 
-    // welcome → try-linking, try-linking → welcome, connect-AI → welcome.
     const welcome = await store.getNoteByPath(WELCOME_PATH);
-    const tryLinking = await store.getNoteByPath(TRY_LINKING_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);
 
-    const welcomeOut = await store.getLinks(welcome!.id, { direction: "outbound" });
-    expect(welcomeOut.some((l) => l.targetId === tryLinking!.id)).toBe(true);
-    const tryOut = await store.getLinks(tryLinking!.id, { direction: "outbound" });
-    expect(tryOut.some((l) => l.targetId === welcome!.id)).toBe(true);
-    const connectOut = await store.getLinks(connectAi!.id, { direction: "outbound" });
-    expect(connectOut.some((l) => l.targetId === welcome!.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.
-    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
     expect(gs!.content).not.toContain("[[Surface Starter]]");
-    expect(gs!.content).toContain("add-pack surface-starter");
+    expect(gs!.content).toContain("add-pack");
   });
 
   test("idempotent: a second seed run skips all notes (does not duplicate)", async () => {
@@ -179,7 +240,8 @@ describe("applySeedPack — surface-starter via add-pack", () => {
     expect(result.pack).toBe("surface-starter");
     expect(result.seededNotes).toEqual([SURFACE_STARTER_PATH]);
     expect(result.skippedNotes).toEqual([]);
-    expect(result.tags).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();

package/src/onboarding-seed.ts

@@ -1,8 +1,8 @@
 /**
  * Seed the default packs on vault creation.
  *
- * A freshly-created vault gets the `welcome` pack (the person-voiced
- * three-note welcome web + the `capture` tag the Notes surface expects) and
+ * 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.

package/src/routes.ts

@@ -2089,7 +2089,7 @@ export async function handleTags(
 
   // PUT /tags/:name — upsert tag identity row. Body accepts any combination
   // of { description, fields, relationships, parent_names }; omitted keys
-  // are preserved, explicit null clears. See patterns/tag-data-model.md.
+  // are preserved, explicit null clears. See docs/contracts/tag-data-model.md.
   if (req.method === "PUT") {
     // Canonical-bare-tag guard (vault#XXX): normalize the upserted tag NAME so
     // the existing-field merge read (store.getTagSchema below) and the upsert
@@ -2114,7 +2114,7 @@ export async function handleTags(
        * the MCP `update-tag` tool relies on (omitted keys preserved). The
        * Schema editor (vault#283) sends the full map + `replace_fields: true`
        * so removing a field row actually deletes the field. See
-       * patterns/tag-data-model.md.
+       * docs/contracts/tag-data-model.md.
        */
       replace_fields?: unknown;
     };
@@ -2211,7 +2211,7 @@ export async function handleTags(
     // Tag-scoped tokens reference root tags by name; deleting a referenced
     // tag would silently orphan the token's allowlist. Fail closed (409)
     // and name the offending tokens so the operator can revoke or re-mint
-    // before retrying. patterns/tag-scoped-tokens.md §Dependencies.
+    // before retrying. docs/contracts/tag-scoped-tokens.md §Dependencies.
     const referenced_by = findTokensReferencingTag(store.db, tagName);
     if (referenced_by.length > 0) {
       return json(