@openparachute/vault 0.6.5-rc.14 → 0.6.5-rc.16

package/core/src/seed-packs.test.ts

@@ -1,35 +1,49 @@
 /**
  * Content + registry pins for the named seed packs (core/src/seed-packs.ts).
  *
- * Pure content tests — no DB. The applier's behavior (idempotence, seeding)
- * is exercised store-level in src/onboarding-seed.test.ts and CLI-level in
- * src/add-pack.test.ts.
+ * Pure content tests — no DB. The applier's behavior (idempotence, seeding,
+ * tag/metadata write-through) is exercised store-level in
+ * src/onboarding-seed.test.ts and CLI-level in src/add-pack.test.ts.
  *
- * The load-bearing pin: the `welcome` pack's tags must stay byte-equal to
- * notes-ui's NOTES_REQUIRED_SCHEMA — the Notes PWA's connect-time audit
- * compares `description` verbatim, and its schema banner only clears when the
- * tags genuinely carry the semantics Notes declares. ONE tag since 2026-07-03:
- * `#capture` only — entry method (text|voice) is note `metadata.source`
- * provenance, not taxonomy (sibling notes-ui PR carries the client side).
+ * The load-bearing pins:
+ *   - the `welcome` pack's tags must CONTAIN notes-ui's NOTES_REQUIRED_SCHEMA
+ *     byte-for-byte — the Notes PWA's connect-time audit compares `description`
+ *     verbatim, and its schema banner only clears when the capture tag genuinely
+ *     carries the semantics Notes declares. (Containment, not equality: the
+ *     welcome pack now also ships the #guide + #pinned tags.)
+ *   - `#guide` is the vault's skill-file tag, carrying a `written_for` enum
+ *     schema (`ai` | `human` | `both`, `ai` first = default). Every seeded guide
+ *     note is tagged `#guide` + `metadata.written_for`.
+ *   - the five-guide welcome ring links into a connected web with no dangling
+ *     wikilinks across the default seed.
  */
 
 import { describe, test, expect } from "bun:test";
 import {
   applySeedPack,
+  CAPTURE_ANYTHING_PATH,
   CONNECT_AI_PATH,
+  DEFAULT_VAULT_DESCRIPTION,
+  IMPORTED_VAULT_DESCRIPTION,
+  YOURS_TO_KEEP_PATH,
   GETTING_STARTED_CONTENT,
   GETTING_STARTED_PACK,
   GETTING_STARTED_PATH,
   getSeedPack,
+  GUIDE_TAG,
   listSeedPacks,
   NOTES_REQUIRED_TAGS,
+  PINNED_TAG,
   SEED_PACK_NAMES,
   SURFACE_STARTER_CONTENT,
   SURFACE_STARTER_PACK,
   SURFACE_STARTER_PATH,
-  TRY_LINKING_PATH,
+  TAGS_GRAPH_PATH,
   WELCOME_PATH,
   welcomePack,
+  YOURS_TO_KEEP_PATH,
+  type SeedPack,
+  type SeedPackNote,
 } from "./seed-packs.ts";
 import * as onboardingShim from "./onboarding.ts";
 
@@ -47,17 +61,74 @@ const NOTES_UI_REQUIRED_SCHEMA_TAGS = [
   },
 ];
 
