@openparachute/vault 0.6.2 → 0.6.3-rc.1

package/core/src/onboarding.ts

@@ -0,0 +1,185 @@
+/**
+ * Onboarding doctrine — the in-vault guide a freshly-created vault seeds so a
+ * connected AI can self-orient and set the vault up on the operator's behalf.
+ *
+ * This module is the single source of truth for the *content* + the *paths* of
+ * the seeded notes. It lives in `core` (not `src`) so both:
+ *   - the seeding path (`src/onboarding-seed.ts`, called from `createVault`), and
+ *   - the projection/`vault-info` pointer (`core/src/vault-projection.ts`)
+ * can share the canonical note paths without a cross-layer import.
+ *
+ * The notes are AI-legible, practical (SKILL.md-style) guides addressed to the
+ * assistant that connects to the vault. They are a starting point, not gospel —
+ * Getting Started tells the AI it can adapt them as the vault matures. Seeding is
+ * create-time only and idempotent (never clobbers a note the operator/AI has
+ * since edited).
+ *
+ * See the demo-prep Workstream A (A1/A2/A3).
+ */
+
+/** Canonical path of the seeded onboarding guide. Top-level, title-cased so it
+ *  reads as a doc and sorts to the top of a casual file listing. */
+export const GETTING_STARTED_PATH = "Getting Started";
+
+/** Canonical path of the seeded surface-build starter, linked from Getting
+ *  Started. */
+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.
+ */
+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.
+
+## What a Parachute vault is
+
+A vault is **notes + tags + links** in one graph, reachable over MCP (you, now),
+a REST API (scripts), and any surface (a UI). It ships *blank* — no predefined
+tags or schema. You and the operator design the structure that fits *their*
+life and work. The vault is the engine; the meaning is yours to bring.
+
+Core moves you already have as MCP tools:
+- \`create-note\` / \`update-note\` / \`delete-note\` — write notes (single or batch).
+- \`query-notes\` — by id/path, by tag, full-text \`search\`, or graph \`near\` a note.
+- \`list-tags\` / \`update-tag\` / \`delete-tag\` — manage the tag vocabulary + schemas.
+- \`find-path\` — shortest link path between two notes.
+- \`vault-info\` — refresh the live schema/stats projection any time.
+
+\`[[wikilinks]]\` in note content auto-link to the note at that path — use them
+freely; they resolve even if the target is created later.
+
+## Tags vs paths vs schemas — the design vocabulary
+
+These three axes are the heart of vault design. Use the right one for the job:
+
+- **Tags = types / membership.** A tag answers *"what kind of thing is this?"*
+  (\`#person\`, \`#meeting\`, \`#project\`). Queries **expand over tags**: a tag can
+  declare \`parent_names\` so \`tag:X\` also returns its subtypes (e.g. tagging a
+  note \`#meeting/standup\` with \`parent_names: [meeting]\` means \`query-notes
+  { tag: "meeting" }\` finds it). Tags are how you ask *"show me all my people."*
+  This is the primary structure — reach for a tag first.
+
+- **Paths = organization / filing.** A path (\`Projects/Acme/Kickoff\`) is *where*
+  a note lives — a human-browsable address, unique per note. Paths are for
+  folders and named docs (like this one). They do **not** drive type queries;
+  don't encode meaning in a path that a tag should carry. A note can have a
+  path, tags, or both.
+
+- **Schemas = typed metadata fields.** Attach a schema to a tag (via
+  \`update-tag\`) to declare typed metadata fields — e.g. \`#meeting\` with a
+  \`held_on\` date, \`#person\` with an \`email\`. Each field can **optionally** be
+  marked \`indexed: true\` to make it **queryable with operators** (\`query-notes
+  { tag: "meeting", metadata: { held_on: { gte: "2026-01-01" } } }\`); indexing
+  is opt-in per field, not automatic. Add a schema (and index a field) when you
+  find yourself wanting to filter or sort on a value, not before.
+
+Rule of thumb: **type with tags, file with paths, make-it-queryable with
+schemas.** Start minimal — invent tags as real notes need them, declare a
+schema only when a query demands it. Over-designing an empty vault is the
+common mistake.
+
+(Full design guide, with copy-paste examples: https://parachute.computer/scripting/)
+
+## Importing existing notes
+
+If the operator already keeps notes (Obsidian, Markdown, etc.), bring them in
+rather than starting cold:
+
+- **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.
+
+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.
+
+## 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, see **[[Surface Starter]]** (built with
+\`@openparachute/surface-client\` + \`@openparachute/surface-render\`).
+
+## Adapt this note
+
+This guide is a **default starting point, not gospel** — edit it to fit this
+vault. As you and the operator settle on a tag vocabulary, conventions, or a
+surface, you can record that here so a future session inherits the current shape
+of the vault instead of this blank-slate default. Useful things to capture:
+- the tag vocabulary you've settled on and what each tag means;
+- naming/path conventions for this vault;
+- which schemas exist and why;
+- anything a fresh AI would need to be immediately useful.
+
+Treat setup as a relationship, not a one-time install.
+`;
+
+/**
+ * Body of the seeded `Surface Starter` note. Linked from Getting Started.
+ *
+ * A concise, *living* starter prompt for building a custom surface (UI) over
+ * the vault using the published surface packages. Tells the AI to import the
+ * packages rather than hand-roll OAuth/API/rendering.
+ */
+export const SURFACE_STARTER_CONTENT = `# Surface Starter
+
+A **surface** is a custom UI over this vault — a dashboard, a notes app, a
+single-purpose tool. This note is a living starter for building one *with the
+operator*. Update it as you settle on a stack, conventions, or a deployed
+surface for this vault.
+
+## Don't hand-roll the plumbing
+
+Two published packages do the heavy lifting — import them instead of writing
+OAuth, the vault API client, or note rendering by hand:
+
+- **\`@openparachute/surface-client\`** — \`createVaultSurface(...)\` wires up
+  Parachute OAuth (sign-in on first connect) and a typed vault API client
+  (query/create/update notes, tags, links) so your app code just calls methods.
+- **\`@openparachute/surface-render\`** — \`<NoteRenderer>\` and friends render note
+  content (Markdown, wikilinks, embeds) the way the rest of the ecosystem does,
+  so your surface looks native without re-implementing the renderer.
+
+## Build order
+
+1. **Auth + data first.** Stand up \`createVaultSurface\` pointed at this vault;
+   confirm you can sign in and \`query-notes\` round-trips before any UI polish.
+2. **Render next.** Drop in \`<NoteRenderer>\` to display note content; wire
+   wikilink/embed resolution through the package, not by hand.
+3. **UX last.** Layout, navigation, and the surface's actual purpose — now that
+   auth, data, and rendering are solid.
+
+## Design it around this vault's structure
+
+A good surface is shaped by the vault's tags + schemas (see [[Getting Started]]
+for the tags-vs-paths-vs-schemas design vocabulary). Query by the tags that
+matter to the operator; surface the indexed fields they filter on. If the vault
+doesn't yet have the structure a surface wants, that's a signal to design tags +
+schemas first.
+
+## Adapt this note
+
+When you build a surface for this vault, record it here: what it's for, the
+stack, how to run it, the queries it depends on. The next session should be able
+to pick it up from this note.
+
+(More on the surface stack + examples: https://parachute.computer/scripting/)
+`;

