@openparachute/vault 0.6.5-rc.13 → 0.6.5-rc.15

package/core/src/seed-packs.ts

@@ -5,8 +5,9 @@
  * A pack is a named bundle of `tags` (upserted) + `notes` (created only when
  * no note already lives at the path). Three packs ship today:
  *
- *   - `welcome` — the person-voiced three-note welcome web + the `capture`
- *     tag the Notes surface expects. Default-seeded on vault creation.
+ *   - `welcome` — the five-guide welcome ring (Welcome, Capture anything, Tags
+ *     and the graph, Connect your AI, Yours to keep) + the `capture` / `guide`
+ *     / `pinned` tags the Notes surface expects. Default-seeded on creation.
  *   - `getting-started` — the AI-facing start-here guide (SKILL.md-style
  *     doctrine addressed to a connected assistant). Default-seeded.
  *   - `surface-starter` — the living starter guide for building a custom
@@ -14,6 +15,11 @@
  *     Surface Starter is out of the default seed) — added on demand via
  *     `parachute-vault add-pack surface-starter` or a console affordance.
  *
+ * Guides are the vault's skill files — the Parachute equivalent of a
+ * `SKILL.md`. They're tagged `#guide` (GUIDE_TAG), and a `written_for` schema
+ * field on that tag records who each guide is written for (`ai` | `human` |
+ * `both`; `ai` first = the default, since guides lean AI).
+ *
  * This module is the single source of truth for pack content across BOTH
  * runtimes: the bun vault (`src/onboarding-seed.ts` default seed + the
  * `add-pack` CLI verb) and the cloud vault DO (parachute-cloud
@@ -26,23 +32,37 @@
  * Getting Started / Surface Starter path + content constants.
  */
 
-import type { Store } from "./types.ts";
+import type { Store, TagFieldSchema } from "./types.ts";
 
 // ---------------------------------------------------------------------------
 // Pack shape
 // ---------------------------------------------------------------------------
 
-/** A tag declaration a pack upserts (identity row, not a schema migration). */
+/**
+ * A tag declaration a pack upserts (identity row, not a schema migration).
+ *
+ * `fields` carries an optional typed-metadata schema — the same
+ * `Record<field, { type, enum?, indexed? }>` shape `update-tag` accepts — so a
+ * pack can declare a schema-carrying tag (e.g. GUIDE_TAG's `written_for`
+ * enum). The applier passes it straight through to `upsertTagRecord`.
+ */
 export interface SeedPackTag {
   name: string;
   description: string;
   parent_names?: string[];
+  fields?: Record<string, TagFieldSchema>;
 }
 
-/** A note a pack seeds — created only when no note exists at `path`. */
+/**
+ * A note a pack seeds — created only when no note exists at `path`. `tags` +
+ * `metadata` are applied at create time (both runtimes' `createNote` accepts
+ * them); a guide note carries `tags: ["guide"]` + `metadata: { written_for }`.
+ */
 export interface SeedPackNote {
   path: string;
   content: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
 }
 
 /** A named bundle of starter tags + notes. */
@@ -83,58 +103,188 @@ export const NOTES_REQUIRED_TAGS: ReadonlyArray<SeedPackTag> = [
   },
 ];
 
+/**
+ * The `guide` tag — the vault's skill-file tag. Guides are the Parachute
+ * equivalent of a `SKILL.md`: notes that teach a connected AI (and the human)
+ * how this vault works and how to work it. The `written_for` schema field says
+ * who a guide is written for; `ai` is the enum's FIRST value, so it's the
+ * schema default — guides lean AI.
+ *
+ * Declared by every pack that ships guide notes (welcome / getting-started /
+ * surface-starter). The upserts converge on one row, so each pack stays
+ * self-sufficient — applying any one of them alone still lands the tag.
+ */
+export const GUIDE_TAG: SeedPackTag = {
+  name: "guide",
+  description:
+    "Guides — the vault's skill files. Notes that teach a connected AI (and the human) how this vault works and how to work it. `written_for` says who a guide is written for.",
+  fields: {
+    // First enum value is the schema default — guides lean AI.
+    written_for: { type: "string", enum: ["ai", "human", "both"] },
+  },
+};
+
+/** The `pinned` tag — notes pinned to the top of the Notes app. No schema. */
+export const PINNED_TAG: SeedPackTag = {
+  name: "pinned",
+  description: "Notes pinned to the top of the Notes app.",
+};
+
 export const WELCOME_PATH = "Welcome to your vault 🪂";
