@openparachute/vault 0.6.2 → 0.6.3-rc.3

package/core/src/onboarding.ts

@@ -0,0 +1,300 @@
+/**
+ * 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.
+
+Declaring a schema is one \`update-tag\` call — the \`fields\` object maps each
+field name to \`{ type, enum?, indexed? }\` (\`type\` is \`"string"\`, \`"boolean"\`,
+or \`"integer"\`):
+
+\`\`\`
+update-tag {
+  tag: "meeting",
+  description: "A meeting with notes",
+  fields: {
+    held_on: { type: "string", indexed: true },              // queryable with operators
+    status:  { type: "string", enum: ["scheduled", "done"] }, // first enum value is the default
+    rating:  { type: "integer" }
+  }
+}
+\`\`\`
+
+\`fields\` is **merged** (new keys added, existing replaced); \`parent_names\` and
+\`relationships\` are replaced wholesale when passed. Only \`indexed: true\` fields
+support operator queries (\`metadata: { held_on: { gte: "..." } }\`) and
+\`order_by\`; all tags declaring the same field must agree on its \`type\` and
+\`indexed\` flag.
+
+## Write gotchas
+
+A few behaviors worth knowing before you write at scale:
+
+- **\`update-note\` requires optimistic concurrency by default.** Pass
+  \`if_updated_at\` with the \`updated_at\` you last read; a mismatch returns a
+  conflict error (re-read, reconcile, retry). For bulk/scripted writes where
+  concurrency is known-safe, pass \`force: true\` to waive the *requirement to
+  supply* it. \`append\`/\`prepend\`-only updates are exempt (no-conflict-by-design).
+- **A schema field's default is filled in on write, so it shows up even when you
+  didn't set it.** When a note gets a tag whose schema declares a field, the
+  missing field is back-filled: an \`enum\` field → its **first listed value**, an
+  \`integer\` → \`0\`, a \`boolean\` → \`false\`, a plain string → \`""\`. So a
+  \`rating: { type: "integer" }\` reads as \`0\` on notes nobody rated — that \`0\`
+  is "unset," not "rated zero." Order an \`enum\`'s values so the first is a sane
+  default, and don't read a back-filled \`0\`/\`""\`/\`false\` as a real value.
+- **Validation is advisory, never blocking.** A type/enum mismatch comes back as
+  a \`validation_status\` warning on the write response — the write still lands.
+  Read those warnings and self-correct on the next turn.
+
+(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.
+
+## ⚠️ Build a surface in your editor, not from this session
+
+A surface runs **in a browser**: it needs a real OAuth round-trip (a redirect to
+the hub's consent screen and back), a dev server to serve the app, and a CORS
+origin the hub trusts. **None of that exists in this MCP/chat session** — there's
+no browser, no redirect, no dev server. So **don't try to "run" a surface from
+the vault session.** Build it in **Claude Code (or your editor)** against a local
+dev server (\`vite\`/\`bun dev\`), sign in through the browser there, and iterate.
+From *this* session you design the vault structure the surface will consume and
+write the code — you can't exercise the OAuth/render loop here.
+
+## 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.
+
+## Minimal end-to-end (config → sign-in → query → render)
+
+A React sketch wiring all four steps. \`createVaultSurface\` is the only required
+config (its \`clientName\` is the sole required option; \`hubUrl\` defaults to the
+page origin, \`vaultName\` to \`"default"\`, \`scope\` to \`"vault:read vault:write"\`).
+\`getClient()\` returns a \`VaultClient\` (or \`null\` until signed in) whose
+\`queryNotes()\` takes the same query grammar you use over MCP. See
+[[Getting Started]] / \`vault-info\` for this vault's NAME and hub origin.
+
+\`\`\`tsx
+import { useEffect, useState } from "react";
+import { createVaultSurface, type Note } from "@openparachute/surface-client";
+import { NoteRenderer } from "@openparachute/surface-render";
+
+// One surface per (hub, vault) config. clientName shows on the consent screen.
+const surface = createVaultSurface({
+  clientName: "My Vault Surface",
+  hubUrl: "https://your-hub.example",   // omit to default to window.location.origin
+  vaultName: "default",                 // this vault's name (see vault-info)
+});
+
+export function App() {
+  const [notes, setNotes] = useState<Note[] | null>(null);
+
+  useEffect(() => {
+    (async () => {
+      // OAuth: finish a redirect callback if we're on it, else send the browser
+      // off to sign in. handleCallback() needs BOTH code + state, so guard on
+      // both. (Real apps route /oauth/callback to its own component.)
+      const q = new URLSearchParams(location.search);
+      if (q.get("code") && q.get("state")) await surface.handleCallback();
+      // getClient() builds a FRESH VaultClient on each call — fine here (one-shot
+      // effect); in a real component keep it in state/ref, don't call it per render.
+      const client = surface.getClient(); // VaultClient | null (null = not signed in)
+      if (!client) return void surface.login();
+      setNotes(await client.queryNotes({ tag: "note", limit: 20 }));
+    })();
+  }, []);
+
+  if (!notes) return <p>Connecting…</p>;
+  return (
+    <>
+      {notes.map((n) => (
+        // resolve maps a [[wikilink]] target → { href, exists } (or null = inert).
+        // You own this href's trust boundary — keep it a fragment (or validate the
+        // target). Don't build a raw passthrough href: a vault note could carry a
+        // javascript: target.
+        <NoteRenderer
+          key={n.id}
+          note={n}
+          resolve={(target) => ({ href: \`#/n/\${encodeURIComponent(target)}\`, exists: true })}
+        />
+      ))}
+    </>
+  );
+}
+\`\`\`
+
+That's the whole spine. \`<NoteRenderer>\` also takes \`linkComponent\` (your
+router's \`<Link>\`) and \`fetchBlob\` (\`(url) => Promise<Blob>\`, for auth'd
+image/audio embeds) when you need them — both optional.
+
+## Build order
+
+1. **Auth + data first.** Stand up \`createVaultSurface\` pointed at this vault;
+   confirm you can sign in and \`queryNotes\` 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);
   }
@@ -242,8 +273,19 @@ export function projectionToMarkdown(args: {
   vaultName: string;
   description?: string | null;
   projection: VaultProjection;
+  /**
+   * This vault's own public coordinates, surfaced so a surface-builder never has
+   * to guess the vault NAME or reconstruct the REST/MCP URLs from the connector
+   * config. When `hubOrigin` is a known absolute origin (configured
+   * `PARACHUTE_HUB_ORIGIN` or an active expose-state FQDN), the absolute base
+   * URLs are rendered; when it's only the loopback fallback (no public origin
+   * known to the vault), relative path templates are rendered with a note that
+   * the origin is whatever the client connected through. The NAME is always
+   * known and always surfaced. See `chooseHubOrigin` (src/mcp-install.ts).
+   */
+  coordinates?: { hubOrigin: string; hubOriginKnown: boolean };
 }): string {
-  const { vaultName, description, projection } = args;
+  const { vaultName, description, projection, coordinates } = args;
   const stats = projection.stats;
 
   const lines: string[] = [];
@@ -253,6 +295,40 @@ export function projectionToMarkdown(args: {
     lines.push(description.trim());
   }
 
+  // GAP 3 / vault coordinates: state the vault's own NAME + REST/MCP URLs so a
+  // surface-builder (or any scripting client) doesn't have to learn them from
+  // the MCP connector config. Absolute when the vault knows its public origin;
+  // relative templates otherwise.
+  if (coordinates) {
+    lines.push("");
+    lines.push("## This vault's coordinates");
+    lines.push("");
+    lines.push(`- Name: \`${vaultName}\``);
+    if (coordinates.hubOriginKnown) {
+      const base = coordinates.hubOrigin.replace(/\/$/, "");
+      lines.push(`- REST API base: \`${base}/vault/${vaultName}/api/...\``);
+      lines.push(`- MCP endpoint: \`${base}/vault/${vaultName}/mcp\``);
+    } else {
+      lines.push(
+        `- REST API: \`<hub-origin>/vault/${vaultName}/api/...\` — \`<hub-origin>\` is the origin you connected through (the vault has no public origin configured to render here).`,
+      );
+      lines.push(`- MCP endpoint: \`<hub-origin>/vault/${vaultName}/mcp\``);
+    }
+  }
+
+  // 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.3",
   "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

@@ -100,9 +100,23 @@ export async function getServerInstruction(
     vaultName,
     description: config?.description ?? null,
     projection,
+    coordinates: resolveVaultCoordinates(),
   });
 }
 