package/core/src/vault-projection.ts

@@ -33,6 +33,23 @@ import {
 import { DEFAULT_TAG_NAME } from "./tag-hierarchy.ts";
 import * as noteOps from "./notes.ts";
 import type { VaultStats } from "./types.ts";
+import { GETTING_STARTED_PATH } from "./onboarding.ts";
+
+/**
+ * Does a note live at the seeded onboarding path? Used to gate the "Start here"
+ * pointer so it only fires when the guide actually exists (fresh vaults seed it;
+ * pre-existing vaults that never seeded one shouldn't dangle a dead pointer).
+ */
+function hasGettingStartedNote(db: Database): boolean {
+  try {
+    const row = db
+      .query("SELECT 1 FROM notes WHERE path = ? LIMIT 1")
+      .get(GETTING_STARTED_PATH);
+    return row != null;
+  } catch {
+    return false;
+  }
+}
 
 // ---------------------------------------------------------------------------
 // Types
@@ -76,6 +93,14 @@ export interface VaultProjection {
   tags: ProjectionTag[];
   indexed_fields: ProjectionIndexedField[];
   query_hints: string[];
+  /**
+   * Path of the seeded onboarding guide, when present. A pointer (NOT the note
+   * body) so any connected AI is steered to read `Getting Started` first, every
+   * session — the AI fetches it with `query-notes { id: "<path>" }`. Omitted
+   * when no such note exists (older vaults that never seeded one). See
+   * core/src/onboarding.ts.
+   */
+  getting_started?: string;
   /** Included when the caller requests stats; omitted otherwise. */
   stats?: VaultStats;
 }
@@ -210,6 +235,12 @@ export function buildVaultProjection(
     query_hints: [...QUERY_HINTS],
   };
 
+  // A2: point any connected AI at the seeded onboarding guide (a path pointer,
+  // never the body). Only when the note actually exists.
+  if (hasGettingStartedNote(db)) {
+    projection.getting_started = GETTING_STARTED_PATH;
+  }
+
   if (opts?.includeStats) {
     projection.stats = noteOps.getVaultStats(db);
   }
@@ -253,6 +284,19 @@ export function projectionToMarkdown(args: {
     lines.push(description.trim());
   }
 
+  // A2: surface the seeded onboarding guide so a connected AI can discover it
+  // when setting up or orienting. A pointer only — the AI fetches the body on
+  // demand. NOT a mandate to re-read every session; it's a start-here guide.
+  if (projection.getting_started) {
+    lines.push("");
+    lines.push(
+      `## Start here\n\nThis vault has a **${projection.getting_started}** guide — how to set it up ` +
+        `and grow it (what a Parachute vault is, designing tags vs paths vs schemas, importing ` +
+        `existing notes). Read it when setting up or getting oriented, or when the operator asks ` +
+        `for help setting up their parachute. Fetch it with \`query-notes { id: "${projection.getting_started}" }\`.`,
+    );
+  }
+
   lines.push("");
   lines.push("## Quick orientation (call `vault-info` for full schema)");
   lines.push("");

package/package.json

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

package/src/cli.ts

@@ -107,6 +107,7 @@ import { VAULT_SCOPES } from "./scopes.ts";
 import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
 import { decideAutostart } from "./autostart.ts";
 import { getVaultStore } from "./vault-store.ts";
+import { seedOnboardingNotesBestEffort } from "./onboarding-seed.ts";
 import {
   defaultMirrorConfig,
   resolveMirrorPath,
@@ -3639,7 +3640,14 @@ async function createVault(
 
   // Touch the store so the vault's SQLite DB + schema are created. No token
   // row is written — vault is a pure hub resource-server post-0.5.0.
-  getVaultStore(name);
+  const seedStore = getVaultStore(name);
+
+  // Seed the in-vault onboarding guide (Getting Started + Surface Starter) so a
+  // connected AI can read it and help the operator set the vault up. Idempotent
+  // + best-effort: only writes notes that are absent, and never fails the
+  // create. Runs BEFORE the mirror bootstrap so the seeded notes land in the
+  // initial mirror commit. See src/onboarding-seed.ts + core/src/onboarding.ts.
+  await seedOnboardingNotesBestEffort(seedStore);
 
   // Default new vaults to an internal live mirror (local git backup of the
   // markdown projection). Backup-on-by-default; GitHub off-site backup is an

package/src/mcp-tools.ts

@@ -490,6 +490,14 @@ function overrideVaultInfo(
       query_hints: projection.query_hints,
     };
 
+    // A2: surface a pointer (path, not body) to the seeded onboarding guide so
+    // any connected AI is steered to read it first. Present only when the note
+    // exists (buildVaultProjection gates on it). Older vaults without one omit
+    // the field entirely.
+    if (projection.getting_started) {
+      result.getting_started = projection.getting_started;
+    }
+
     if (projection.stats) {
       result.stats = projection.stats;
     }

package/src/onboarding-seed.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Unit tests for the onboarding-guide seeding (demo-prep Workstream A — A1/A2/A3).
+ *
+ * Store-direct (no CLI subprocess) so they're fast. Covers:
+ *   - A1: seedOnboardingNotes writes Getting Started + Surface Starter.
+ *   - A3: Surface Starter is linked from Getting Started (wikilink).
+ *   - idempotency: a re-run never clobbers an edited note.
+ *   - A2: the projection / vault-info pointer steers the AI at Getting Started.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { BunStore } from "./vault-store.ts";
+import { seedOnboardingNotes } from "./onboarding-seed.ts";
+import {
+  GETTING_STARTED_PATH,
+  SURFACE_STARTER_PATH,
+} from "../core/src/onboarding.ts";
+import {
+  buildVaultProjection,
+  projectionToMarkdown,
+} from "../core/src/vault-projection.ts";
+
+let db: Database;
+let store: BunStore;
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = join(tmpdir(), `onboarding-seed-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(tmpDir, { recursive: true });
+  db = new Database(join(tmpDir, "test.db"));
+  store = new BunStore(db);
+});
+
+afterEach(() => {
+  db.close();
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("seedOnboardingNotes (A1/A3)", () => {
+  test("seeds Getting Started + Surface Starter on a blank vault", async () => {
+    const result = await seedOnboardingNotes(store);
+    expect(result.seeded.sort()).toEqual(
+      [GETTING_STARTED_PATH, SURFACE_STARTER_PATH].sort(),
+    );
+    expect(result.skipped).toEqual([]);
+
+    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
+    expect(gs).not.toBeNull();
+    expect(gs!.content).toContain("# Getting Started");
+    // A1 doctrine markers: tags-as-types, the three-axis design vocab, import,
+    // and the living-note instruction.
+    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");
+    expect(gs!.content).toContain("Adapt this note");
+
+    const ss = await store.getNoteByPath(SURFACE_STARTER_PATH);
+    expect(ss).not.toBeNull();
+    expect(ss!.content).toContain("# Surface Starter");
+    // A3: the two surface packages by name.
+    expect(ss!.content).toContain("@openparachute/surface-client");
+    expect(ss!.content).toContain("@openparachute/surface-render");
+    expect(ss!.content).toContain("createVaultSurface");
+    expect(ss!.content).toContain("NoteRenderer");
+  });
+
+  test("A3: Getting Started links to Surface Starter via a resolved wikilink", async () => {
+    await seedOnboardingNotes(store);
+    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
+    expect(gs!.content).toContain("[[Surface Starter]]");
+
+    // Wikilink auto-resolution: Getting Started → Surface Starter link row.
+    const ss = await store.getNoteByPath(SURFACE_STARTER_PATH);
+    const outbound = await store.getLinks(gs!.id, { direction: "outbound" });
+    expect(outbound.some((l) => l.targetId === ss!.id)).toBe(true);
+  });
+
+  test("idempotent: a second seed run skips both (does not duplicate)", async () => {
+    await seedOnboardingNotes(store);
+    const second = await seedOnboardingNotes(store);
+    expect(second.seeded).toEqual([]);
+    expect(second.skipped.sort()).toEqual(
+      [GETTING_STARTED_PATH, SURFACE_STARTER_PATH].sort(),
+    );
+
+    // Exactly one note per path — no duplicates.
+    const all = await store.queryNotes({});
+    expect(all.filter((n) => n.path === GETTING_STARTED_PATH)).toHaveLength(1);
+    expect(all.filter((n) => n.path === SURFACE_STARTER_PATH)).toHaveLength(1);
+  });
+
+  test("idempotent: never clobbers an operator-edited Getting Started", async () => {
+    await seedOnboardingNotes(store);
+    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
+
+    // Operator/AI rewrites the note — the living-note case.
+    const edited = "# Getting Started\n\nThis vault is for my book research.";
+    await store.updateNote(gs!.id, { content: edited });
+
+    // Re-seed (simulates a re-init / restart): the edit must survive untouched.
+    const rerun = await seedOnboardingNotes(store);
+    expect(rerun.seeded).toEqual([]);
+    const after = await store.getNoteByPath(GETTING_STARTED_PATH);
+    expect(after!.content).toBe(edited);
+  });
+});
+
+describe("vault-info / projection pointer (A2)", () => {
+  test("projection carries getting_started when the note exists", async () => {
+    // Absent before seeding → no pointer.
+    const before = buildVaultProjection(db);
+    expect(before.getting_started).toBeUndefined();
+
+    await seedOnboardingNotes(store);
+    const after = buildVaultProjection(db);
+    expect(after.getting_started).toBe(GETTING_STARTED_PATH);
+  });
+
+  test("connect-time markdown brief steers the AI to read Getting Started first", async () => {
+    await seedOnboardingNotes(store);
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({
+      vaultName: "fresh",
+      description: null,
+      projection,
+    });
+
+    expect(md).toContain("## Start here");
+    expect(md).toContain(GETTING_STARTED_PATH);
+    // It's a POINTER, not the embedded body — the fetch command appears, the
+    // note's distinctive body copy does not.
+    expect(md).toContain(`query-notes { id: "${GETTING_STARTED_PATH}" }`);
+    expect(md).not.toContain("Adapt this note");
+  });
+
+  test("no Start-here block on a vault without the guide (back-compat)", async () => {
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({
+      vaultName: "legacy",
+      description: null,
+      projection,
+    });
+    expect(md).not.toContain("## Start here");
+  });
+});

package/src/onboarding-seed.ts

@@ -0,0 +1,83 @@
+/**
+ * Seed the in-vault onboarding guide on vault creation.
+ *
+ * A freshly-created vault gets a `Getting Started` note (AI-legible doctrine)
+ * and a linked `Surface Starter` note, so a connected AI can read the guide and
+ * help the operator set the vault up — and keep growing it over time.
+ *
+ * IDEMPOTENT + create-time only: each note is written ONLY when absent. A
+ * re-init, restart, or re-run never clobbers a note the operator/AI has since
+ * edited. Existing vaults are unaffected — this runs on the create path, not as
+ * a sweep over existing vaults.
+ *
+ * Best-effort + non-fatal: seeding must NEVER fail a vault create. Any error is
+ * caught and logged; the vault is still usable without the guide.
+ *
+ * See the demo-prep Workstream A (A1/A2/A3).
+ */
+
+import {
+  GETTING_STARTED_PATH,
+  GETTING_STARTED_CONTENT,
+  SURFACE_STARTER_PATH,
+  SURFACE_STARTER_CONTENT,
+} from "../core/src/onboarding.ts";
+import type { Store } from "../core/src/types.ts";
+
+interface SeedResult {
+  /** Paths actually written this run (absent ones). Empty when both pre-existed. */
+  seeded: string[];
+  /** Paths skipped because the note already existed (idempotency). */
+  skipped: string[];
+}
+
+/**
+ * Write a single onboarding note only if no note already lives at `path`.
+ * Returns true when it wrote (was absent), false when it skipped (present).
+ */
+async function seedNoteIfAbsent(
+  store: Store,
+  path: string,
+  content: string,
+): Promise<boolean> {
+  const existing = await store.getNoteByPath(path);
+  if (existing) return false;
+  await store.createNote(content, { path });
+  return true;
+}
+
+/**
+ * Seed the onboarding notes into `store`, idempotently. Surface Starter is
+ * created first so the `[[Surface Starter]]` wikilink in Getting Started
+ * resolves immediately (the create path also auto-resolves later, but this
+ * keeps the link live from the first write).
+ */
+export async function seedOnboardingNotes(store: Store): Promise<SeedResult> {
+  const seeded: string[] = [];
+  const skipped: string[] = [];
+
+  for (const [path, content] of [
+    [SURFACE_STARTER_PATH, SURFACE_STARTER_CONTENT],
+    [GETTING_STARTED_PATH, GETTING_STARTED_CONTENT],
+  ] as const) {
+    const wrote = await seedNoteIfAbsent(store, path, content);
+    (wrote ? seeded : skipped).push(path);
+  }
+
+  return { seeded, skipped };
+}
+
+/**
+ * Best-effort wrapper for the create path: seed the onboarding notes, swallow
+ * and log any error so a seeding failure never fails the vault create.
+ */
+export async function seedOnboardingNotesBestEffort(store: Store): Promise<void> {
+  try {
+    await seedOnboardingNotes(store);
+  } catch (err) {
+    console.error(
+      `Note: onboarding guide not seeded (${(err as Error)?.message ?? err}). ` +
+        `The vault was still created; you can connect an AI and ask it to set things up.`,
+    );
+  }
+}

package/src/server.ts

@@ -20,6 +20,7 @@ import { existsSync, rmSync } from "fs";
 import { migrateVaultKeys } from "./token-store.ts";
 import { resolveFirstBootVaultName, reservedNameSquatWarnings } from "./vault-name.ts";
 import { getVaultStore, getVaultNameForStore } from "./vault-store.ts";
+import { seedOnboardingNotesBestEffort } from "./onboarding-seed.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
 import { registerTriggers } from "./triggers.ts";
 import { loadVaultTriggers } from "./triggers-api.ts";
@@ -205,6 +206,10 @@ if (listVaults().length === 0) {
     }
     writeGlobalConfig(globalConfig);
     console.log(`Auto-created vault "${vaultName}" (API key: ${fullKey})`);
+    // Seed the in-vault onboarding guide so a connected AI can self-orient and
+    // help set the vault up — same as the `create`/`init` CLI path. Idempotent
+    // + best-effort (never fails first boot). Mirrors createVault() in cli.ts.
+    await seedOnboardingNotesBestEffort(getVaultStore(vaultName));
   }
 }
 

package/src/vault-create.test.ts

@@ -9,6 +9,7 @@
  */
 
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
 import { resolve } from "path";
 import {
   mkdtempSync,
@@ -353,6 +354,51 @@ describe("vault create — services.json registration (#208)", () => {
   });
 });
 
+/**
+ * Onboarding-guide seeding on create (demo-prep Workstream A — A1/A3).
+ *
+ * A freshly-created vault must contain the `Getting Started` + `Surface Starter`
+ * notes so a connected AI can read them and help set the vault up. Idempotent +
+ * best-effort: the seed never fails a create and never clobbers an edited note.
+ */
+describe("vault create — onboarding guide seeding (A1/A3)", () => {
+  /** Read all (path, content) rows from a created vault's SQLite DB. */
+  function readNotes(name: string): { path: string | null; content: string }[] {
+    const dbPath = join(home, "vault", "data", name, "vault.db");
+    const db = new Database(dbPath, { readonly: true });
+    try {
+      return db
+        .query("SELECT path, content FROM notes")
+        .all() as { path: string | null; content: string }[];
+    } finally {
+      db.close();
+    }
+  }
+
+  test("create seeds Getting Started + Surface Starter notes", () => {
+    const { exitCode } = runCli(["create", "guided", "--json"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(exitCode).toBe(0);
+
+    const notes = readNotes("guided");
+    const gs = notes.find((n) => n.path === "Getting Started");
+    const ss = notes.find((n) => n.path === "Surface Starter");
+    expect(gs).toBeDefined();
+    expect(ss).toBeDefined();
+    expect(gs!.content).toContain("# Getting Started");
+    expect(gs!.content).toContain("[[Surface Starter]]");
+    expect(ss!.content).toContain("@openparachute/surface-client");
+  });
+
+  test("seeding doesn't break --json stdout (notes seeded silently)", () => {
+    const { stdout } = runCli(["create", "jsonclean", "--json"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(() => JSON.parse(stdout.trim())).not.toThrow();
+  });
+});
+
 describe("vault create (human mode)", () => {
   test("prints multi-line human output without --json", () => {
     const { exitCode, stdout } = runCli(