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

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

@@ -1,35 +1,46 @@
 /**
  * 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,
   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 +58,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,65 +136,146 @@ 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,
+    );
+
+    // 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,
+    );
+  });
 
-    expect(pack.notes[0]!.content).toBe(`# ${WELCOME_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);
+        }
+      }
+    }
+  });
 
-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("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" });
+    }
+  });
 
-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("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"]);
+  });
 
-Your vault speaks MCP. Grab the connection URL from your console at ${origin}.
-Start from [[${WELCOME_PATH}]].
-`);
+  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>`",
+    );
   });
 
-  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("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(connectAi.content).not.toContain("undefined");
-    expect(connectAi.content).not.toContain("at .");
+    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
@@ -141,11 +290,16 @@ describe("getting-started pack", () => {
 });
 
 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,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.14",
+  "version": "0.6.5-rc.15",
   "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,
 ];
 
@@ -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.

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");
 
-    // 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)", () => {