-export const TRY_LINKING_PATH = "Try linking notes";
+export const CAPTURE_ANYTHING_PATH = "Capture anything";
+export const TAGS_GRAPH_PATH = "Tags and the graph";
 export const CONNECT_AI_PATH = "Connect your AI";
+export const YOURS_TO_KEEP_PATH = "Yours to keep";
 
 /**
- * Build the `welcome` pack: a three-note welcome web (welcome → try-linking →
- * back, connect-AI → welcome) so the graph view shows a connected structure
- * from minute one, plus the `capture` tag above. The notes are ordinary
- * notes — no special flags, deletable like anything else.
+ * Build the `welcome` pack: the five-guide welcome ring — Welcome, Capture
+ * anything, Tags and the graph, Connect your AI, Yours to keep — plus the
+ * `capture` / `guide` / `pinned` tags. The guides are ordinary notes tagged
+ * `#guide` (the vault's skill-file tag), each `metadata.written_for: "human"`;
+ * Welcome is `#pinned` so it sits at the top of the Notes app. They form a
+ * small linked web (Welcome → all four; the rest chain 2→3→4→5→1; Connect
+ * your AI also links the AI-facing [[Getting Started]]) so the graph view
+ * shows a connected structure from minute one. Deletable like anything else.
  *
- * Content is ported EXACTLY from parachute-cloud workers/vault/src/welcome.ts
- * (person-voiced, addressed to the everyday user). `consoleOrigin` is the
- * origin of the operator's console (the cloud console, or a hub portal) —
- * when known, the Connect-your-AI note names it; when omitted (the bun vault
- * seeds at create time, often pre-expose, and must never bake in a loopback
- * origin) the line stays generic.
+ * These five bodies are the ratified guides (already live at
+ * parachute.computer/guides). `consoleOrigin` is the origin of the operator's
+ * console (the cloud console, or a hub portal) — when known, the Connect-your-AI
+ * note names it; when omitted (the bun vault seeds at create time, often
+ * pre-expose, and must never bake in a loopback origin) the line stays generic.
  */
 export function welcomePack(opts: { consoleOrigin?: string } = {}): SeedPack {
   const consoleLine = opts.consoleOrigin
     ? `Grab the connection URL from your console at ${opts.consoleOrigin}.`
     : `Grab the connection URL from your console.`;
+  const guideHuman = { tags: ["guide"], metadata: { written_for: "human" } };
   return {
     name: "welcome",
     description:
-      "A small linked welcome web (three notes) + the capture tag the Notes surface uses. Seeded by default on new vaults.",
-    tags: NOTES_REQUIRED_TAGS,
+      "The five-guide welcome ring (Welcome, Capture anything, Tags and the graph, Connect your AI, Yours to keep) — the vault's #guide skill files — plus the capture/guide/pinned tags. Seeded by default on new vaults.",
+    // capture (Notes surface) + guide (the skill-file tag, carries the
+    // written_for schema) + pinned (top-of-app). Upserts are idempotent.
+    tags: [...NOTES_REQUIRED_TAGS, GUIDE_TAG, PINNED_TAG],
     // `[[wikilinks]]` resolve by note path — pending links auto-resolve when
     // the target is created, so order only affects how briefly a link sits
-    // unresolved during the seed.
+    // unresolved during the seed. Every [[target]] here resolves to a note the
+    // default seed writes (the four siblings + [[Getting Started]] from the
+    // getting-started pack) — no dangling links on a fresh vault.
     notes: [
       {
         path: WELCOME_PATH,
+        tags: ["guide", "pinned"],
+        metadata: { written_for: "human" },
         content: `# ${WELCOME_PATH}
 
 This vault is yours.
-Write anything.
-Notes can link to each other, like this: [[${TRY_LINKING_PATH}]].
+
+Write anything — ideas, people, plans, wifi passwords. Notes can link to each
+other, like this: [[${CAPTURE_ANYTHING_PATH}]]. Follow that link and keep going — these
+guides form a small web you can wander:
+
+- [[${CAPTURE_ANYTHING_PATH}]] — get thoughts in and link them together
+- [[${TAGS_GRAPH_PATH}]] — structure that grows out of what you write
+- [[${CONNECT_AI_PATH}]] — any AI can read and write your vault
+- [[${YOURS_TO_KEEP_PATH}]] — export everything, anytime
+
+They're ordinary notes, tagged #guide. Edit them, add to them, or delete the
+lot — the vault is yours, remember.
+`,
+      },
+      {
+        path: CAPTURE_ANYTHING_PATH,
+        ...guideHuman,
+        content: `# ${CAPTURE_ANYTHING_PATH}
+
+The one habit that makes a vault work: when a thought strikes, write it down.
+Don't sort it. Don't file it. Let it land.
+
+A note can be two words or two pages. The blog idea on a trail, the follow-up
+from a meeting, the dream at 2am — capture first. Organizing can happen later,
+or never; that's what tags and your AI are for.
+
+To connect two notes, wrap a note's name in double square brackets:
+[[${WELCOME_PATH}]] is a link back to where you started. If the note
+doesn't exist yet, the link waits patiently and connects the moment it does.
+
+That's the whole trick. Storage is easy — connection is everything. A linked
+note is a thought your future self, and your AI, can find again.
+
+Next: [[${TAGS_GRAPH_PATH}]].
 `,
       },
       {
-        path: TRY_LINKING_PATH,
-        content: `# ${TRY_LINKING_PATH}
+        path: TAGS_GRAPH_PATH,
+        ...guideHuman,
+        content: `# ${TAGS_GRAPH_PATH}
+
+Notes and links come first. Tags come later, when you notice a pattern.
+
+A tag answers "what kind of thing is this?" — #person, #recipe, #idea. Tag a
+few notes the same way and a view lights up: all your people, all your recipes,
+everything half-finished. Your vault starts with just two:
 
-Wrap a note's name in double square brackets to make a wikilink, like this one back to [[${WELCOME_PATH}]].
+- #capture — the Notes app puts it on whatever you write or speak in directly,
+  marking your own raw words.
+- #guide — these notes.
+
+Underneath, everything is one graph: every note a node, every link an edge.
+Open the graph view and watch it grow; ask a connected AI "what's near this
+note?" and it walks the edges for you.
+
+The structure isn't a filing system you design on day one. It grows out of what
+you actually write — so don't over-organize an empty vault. Write, link, and
+let the shape appear.
+
+Next: [[${CONNECT_AI_PATH}]].
 `,
       },
       {
         path: CONNECT_AI_PATH,
+        ...guideHuman,
         content: `# ${CONNECT_AI_PATH}
 
-Your vault speaks MCP. ${consoleLine}
-Start from [[${WELCOME_PATH}]].
+Your vault speaks MCP — an open standard — so any AI can read and write it:
+Claude, ChatGPT, Claude Code, Cursor, or an agent you build. ${consoleLine}
+
+Once you're connected, try:
+
+- "Read the Getting Started note and help me set this vault up."
+- "What did I want to write about?"
+- "Tag my untagged notes."
+
+Your AI sees what you see — the same notes, links, and tags — and what it
+writes lands here, as notes you can read, edit, or delete. There's even a note
+in this vault written for it: [[${GETTING_STARTED_PATH}]], the vault-design brief your
+AI reads so you don't have to.
+
+One memory, shared with every AI you choose to connect. That's the point.
+
+Next: [[${YOURS_TO_KEEP_PATH}]].
+`,
+      },
+      {
+        path: YOURS_TO_KEEP_PATH,
+        ...guideHuman,
+        content: `# ${YOURS_TO_KEEP_PATH}
+
+Everything here — every note, tag, and link — exports as plain markdown files
+with the structure intact. On Parachute Cloud, it's the Export button in your
+console. Self-hosting, it's one command: \`parachute-vault export <dir>\`.
+
+What you get is a folder any app can open, and another Parachute can import
+losslessly. Move from our cloud to your own machine, or the other way — same
+software, same format, nothing held hostage between the doors.
+
+We build it this way on purpose. A connection you can't leave isn't a
+relationship. You can always leave — which is exactly why you can trust
+staying.
+
+Export isn't a feature we grudgingly support; it's the moral center of the
+design. We test it constantly, because a promise you don't test is just a
+hope.
+
+Back to [[${WELCOME_PATH}]].
 `,
       },
     ],
@@ -313,8 +463,17 @@ export const GETTING_STARTED_PACK: SeedPack = {
   name: "getting-started",
   description:
     "The AI-facing start-here guide: vault design vocabulary (tags/paths/schemas), imports, write gotchas. Seeded by default on new vaults.",
-  tags: [],
-  notes: [{ path: GETTING_STARTED_PATH, content: GETTING_STARTED_CONTENT }],
+  // Declares GUIDE_TAG too — each pack is self-sufficient; the upsert converges
+  // with the welcome pack's. This guide is written FOR the AI.
+  tags: [GUIDE_TAG],
+  notes: [
+    {
+      path: GETTING_STARTED_PATH,
+      tags: ["guide"],
+      metadata: { written_for: "ai" },
+      content: GETTING_STARTED_CONTENT,
+    },
+  ],
 };
 
 // ---------------------------------------------------------------------------
@@ -450,8 +609,17 @@ export const SURFACE_STARTER_PACK: SeedPack = {
   name: "surface-starter",
   description:
     "A living starter guide for building a custom surface (UI) over this vault with the published surface packages. Opt-in — not seeded by default.",
-  tags: [],
-  notes: [{ path: SURFACE_STARTER_PATH, content: SURFACE_STARTER_CONTENT }],
+  // A guide too (written for the AI) — declares GUIDE_TAG so the opt-in
+  // add-pack path lands the tag even if this pack is applied on its own.
+  tags: [GUIDE_TAG],
+  notes: [
+    {
+      path: SURFACE_STARTER_PATH,
+      tags: ["guide"],
+      metadata: { written_for: "ai" },
+      content: SURFACE_STARTER_CONTENT,
+    },
+  ],
 };
 
 // ---------------------------------------------------------------------------
@@ -541,18 +709,23 @@ export async function applySeedPack(
     await store.upsertTagRecord(decl.name, {
       description: decl.description,
       ...(decl.parent_names ? { parent_names: decl.parent_names } : {}),
+      ...(decl.fields ? { fields: decl.fields } : {}),
     });
     result.tags.push(decl.name);
   }
 
-  for (const { path, content } of pack.notes) {
-    const existing = await store.getNoteByPath(path);
+  for (const note of pack.notes) {
+    const existing = await store.getNoteByPath(note.path);
     if (existing) {
-      result.skippedNotes.push(path);
+      result.skippedNotes.push(note.path);
       continue;
     }
-    await store.createNote(content, { path });
-    result.seededNotes.push(path);
+    await store.createNote(note.content, {
+      path: note.path,
+      tags: note.tags,
+      metadata: note.metadata,
+    });
+    result.seededNotes.push(note.path);
   }
 
   return result;

package/package.json

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

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

@@ -1,21 +1,22 @@
 /**
- * Live-query frame PARITY + the pure WS helpers (WS-hibernation migration
- * Phase 3, self-host door).
+ * 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 payload and the
- * self-host SSE `data:` body carry a byte-IDENTICAL serialization of the inner
- * payload (`notes` / `note` / `id`) — the ONLY difference is the `type`
- * discriminator the WS message folds in (plus the snapshot `done` chunk flag).
- * Because the corpus AND the `sseFrame`/`wsFrame` formatters are byte-shaped
- * identical to cloud's, this transitively proves: self-host WS bytes === corpus
- * === self-host SSE bytes === cloud WS/SSE bytes.
+ * (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 { sseFrame, wsFrame, SseSink, WsSink, snapshotFrame } from "./subscriptions.ts";
+import { wsFrame, WsSink } from "./subscriptions.ts";
 import {
   buildSnapshotFrames,
   parseClientMessage,
@@ -30,23 +31,11 @@ import {
 import { unsupportedSubscriptionReason } from "./live-match.ts";
 import { FRAME_CORPUS, NOTE_A } from "./test-support/live-frame-corpus.ts";
 
-/** Strip the SSE `data:` body out of a single-event SSE frame. */
-function sseDataBody(frame: string): string {
-  const line = frame.split("\n").find((l) => l.startsWith("data:"))!;
-  return line.slice("data:".length).replace(/^ /, "");
-}
-
-describe("live-frame parity — self-host WS bytes === corpus === SSE data body", () => {
+describe("live-frame parity — self-host WS bytes === corpus === cloud WS bytes", () => {
   for (const c of FRAME_CORPUS) {
-    it(`${c.name}: identical inner payload across transports`, () => {
-      const sse = sseFrame(c.event, c.data);
+    it(`${c.name}: WS message folds the event into \`type\` over the corpus payload`, () => {
       const ws = wsFrame(c.event, c.data);
 
-      // SSE frame shape (byte-identical to the pre-WS-migration contract).
-      expect(sse).toBe(`event: ${c.event}\ndata: ${JSON.stringify(c.data)}\n\n`);
-      // SSE data body parses back to exactly the payload.
-      expect(JSON.parse(sseDataBody(sse))).toEqual(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);
@@ -55,21 +44,16 @@ describe("live-frame parity — self-host WS bytes === corpus === SSE data body"
       expect(rest).toEqual(c.data);
 
       // BYTE parity of the inner payload: whatever value the event carries
-      // (`notes` / `note` / `id`) serializes IDENTICALLY in both frames AND
-      // equals the corpus serialization (the cross-door invariant).
+      // (`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(sse.includes(innerBytes)).toBe(true);
       expect(ws.includes(innerBytes)).toBe(true);
     });
   }
-
-  it("snapshotFrame() is the SSE snapshot frame for a note set", () => {
-    expect(snapshotFrame([NOTE_A as any])).toBe(sseFrame("snapshot", { notes: [NOTE_A] }));
-  });
 });
 
-describe("sink classes render through the ONE formatter each", () => {
+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: () => {} });
@@ -78,15 +62,6 @@ describe("sink classes render through the ONE formatter each", () => {
       expect(sent.at(-1)).toBe(wsFrame(c.event, c.data));
     }
   });