-describe("welcome pack — notes-ui schema parity", () => {
-  test("welcome tags are byte-equal to notes-ui's NOTES_REQUIRED_SCHEMA", () => {
+/**
+ * Extract every REAL `[[wikilink]]` target from note content — mirroring the
+ * store's parser (core/src/wikilinks.ts), which ignores wikilinks inside
+ * fenced/inline code. So an illustrative `[[wikilinks]]` in a code span (as in
+ * the Getting Started guide) is not counted — it never becomes a link.
+ */
+function wikilinkTargets(content: string): string[] {
+  const stripped = content
+    .replace(/```[\s\S]*?```/g, (m) => " ".repeat(m.length)) // fenced code
+    .replace(/`[^`]*`/g, (m) => " ".repeat(m.length)); // inline code
+  return [...stripped.matchAll(/\[\[([^\]]+)\]\]/g)].map((m) => m[1]!);
+}
+
+/** A note in a pack, by path (fails loudly if absent). */
+function noteAt(pack: SeedPack, path: string): SeedPackNote {
+  const note = pack.notes.find((n) => n.path === path);
+  if (!note) throw new Error(`no note at path ${path}`);
+  return note;
+}
+
+describe("guide tag — the vault's skill-file tag", () => {
+  test("GUIDE_TAG carries the written_for enum, ai first (= default)", () => {
+    expect(GUIDE_TAG.name).toBe("guide");
+    // The description's last sentence names the schema field.
+    expect(GUIDE_TAG.description).toContain(
+      "`written_for` says who a guide is written for.",
+    );
+    const wf = GUIDE_TAG.fields?.written_for;
+    expect(wf).toBeDefined();
+    expect(wf!.type).toBe("string");
+    expect(wf!.enum).toEqual(["ai", "human", "both"]);
+    // First enum value is the schema default — guides lean AI.
+    expect(wf!.enum![0]).toBe("ai");
+  });
+
+  test("PINNED_TAG is a plain identity tag (no schema)", () => {
+    expect(PINNED_TAG.name).toBe("pinned");
+    expect(PINNED_TAG.description).toBe(
+      "Notes pinned to the top of the Notes app.",
+    );
+    expect(PINNED_TAG.fields).toBeUndefined();
+  });
+});
+
+describe("welcome pack — notes-ui schema parity (containment)", () => {
+  test("welcome tags CONTAIN notes-ui's NOTES_REQUIRED_SCHEMA byte-for-byte", () => {
+    // The independent copy still matches, and the welcome pack still ships it.
     expect(NOTES_REQUIRED_TAGS).toEqual(NOTES_UI_REQUIRED_SCHEMA_TAGS);
-    expect(welcomePack().tags).toEqual(NOTES_UI_REQUIRED_SCHEMA_TAGS);
-    // Field-level byte pins (toEqual ignores key order; these don't).
-    for (const [i, expected] of NOTES_UI_REQUIRED_SCHEMA_TAGS.entries()) {
-      expect(NOTES_REQUIRED_TAGS[i]!.name).toBe(expected.name);
-      expect(NOTES_REQUIRED_TAGS[i]!.description).toBe(expected.description);
+    for (const req of NOTES_UI_REQUIRED_SCHEMA_TAGS) {
+      const found = welcomePack().tags.find((t) => t.name === req.name);
+      expect(found).toBeDefined();
+      // Field-level byte pins (toEqual ignores key order; these don't).
+      expect(found!.name).toBe(req.name);
+      expect(found!.description).toBe(req.description);
+      expect(found!.parent_names).toBeUndefined();
     }
   });
 
+  test("welcome tags = capture + guide + pinned (the guide/pinned tags ride along)", () => {
+    expect(welcomePack().tags.map((t) => t.name)).toEqual([
+      "capture",
+      "guide",
+      "pinned",
+    ]);
+    expect(welcomePack().tags).toContain(GUIDE_TAG);
+    expect(welcomePack().tags).toContain(PINNED_TAG);
+  });
+
   test("exactly ONE capture tag — no subtype tags, no parent_names (2026-07-03)", () => {
     // Entry method is metadata.source (text|voice), not taxonomy. The old
     // capture/text + capture/voice subtypes must not creep back into the seed
@@ -68,84 +139,197 @@ describe("welcome pack — notes-ui schema parity", () => {
   });
 });
 
-describe("welcome pack — person-voiced welcome web", () => {
-  test("three notes forming a linked web (welcome ⇄ try-linking, connect-AI → welcome)", () => {
+describe("welcome pack — the five-guide ring", () => {
+  test("five guides at the ratified paths, in order", () => {
     const pack = welcomePack();
     expect(pack.name).toBe("welcome");
     expect(pack.notes.map((n) => n.path)).toEqual([
       WELCOME_PATH,
-      TRY_LINKING_PATH,
+      CAPTURE_ANYTHING_PATH,
+      TAGS_GRAPH_PATH,
       CONNECT_AI_PATH,
+      YOURS_TO_KEEP_PATH,
     ]);
-
-    const [welcome, tryLinking, connectAi] = pack.notes;
-    expect(welcome!.content).toContain(`[[${TRY_LINKING_PATH}]]`);
-    expect(tryLinking!.content).toContain(`[[${WELCOME_PATH}]]`);
-    expect(connectAi!.content).toContain(`[[${WELCOME_PATH}]]`);
   });
 
-  test("content with consoleOrigin is byte-equal to the cloud's welcome copy", () => {
-    // Pinned against parachute-cloud workers/vault/src/welcome.ts
-    // `welcomeNotes(consoleOrigin)` — the sibling cloud PR swaps that module
-    // for this pack, so the ported content must not drift.
-    const origin = "https://cloud.parachute.computer";
-    const pack = welcomePack({ consoleOrigin: origin });
+  test("the link web: welcome → all four; 2→3→4→5→1; connect → Getting Started", () => {
+    const pack = welcomePack();
+
+    // Welcome wikilinks to all four siblings.
+    const welcomeLinks = wikilinkTargets(noteAt(pack, WELCOME_PATH).content);
+    for (const target of [
+      CAPTURE_ANYTHING_PATH,
+      TAGS_GRAPH_PATH,
+      CONNECT_AI_PATH,
+      YOURS_TO_KEEP_PATH,
+    ]) {
+      expect(welcomeLinks).toContain(target);
+    }
+
+    // The chain forward: 2→3, 3→4, 4→5, 5→1.
+    expect(wikilinkTargets(noteAt(pack, CAPTURE_ANYTHING_PATH).content)).toContain(
+      TAGS_GRAPH_PATH,
+    );
+    expect(wikilinkTargets(noteAt(pack, TAGS_GRAPH_PATH).content)).toContain(
+      CONNECT_AI_PATH,
+    );
+    expect(wikilinkTargets(noteAt(pack, CONNECT_AI_PATH).content)).toContain(
+      YOURS_TO_KEEP_PATH,
+    );
+    expect(wikilinkTargets(noteAt(pack, YOURS_TO_KEEP_PATH).content)).toContain(
+      WELCOME_PATH,
+    );
 
-    expect(pack.notes[0]!.content).toBe(`# ${WELCOME_PATH}
+    // Connect your AI points the human at the AI-facing Getting Started note.
+    expect(wikilinkTargets(noteAt(pack, CONNECT_AI_PATH).content)).toContain(
+      GETTING_STARTED_PATH,
+    );
+  });
 
-This vault is yours.
-Write anything.
-Notes can link to each other, like this: [[${TRY_LINKING_PATH}]].
-`);
-    expect(pack.notes[1]!.content).toBe(`# ${TRY_LINKING_PATH}
+  test("NO dangling wikilinks across the default seed (welcome + getting-started)", () => {
+    // Both packs auto-seed on create, so every [[target]] across their notes
+    // must resolve to a note one of them writes — including [[Getting Started]].
+    const seededPaths = new Set<string>([
+      ...welcomePack().notes.map((n) => n.path),
+      ...GETTING_STARTED_PACK.notes.map((n) => n.path),
+    ]);
+    for (const pack of [welcomePack(), GETTING_STARTED_PACK]) {
+      for (const note of pack.notes) {
+        for (const target of wikilinkTargets(note.content)) {
+          expect(seededPaths.has(target)).toBe(true);
+        }
+      }
+    }
+  });
 
-Wrap a note's name in double square brackets to make a wikilink, like this one back to [[${WELCOME_PATH}]].
-`);
-    expect(pack.notes[2]!.content).toBe(`# ${CONNECT_AI_PATH}
+  test("every guide is tagged #guide with metadata.written_for = human", () => {
+    for (const note of welcomePack().notes) {
+      expect(note.tags).toContain("guide");
+      expect(note.metadata).toEqual({ written_for: "human" });
+    }
+  });
 
-Your vault speaks MCP. Grab the connection URL from your console at ${origin}.
-Start from [[${WELCOME_PATH}]].
-`);
+  test("Welcome is the ONLY pinned note", () => {
+    const pinned = welcomePack().notes.filter((n) => n.tags?.includes("pinned"));
+    expect(pinned.map((n) => n.path)).toEqual([WELCOME_PATH]);
+    // Welcome carries both guide + pinned.
+    expect(noteAt(welcomePack(), WELCOME_PATH).tags).toEqual(["guide", "pinned"]);
   });
 
-  test("without consoleOrigin the Connect-AI line stays generic (no baked origin)", () => {
-    const connectAi = welcomePack().notes[2]!;
-    expect(connectAi.content).toContain(
-      "Your vault speaks MCP. Grab the connection URL from your console.",
+  test("content anchors: the ratified copy is present (guards body drift)", () => {
+    const pack = welcomePack();
+    expect(noteAt(pack, WELCOME_PATH).content).toContain("This vault is yours.");
+    expect(noteAt(pack, WELCOME_PATH).content).toContain("tagged #guide");
+    expect(noteAt(pack, CAPTURE_ANYTHING_PATH).content).toContain(
+      "The one habit that makes a vault work",
+    );
+    expect(noteAt(pack, TAGS_GRAPH_PATH).content).toContain(
+      "Notes and links come first. Tags come later",
+    );
+    expect(noteAt(pack, YOURS_TO_KEEP_PATH).content).toContain(
+      "the moral center of the",
+    );
+    // Yours to keep carries the self-host export command (backtick-wrapped).
+    expect(noteAt(pack, YOURS_TO_KEEP_PATH).content).toContain(
+      "`parachute-vault export <dir>`",
     );
-    expect(connectAi.content).not.toContain("undefined");
-    expect(connectAi.content).not.toContain("at .");
+  });
+
+  test("consoleOrigin renders both modes on the Connect-your-AI note", () => {
+    const origin = "https://cloud.parachute.computer";
+
+    // With origin: the console sentence names it, no `undefined`, no `at .`.
+    const withOrigin = noteAt(welcomePack({ consoleOrigin: origin }), CONNECT_AI_PATH);
+    expect(withOrigin.content).toContain(
+      `Grab the connection URL from your console at ${origin}.`,
+    );
+    expect(withOrigin.content).not.toContain("undefined");
+
+    // Without origin: the line stays generic — no baked loopback, no `at .`.
+    const generic = noteAt(welcomePack(), CONNECT_AI_PATH);
+    expect(generic.content).toContain(
+      "Grab the connection URL from your console.",
+    );
+    expect(generic.content).not.toContain("undefined");
+    expect(generic.content).not.toContain("at .");
+    expect(generic.content).not.toContain(origin);
   });
 });
 
 describe("getting-started pack", () => {
-  test("carries the doctrine note at the canonical path", () => {
+  test("carries the AI-facing guide note, tagged #guide / written_for ai", () => {
     expect(GETTING_STARTED_PACK.name).toBe("getting-started");
-    expect(GETTING_STARTED_PACK.tags).toEqual([]);
+    // Declares the guide tag (self-sufficient — converges with the welcome pack).
+    expect(GETTING_STARTED_PACK.tags).toEqual([GUIDE_TAG]);
     expect(GETTING_STARTED_PACK.notes).toEqual([
-      { path: GETTING_STARTED_PATH, content: GETTING_STARTED_CONTENT },
+      {
+        path: GETTING_STARTED_PATH,
+        tags: ["guide"],
+        metadata: { written_for: "ai" },
+        content: GETTING_STARTED_CONTENT,
+      },
     ]);
   });
 
+  test("the Getting Started body is byte-unchanged", () => {
+    // The AI-facing doctrine copy is not touched by the ring rewrite.
+    expect(noteAt(GETTING_STARTED_PACK, GETTING_STARTED_PATH).content).toBe(
+      GETTING_STARTED_CONTENT,
+    );
+    expect(GETTING_STARTED_CONTENT.startsWith("# Getting Started\n")).toBe(true);
+  });
+
   test("no dangling [[Surface Starter]] wikilink — points at the add-pack flow instead", () => {
     // Surface Starter is out of the default seed (ratified 2026-07-02), so the
     // default-seeded guide must not carry a wikilink to a note that doesn't
     // exist. It names the pack + the way to add it.
     expect(GETTING_STARTED_CONTENT).not.toContain("[[Surface Starter]]");
     expect(GETTING_STARTED_CONTENT).toContain("Surface Starter");
-    expect(GETTING_STARTED_CONTENT).toContain("add-pack surface-starter");
+    // Points at the add-pack flow (console affordance / CLI) without spelling
+    // out a terminal command — de-emphasise the CLI (Aaron 2026-07-06).
+    expect(GETTING_STARTED_CONTENT).toContain("add-pack");
     // The surface packages are still named for discoverability.
     expect(GETTING_STARTED_CONTENT).toContain("@openparachute/surface-client");
     expect(GETTING_STARTED_CONTENT).toContain("@openparachute/surface-render");
   });
+
+  test("Getting Started is onboarding-first + carries no dead CLI guidance (2026-07-06 rewrite)", () => {
+    // Two-part structure: onboarding conversation leads, mechanics reference follows.
+    expect(GETTING_STARTED_CONTENT).toContain("## Part 1 — Onboarding the person");
+    expect(GETTING_STARTED_CONTENT).toContain("## Part 2 — Vault mechanics");
+    // Points the person at the five human guides by name (all resolve to seeds).
+    for (const g of [WELCOME_PATH, CAPTURE_ANYTHING_PATH, TAGS_GRAPH_PATH, CONNECT_AI_PATH, YOURS_TO_KEEP_PATH]) {
+      expect(GETTING_STARTED_CONTENT).toContain("[[" + g + "]]");
+    }
+    // The old live bug: it told cloud AIs to run a CLI that doesn't exist there.
+    expect(GETTING_STARTED_CONTENT).not.toContain("parachute-vault import");
+    // Data-in leads with the import UI + MCP bridge, not the terminal.
+    expect(GETTING_STARTED_CONTENT).toContain("Import button");
+    expect(GETTING_STARTED_CONTENT).toContain("over MCP");
+  });
+
+  test("default vault-description constants orient + tell the AI to self-replace them", () => {
+    for (const d of [DEFAULT_VAULT_DESCRIPTION, IMPORTED_VAULT_DESCRIPTION]) {
+      expect(d.length).toBeGreaterThan(100);
+      expect(d).toContain("Getting Started");
+      expect(d).toContain("vault-info { description:"); // the self-replace instruction
+    }
+    expect(DEFAULT_VAULT_DESCRIPTION).toContain("brand-new");
+    expect(IMPORTED_VAULT_DESCRIPTION).toContain("imported");
+  });
 });
 
 describe("surface-starter pack", () => {
-  test("carries the surface guide at the canonical path (opt-in, not default)", () => {
+  test("carries the surface guide, tagged #guide / written_for ai (opt-in, not default)", () => {
     expect(SURFACE_STARTER_PACK.name).toBe("surface-starter");
-    expect(SURFACE_STARTER_PACK.tags).toEqual([]);
+    expect(SURFACE_STARTER_PACK.tags).toEqual([GUIDE_TAG]);
     expect(SURFACE_STARTER_PACK.notes).toEqual([
-      { path: SURFACE_STARTER_PATH, content: SURFACE_STARTER_CONTENT },
+      {
+        path: SURFACE_STARTER_PATH,
+        tags: ["guide"],
+        metadata: { written_for: "ai" },
+        content: SURFACE_STARTER_CONTENT,
+      },
     ]);
     expect(SURFACE_STARTER_PACK.description).toContain("not seeded by default");
   });

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,63 @@
  * Getting Started / Surface Starter path + content constants.
  */
 
-import type { Store } from "./types.ts";
+import type { Store, TagFieldSchema } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Default vault descriptions — the single source of truth
+// ---------------------------------------------------------------------------
+
+/**
+ * The `vault-info` description a **brand-new** vault ships with. It's the first
+ * thing a connected AI reads about the vault, so it doubles as a nudge: orient
+ * the person, read the Getting Started brief, do one small real thing, and — once
+ * real structure lands — REPLACE this text with a current picture of the vault.
+ *
+ * Exported as the single source of truth; the runtimes (bun vault default seed +
+ * cloud vault DO) consume it in a follow-up PR. Not wired into `applySeedPack`
+ * here — a description is vault metadata, not a pack note.
+ */
+export const DEFAULT_VAULT_DESCRIPTION =
+  'This is a brand-new personal vault — just its starter guides so far; the person it belongs to is probably new to Parachute. Before helping them set it up, read the "Getting Started" note — it\'s your onboarding brief. Short version: start with a conversation, not a filing system; learn how they want to use this and where their notes live today; do one small real thing first. When the vault has real structure, replace this description (vault-info { description: "..." }) with a current picture of what lives here and how to work it — so every future session, yours or another AI\'s, starts oriented.';
+
+/**
+ * The `vault-info` description a vault gets when it was **imported/restored** —
+ * it arrived with content. Flips the AI's first job from seed-it to learn-it:
+ * orient over the existing shape, reflect it back, and only then replace this
+ * text with a current picture.
+ */
+export const IMPORTED_VAULT_DESCRIPTION =
+  'This vault was imported — it arrived with its own notes, tags, and history. Orient before you write: vault-info { include_stats: true }, list-tags, read a sample, and read "Getting Started" if present. Your first job is to learn the shape that\'s already here and reflect it back to the person — not to propose new structure cold. When you understand it, replace this description (vault-info { description: "..." }) with a current picture.';
 
 // ---------------------------------------------------------------------------
 // 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 +129,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: TRY_LINKING_PATH,
-        content: `# ${TRY_LINKING_PATH}
+        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.
 
-Wrap a note's name in double square brackets to make a wikilink, like this one back to [[${WELCOME_PATH}]].
+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: 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:
+
+- #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}]].
 `,
       },
     ],
@@ -156,24 +332,98 @@ export const SURFACE_STARTER_PATH = "Surface Starter";
 /**
  * Body of the seeded `Getting Started` note.
  *
- * Voice: addressed to the connected AI ("you"), practical, SKILL.md-style.
- * Covers (a) what a Parachute vault is, (b) tags-vs-paths-vs-schemas design,
- * (c) importing existing notes, (d) that it's an adaptable starting point.
- * Mentions the Surface Starter PACK by name (no wikilink — the note isn't
- * seeded by default, and a dangling `[[Surface Starter]]` would sit unresolved
- * on every fresh vault).
+ * Voice: addressed to the connected AI ("you"), warm and practical, SKILL.md-style.
+ * ONE note, two labeled parts:
+ *   - Part 1 — Onboarding the person: lead with a real conversation, leverage
+ *     prior context, offer to survey their content, do one small real thing
+ *     first, the data-in menu (import UI / MCP bridge / paste-and-file — NOT the
+ *     CLI, NOT Obsidian-first), the arrived-with-content branch, and closing the
+ *     loop by updating the vault description (see DEFAULT_VAULT_DESCRIPTION).
+ *   - Part 2 — Vault mechanics: the preserved reference — what a vault is + the
+ *     tool list, tags-vs-paths-vs-schemas, write gotchas, the custom-surface
+ *     pointer, and "Adapt this note."
+ *
+ * Deliberately points AIs at the import UI + MCP bridge, never at a
+ * `parachute-vault import` CLI (that verb doesn't exist on cloud — the old copy
+ * shipped that live bug to every hosted user). Mentions the Surface Starter PACK
+ * by name (no wikilink — the note isn't seeded by default, and a dangling
+ * `[[Surface Starter]]` would sit unresolved on every fresh vault).
  */
 export const GETTING_STARTED_CONTENT = `# Getting Started
 
-This is the **start-here guide** for this Parachute vault — think of it like a
-\`SKILL.md\`: practical instructions for setting up and growing the vault. Read it
-when you're **getting the vault started** or orienting yourself to it — you don't
-need to re-read it every session. It's a **starting point, not a script**, and
-it's adaptable: edit it (see "Adapt this note") as the vault takes shape.
-
-When the operator says something like *"help me set up my parachute,"* this is
-your brief: design their structure with them, import what they already have, and
-shape the vault around how they actually think and work.
+This is the **start-here guide** for this Parachute vault — instructions for a
+connected AI (you), like a \`SKILL.md\`. Read it when the vault is new, when
+you're orienting yourself, or when the person says *"help me set up my
+parachute."* You don't need to re-read it every session. It has two parts:
+**how to onboard the person** (start there if they're new) and **vault
+mechanics** (reference for operating the vault). It's a starting point, not a
+script — and it's editable (see "Adapt this note" at the end).
+
+---
+
+## Part 1 — Onboarding the person
+
+### Start with a conversation, not a filing system
+
+If this vault is fresh, this is probably the person's first real session with
+it. Don't start building — orient them, briefly, in your own words: this vault
+is **their** memory, one place every AI they choose to connect can read and
+write, and they can export all of it anytime as plain markdown. Then have a
+real conversation:
+
+- **How do they imagine using this?** A journal, a project brain, a people
+  directory, meeting notes, a commonplace book — or they don't know yet
+  (that's fine; capture-first works).
+- **Where do their notes and data live now?** Another app, a pile of markdown,
+  another Parachute — or nowhere yet.
+- **What's alive for them right now?** A project, a decision, a trip, a draft.
+  The first note should be about something real.
+
+**Use what you already know.** If you have memory or context about this person
+from working with them, bring it — propose the two or three kinds of
+information *they specifically* would want here ("you mention a lot of book
+ideas — want a place for those?"). Propose, confirm, then write; never
+bulk-create structure they didn't agree to. You can also **offer to survey**
+what they already have — "want me to look through what you've brought in and
+suggest a few ways to organize it?" — then read a sample and propose, don't
+impose.
+
+### Do one small real thing first
+
+The failure mode of every notes tool is over-organizing an empty vault. So:
+**one small real thing this session.** Capture a thought they actually have,
+file one document, or bring in one small batch — then stop and show them what
+happened. Structure grows from real notes (that's Part 2's design vocabulary).
+Setup is a relationship over many sessions, not an install step.
+
+Five short guides ship in this vault for the person to read (tagged \`#guide\`):
+[[Welcome to your vault 🪂]], [[Capture anything]], [[Tags and the graph]],
+[[Connect your AI]], and [[Yours to keep]]. Point them there for anything you'd
+otherwise lecture about — they're the return-point between sessions. If a
+session ends mid-setup, leave a breadcrumb (update this note or the vault
+description) so the next one picks up where you left off.
+
+### If this vault already has content
+
+Some vaults arrive full — an import, a restore, months of use. Then your first
+job is to **learn it, not seed it**: \`vault-info { include_stats: true }\`,
+\`list-tags\`, read a sample (\`query-notes { search: "..." }\`), then reflect the
+shape back to the person and ask what's missing or wrong. Propose structure
+only once you can describe what's already there.
+
+### Close the loop: describe the vault
+
+When the first real structure lands, update the vault description —
+\`vault-info { description: "..." }\` — so every future session (yours or another
+AI's) starts oriented: what this vault is for, its main tags, its conventions.
+The default description says "brand-new vault"; once that stops being true,
+replace it. Keep it a few sentences (the projection carries the schema detail,
+and this note carries the richer conventions — see "Adapt this note"). Bringing
+their existing data in is covered under "Bringing existing notes in" below.
+
+---
+
+## Part 2 — Vault mechanics
 
 ## What a Parachute vault is
 
@@ -267,33 +517,40 @@ A few behaviors worth knowing before you write at scale:
 
 (Full design guide, with copy-paste examples: https://parachute.computer/scripting/)
 
-## Importing existing notes
+## Bringing existing notes in
+
+If the person already keeps notes somewhere, help them bring what matters —
+start with what's alive for them, not the whole archive. What works today:
 
-If the operator already keeps notes (Obsidian, Markdown, etc.), bring them in
-rather than starting cold:
+- **Connect the source over MCP (the flexible path).** If their AI client can
+  add other MCP servers — a Google Drive server, a Notion server, a filesystem
+  server — connect it alongside this vault in the same session. Then read from
+  there and \`create-note\` here: a selective, conversational migration, no
+  export file needed.
+- **Paste and file.** They paste anything — a doc, a list, an export — and you
+  \`create-note\` it (batch mode for many at once).
+- **Import a Parachute export.** Moving between Parachute vaults (cloud ⇄
+  self-host) is lossless — on Parachute Cloud, the console's Import button —
+  ids, tags, links, schemas, and attachments round-trip.
 
-- **Obsidian / a Markdown folder:** \`parachute-vault import <path>\` — preserves
-  frontmatter, tags, \`[[wikilinks]]\`, and file paths.
-- **A portable Parachute export** (a dir with \`.parachute/vault.yaml\`): the same
-  \`import\` command auto-detects it and does a lossless round-trip (ids, typed
-  links, tag schemas, attachments).
-- **Ad hoc / pasted content:** just \`create-note\` it. Then help the operator tag
-  and schematize: read a sample of imported notes, propose a small tag
-  vocabulary, and apply it.
+Bringing a whole Obsidian or Markdown library in is getting easier, and a
+flexible import is on the way; for now the connect-over-MCP and paste paths
+handle it without anyone touching a terminal. Whatever they bring, offer to
+survey it and suggest a first structure — read a sample, propose a small tag
+vocabulary, confirm, then apply. Don't impose structure silently.
 
-After an import, orient yourself: \`vault-info\` for the new schema picture,
-\`list-tags\` to see what vocabulary arrived, \`query-notes { search: "..." }\` to
-spot-check. Then propose structure — don't impose it silently.
+After bringing content in, orient: \`vault-info\` for the schema picture,
+\`list-tags\` for the vocabulary that arrived, \`query-notes { search: "..." }\`
+to spot-check.
 
 ## Later: a custom surface
 
 Building a custom UI over the vault (a dashboard, a notes app) is usually **not**
-the starting point — get the notes and structure right first. If and when the
-operator wants one, add the **Surface Starter** guide to this vault — it's a
-seed pack that isn't installed by default. Run
-\`parachute-vault add-pack surface-starter\` (or use the console's add-pack
-affordance) to seed it; it covers building a surface with
-\`@openparachute/surface-client\` + \`@openparachute/surface-render\`.
+the starting point — get the notes and structure right first. When the person
+wants one, add the **Surface Starter** guide to this vault — an optional pack
+(not installed by default) that covers building a surface with
+\`@openparachute/surface-client\` + \`@openparachute/surface-render\`. On Parachute
+Cloud it's the console's add-pack affordance.
 
 ## Adapt this note
 
@@ -313,8 +570,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 +716,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 +816,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.14",
+  "version": "0.6.5-rc.16",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

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/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 +114,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 +129,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,26 +172,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 +242,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.

package/src/vault-create.test.ts

@@ -358,11 +358,11 @@ describe("vault create — services.json registration (#208)", () => {
  * Default-pack seeding on create (originally demo-prep Workstream A — A1/A3;
  * reshaped for named seed packs).
  *
- * A freshly-created vault must contain the `welcome` pack (three-note welcome
- * web + the one capture tag Notes requires) and the `getting-started` guide — and
- * NOT the `surface-starter` pack, which is opt-in via `add-pack` (ratified
- * 2026-07-02). Idempotent + best-effort: the seed never fails a create and
- * never clobbers an edited note.
+ * A freshly-created vault must contain the `welcome` pack (the five-guide
+ * welcome ring + the capture/guide/pinned tags) and the `getting-started`
+ * guide — and NOT the `surface-starter` pack, which is opt-in via `add-pack`
+ * (ratified 2026-07-02). Idempotent + best-effort: the seed never fails a
+ * create and never clobbers an edited note.
  */
 describe("vault create — default pack seeding (welcome + getting-started)", () => {
   /** Read all (path, content) rows from a created vault's SQLite DB. */
@@ -400,23 +400,28 @@ describe("vault create — default pack seeding (welcome + getting-started)", ()
     const notes = readNotes("guided");
     const gs = notes.find((n) => n.path === "Getting Started");
     const welcome = notes.find((n) => n.path === "Welcome to your vault 🪂");
-    const tryLinking = notes.find((n) => n.path === "Try linking notes");
+    const captureAnything = notes.find((n) => n.path === "Capture anything");
+    const tagsGraph = notes.find((n) => n.path === "Tags and the graph");
     const connectAi = notes.find((n) => n.path === "Connect your AI");
+    const yoursToKeep = notes.find((n) => n.path === "Yours to keep");
     expect(gs).toBeDefined();
     expect(welcome).toBeDefined();
-    expect(tryLinking).toBeDefined();
+    expect(captureAnything).toBeDefined();
+    expect(tagsGraph).toBeDefined();
     expect(connectAi).toBeDefined();
+    expect(yoursToKeep).toBeDefined();
     expect(gs!.content).toContain("# Getting Started");
     // Surface Starter is out of the default seed — no note, no dangling link.
     expect(notes.find((n) => n.path === "Surface Starter")).toBeUndefined();
     expect(gs!.content).not.toContain("[[Surface Starter]]");
-    expect(gs!.content).toContain("add-pack surface-starter");
+    expect(gs!.content).toContain("add-pack");
 
-    // The ONE capture tag Notes requires arrives with the welcome pack —
-    // and nothing else (fresh-vault seed = 4 notes + 1 tag; the retired
+    // The capture tag Notes requires arrives with the welcome pack, alongside
+    // the guide (skill-file) + pinned tags — and nothing else (fresh-vault
+    // seed = 6 notes: the 5-guide ring + Getting Started. The retired
     // capture/text + capture/voice subtypes are no longer seeded).
-    expect(readTagNames("guided")).toEqual(["capture"]);
-    expect(notes).toHaveLength(4);
+    expect(readTagNames("guided").sort()).toEqual(["capture", "guide", "pinned"]);
+    expect(notes).toHaveLength(6);
   });
 
   test("seeding doesn't break --json stdout (notes seeded silently)", () => {