+/**
+ * Resolve this vault's own public coordinates for the projection. The vault
+ * always knows its NAME; its hub origin comes from `resolveHubOrigin()`
+ * (PARACHUTE_HUB_ORIGIN → expose-state FQDN → loopback). A loopback source
+ * means no public origin is configured — flagged via `hubOriginKnown: false`
+ * so the projection renders relative path templates rather than a loopback URL
+ * a remote surface-builder can't use.
+ */
+function resolveVaultCoordinates(): { hubOrigin: string; hubOriginKnown: boolean } {
+  const { url, source } = resolveHubOrigin();
+  return { hubOrigin: url, hubOriginKnown: source !== "loopback" };
+}
+
 /**
  * Generate MCP tools scoped to a single vault.
  *
@@ -482,14 +496,37 @@ function overrideVaultInfo(
     const includeStats = Boolean(params.include_stats);
     const projection = buildVaultProjection(store.db, { includeStats });
 
+    // GAP 3 / vault coordinates: surface the vault's own NAME + REST/MCP URL
+    // templates so a surface-builder doesn't have to learn them from the MCP
+    // connector config. `base_url` is absolute when the vault knows its public
+    // origin (PARACHUTE_HUB_ORIGIN / expose-state); null on a loopback-only
+    // box, where `rest_api` / `mcp` carry `<hub-origin>` placeholder templates
+    // resolved against whatever origin the client connected through.
+    const coords = resolveVaultCoordinates();
+    const coordBase = coords.hubOriginKnown ? coords.hubOrigin.replace(/\/$/, "") : "<hub-origin>";
+
     const result: Record<string, unknown> = {
       name: config.name,
       description: config.description ?? null,
+      coordinates: {
+        name: config.name,
+        base_url: coords.hubOriginKnown ? `${coordBase}/vault/${config.name}` : null,
+        rest_api: `${coordBase}/vault/${config.name}/api`,
+        mcp: `${coordBase}/vault/${config.name}/mcp`,
+      },
       tags: projection.tags,
       indexed_fields: projection.indexed_fields,
       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,222 @@
+/**
+ * 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");
+
+    // GAP 2: warn that a surface can't be run/developed from this MCP session.
+    expect(ss!.content).toContain("not from this");
+    expect(ss!.content.toLowerCase()).toContain("browser");
+
+    // GAP 1: a real, copy-paste end-to-end snippet — every load-bearing symbol
+    // present, verified against the surface-client / surface-render source.
+    expect(ss!.content).toContain("clientName"); // the one required createVaultSurface option
+    expect(ss!.content).toContain("getClient");
+    expect(ss!.content).toContain("queryNotes");
+    expect(ss!.content).toContain("handleCallback");
+    expect(ss!.content).toContain("resolve="); // NoteRenderer wikilink resolver prop
+  });
+
+  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);
+
+    // (a) a literal update-tag fields object: field name → { type, enum?, indexed? }.
+    expect(gs!.content).toContain("update-tag {");
+    expect(gs!.content).toContain('{ type: "string", indexed: true }');
+    expect(gs!.content).toContain('enum: ["scheduled", "done"]');
+
+    // (b) the write-gotchas subsection — each gotcha verified against mcp.ts.
+    expect(gs!.content).toContain("## Write gotchas");
+    expect(gs!.content).toContain("if_updated_at"); // optimistic concurrency
+    expect(gs!.content).toContain("force: true");
+    // schema-default back-fill: enum→first value, integer→0.
+    expect(gs!.content).toContain("first listed value");
+  });
+
+  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");
+  });
+});
+
+describe("vault coordinates in the projection (GAP 3)", () => {
+  test("renders absolute REST + MCP URLs when the hub origin is known", () => {
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({
+      vaultName: "research",
+      description: null,
+      projection,
+      coordinates: { hubOrigin: "https://hub.example.com", hubOriginKnown: true },
+    });
+
+    expect(md).toContain("## This vault's coordinates");
+    expect(md).toContain("Name: `research`");
+    expect(md).toContain("https://hub.example.com/vault/research/api/...");
+    expect(md).toContain("https://hub.example.com/vault/research/mcp");
+  });
+
+  test("renders relative templates + connected-origin note when origin is unknown", () => {
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({
+      vaultName: "research",
+      description: null,
+      projection,
+      coordinates: { hubOrigin: "http://127.0.0.1:1940", hubOriginKnown: false },
+    });
+
+    expect(md).toContain("## This vault's coordinates");
+    expect(md).toContain("Name: `research`");
+    // The loopback URL is NOT leaked; relative templates carry a placeholder.
+    expect(md).not.toContain("127.0.0.1");
+    expect(md).toContain("<hub-origin>/vault/research/api/...");
+    expect(md).toContain("<hub-origin>/vault/research/mcp");
+  });
+
+  test("no coordinates block when coordinates are omitted; name still in the opening line", () => {
+    const projection = buildVaultProjection(db, { includeStats: true });
+    const md = projectionToMarkdown({ vaultName: "research", description: null, projection });
+    // Without coordinates the dedicated block is absent; the vault NAME is still
+    // stated in the pre-existing opening line (the always-known coordinate).
+    expect(md).toContain('Parachute Vault "research"');
+    expect(md).not.toContain("## This vault's coordinates");
+  });
+});

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(

package/src/vault.test.ts

@@ -578,6 +578,13 @@ describe("scoped MCP wrapper", async () => {
     const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
 
+    // The GAP-3 coordinates block reads PARACHUTE_HUB_ORIGIN; another test FILE
+    // in a shared `bun test ./src` run may have left it set (cross-file env
+    // pollution — e.g. hub-jwt.test.ts). Pin loopback so the coordinates
+    // assertion below is deterministic regardless of file order; restore after.
+    const prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+
     const vaultName = `proj-${Date.now()}`;
     writeVaultConfig({
       name: vaultName,
@@ -641,12 +648,24 @@ describe("scoped MCP wrapper", async () => {
     expect(Array.isArray(result.query_hints)).toBe(true);
     expect((result.query_hints as string[]).length).toBeGreaterThan(0);
 
+    // GAP 3 — coordinates block: the vault states its own NAME + REST/MCP URL
+    // templates so a surface-builder doesn't reconstruct them from the
+    // connector config. No public hub origin in this test fixture → loopback →
+    // `<hub-origin>` placeholder templates, `base_url` null.
+    const coords = result.coordinates as Record<string, unknown>;
+    expect(coords.name).toBe(vaultName);
+    expect(coords.rest_api).toBe(`<hub-origin>/vault/${vaultName}/api`);
+    expect(coords.mcp).toBe(`<hub-origin>/vault/${vaultName}/mcp`);
+    expect(coords.base_url).toBeNull();
+
     // stats omitted unless requested
     expect(result.stats).toBeUndefined();
 
     const withStats = await vaultInfo.execute({ include_stats: true }) as any;
     expect(withStats.stats).toBeTruthy();
 
+    if (prevHubOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
+    else process.env.PARACHUTE_HUB_ORIGIN = prevHubOrigin;
     closeAllStores();
   });