-
-  it("SseSink.send emits exactly sseFrame(event, data); comment() emits `:\\n\\n`", () => {
-    const pushed: string[] = [];
-    const sink = new SseSink((f) => (pushed.push(f), true), () => {});
-    sink.send("upsert", { note: NOTE_A });
-    expect(pushed.at(-1)).toBe(sseFrame("upsert", { note: NOTE_A }));
-    sink.comment();
-    expect(pushed.at(-1)).toBe(":\n\n");
-  });
 });
 
 describe("buildSnapshotFrames — chunking + done flag", () => {

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,
 ];
 
@@ -80,15 +85,24 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
     expect(gs!.content).toContain("parachute-vault import");
     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/pinned tags", async () => {
     const result = await seedOnboardingNotes(store);
-    expect(result.tags).toEqual(["capture"]);
+    // welcome upserts [capture, guide, pinned]; 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", "pinned", "guide"]);
 
     for (const decl of NOTES_REQUIRED_TAGS) {
       const record = await store.getTagRecord(decl.name);
@@ -97,6 +111,14 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
       expect(record!.parent_names ?? []).toEqual(decl.parent_names ?? []);
     }
 
+    // The guide tag lands with its written_for enum schema (applier passes
+    // `fields` through to upsertTagRecord). "ai" is the default (first value).
+    const guide = await store.getTagRecord("guide");
+    expect(guide).not.toBeNull();
+    expect(guide!.fields?.written_for?.enum).toEqual(["ai", "human", "both"]);
+    const pinned = await store.getTagRecord("pinned");
+    expect(pinned).not.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 +126,32 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
     expect(await store.getTagRecord("capture/voice")).toBeNull();
   });
 
+  test("seeded guides carry #guide + metadata.written_for (create-time tag/metadata write-through)", async () => {
+    await seedOnboardingNotes(store);
+
+    // Human-facing welcome guide: tagged guide + pinned, written_for human.
+    const welcome = await store.getNoteByPath(WELCOME_PATH);
+    expect([...(welcome!.tags ?? [])].sort()).toEqual(["guide", "pinned"]);
+    expect(welcome!.metadata?.written_for).toBe("human");
+
+    // The four sibling guides: guide only, written_for human.
+    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"]);
+      expect(note!.metadata?.written_for).toBe("human");
+    }
+
+    // The AI-facing Getting Started guide: guide, written_for ai.
+    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
+    expect(gs!.tags).toEqual(["guide"]);
+    expect(gs!.metadata?.written_for).toBe("ai");
+  });
+
   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,24 +169,36 @@ 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");
   });
@@ -179,7 +239,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, written_for ai).
+    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.