@openparachute/vault 0.6.5-rc.1 → 0.6.5-rc.11

package/core/src/do-param-cap.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Behavioral proof that the id-list query paths stay under the Cloudflare
+ * Durable Object SQLite 100-bound-param cap over a real >100-note vault.
+ *
+ * bun:sqlite tolerates 999+ bound params, so it CANNOT reproduce the DO
+ * `too many SQL variables` 500 directly — the ultimate DO-constraint proof is
+ * the cloud staging export re-verify (orchestrator's post-merge step). What we
+ * CAN prove locally, and what actually catches the regression that let the bug
+ * ship, is the *shape* of the SQL each path issues: no single prepared
+ * statement binds more than the chunk size (chunked lists) or a handful of
+ * params (json_each id-sets). A prepare-spy records the max bind count per
+ * statement; if a future edit raises the chunk size back over the cap, the
+ * placeholder-IN assertion here fails.
+ *
+ * Root cause recap: DO SQLite caps bound params at 100/statement. The export
+ * walk pages 500 notes at a time and hydrated each page's rows + tags with an
+ * `id IN (?×page)` list sized for standard SQLite's 999 floor → >100 params →
+ * DO 500. Fix: chunk id-lists at 90 (sql-in.ts) and bind embedded id-sets
+ * (e.g. `near` neighborhoods) as one json_each param.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { existsSync, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import { SqliteStore } from "./store.js";
+import { exportVaultToDir } from "./portable-md.js";
+import { IN_PARAM_CHUNK } from "./sql-in.js";
+
+/** Zero-padded so lexicographic id order == numeric order. */
+const pad = (i: number): string => String(i).padStart(5, "0");
+
+/** Wrap `db.prepare` to record the max bind-arg count seen per SQL string.
+ *  Install AFTER seeding so bulk-insert params don't pollute the sample. */
+function installBindSpy(db: Database) {
+  const perSql = new Map<string, number>();
+  const origPrepare = db.prepare.bind(db);
+  (db as unknown as { prepare: (sql: string) => unknown }).prepare = (sql: string) => {
+    const stmt = origPrepare(sql) as Record<string, unknown>;
+    const record = (n: number) => perSql.set(sql, Math.max(perSql.get(sql) ?? 0, n));
+    for (const m of ["all", "get", "run", "values", "iterate"] as const) {
+      const orig = stmt[m];
+      if (typeof orig === "function") {
+        stmt[m] = (...args: unknown[]) => {
+          record(args.length);
+          return (orig as (...a: unknown[]) => unknown).apply(stmt, args);
+        };
+      }
+    }
+    return stmt;
+  };
+  return {
+    restore() {
+      (db as unknown as { prepare: unknown }).prepare = origPrepare;
+    },
+    /** Max binds over statements carrying a literal `IN (?, …)` placeholder
+     *  list — the chunked kind that must never exceed the chunk size. */
+    maxPlaceholderInBinds(): number {
+      let max = 0;
+      for (const [sql, n] of perSql) if (/\bIN \(\?/.test(sql)) max = Math.max(max, n);
+      return max;
+    },
+    /** Max binds over ALL statements — must stay under the DO cap. */
+    maxAnyBinds(): number {
+      let max = 0;
+      for (const n of perSql.values()) max = Math.max(max, n);
+      return max;
+    },
+    usedJsonEach(): boolean {
+      for (const sql of perSql.keys()) if (/json_each\(/.test(sql)) return true;
+      return false;
+    },
+  };
+}
+
+const DO_PARAM_CAP = 100;
+
+describe("id-list query paths stay under the DO 100-bound-param cap", () => {
+  let store: SqliteStore;
+  let db: Database;
+
+  beforeEach(async () => {
+    db = new Database(":memory:");
+    store = new SqliteStore(db);
+    // 250 notes > the DO cap and > 2× the chunk size, so chunking spans
+    // multiple chunks (250 = 90 + 90 + 70).
+    const inputs = [];
+    for (let i = 0; i < 250; i++) {
+      inputs.push({ content: `note ${i}`, id: `n${pad(i)}`, path: `notes/n${pad(i)}` });
+    }
+    await store.createNotes(inputs);
+  });
+
+  it("getNotes chunks a >100-id fetch (correct rows, no statement over the cap)", async () => {
+    const ids = Array.from({ length: 250 }, (_, i) => `n${pad(i)}`);
+    const spy = installBindSpy(db);
+    try {
+      const notes = await store.getNotes(ids);
+      // Correctness: every requested note returned, ordered by created_at then id.
+      expect(notes.length).toBe(250);
+      expect(notes.map((n) => n.id)).toEqual(ids);
+    } finally {
+      spy.restore();
+    }
+    // Regression guard: no IN-list statement binds more than the chunk size...
+    expect(spy.maxPlaceholderInBinds()).toBeLessThanOrEqual(IN_PARAM_CHUNK);
+    // ...and nothing at all trips the DO cap.
+    expect(spy.maxAnyBinds()).toBeLessThanOrEqual(DO_PARAM_CAP);
+  });
+
+  it("queryNotes over a >100-id set (the `near` path) binds the set as one json_each param", async () => {
+    const ids = Array.from({ length: 150 }, (_, i) => `n${pad(i)}`);
+    const spy = installBindSpy(db);
+    let notes;
+    try {
+      notes = await store.queryNotes({ ids, limit: 1000, sort: "asc" });
+    } finally {
+      spy.restore();
+    }
+    // Correctness: all 150 in-set notes returned.
+    expect(notes.length).toBe(150);
+    // The id-set filter rode a single json_each param, not 150 placeholders...
+    expect(spy.usedJsonEach()).toBe(true);
+    // ...so no statement — including the phase-1 id select carrying the set —
+    // exceeds the DO cap, and the phase-2 chunked hydration stays under it.
+    expect(spy.maxPlaceholderInBinds()).toBeLessThanOrEqual(IN_PARAM_CHUNK);
+    expect(spy.maxAnyBinds()).toBeLessThanOrEqual(DO_PARAM_CAP);
+  });
+
+  it("empty id-set still short-circuits (no json_each, no rows)", async () => {
+    const notes = await store.queryNotes({ ids: [], limit: 10 });
+    expect(notes.length).toBe(0);
+  });
+
+  describe("export a >100-note vault", () => {
+    let outDir: string;
+    beforeEach(() => { outDir = mkdtempSync(join(tmpdir(), "do-cap-export-")); });
+    afterEach(() => { try { rmSync(outDir, { recursive: true, force: true }); } catch {} });
+
+    it("exports all 250 notes with no statement over the cap (the shipped bug)", async () => {
+      const spy = installBindSpy(db);
+      let stats;
+      try {
+        stats = await exportVaultToDir(store, { outDir, exportedAt: "2026-07-03T00:00:00.000Z" });
+      } finally {
+        spy.restore();
+      }
+      // Correctness: every note on disk.
+      expect(stats.notes).toBe(250);
+      expect(existsSync(join(outDir, "notes/n00000.md"))).toBe(true);
+      expect(existsSync(join(outDir, "notes/n00090.md"))).toBe(true); // first chunk boundary
+      expect(existsSync(join(outDir, "notes/n00249.md"))).toBe(true); // tail
+      // The bug: the export page's `id IN (?×page)` hydration exceeded 100 on
+      // DO. Now every IN-list statement stays under the chunk size...
+      expect(spy.maxPlaceholderInBinds()).toBeLessThanOrEqual(IN_PARAM_CHUNK);
+      // ...and no statement trips the DO cap.
+      expect(spy.maxAnyBinds()).toBeLessThanOrEqual(DO_PARAM_CAP);
+    });
+  });
+});

package/core/src/links.ts

@@ -1,6 +1,7 @@
 import { Database } from "bun:sqlite";
 import type { Link, NoteSummary, HydratedLink } from "./types.js";
 import { getNoteTagsForNotes } from "./notes.js";
+import { chunkForInClause } from "./sql-in.js";
 
 export function createLink(
   db: Database,
@@ -103,16 +104,13 @@ function parseMetadata(raw: string | null): Record<string, unknown> | undefined
   try { return JSON.parse(raw); } catch { return undefined; }
 }
 
-/** IN-list chunk size — matches getLinkCounts' conservative bound-variable floor. */
-const IN_CHUNK = 900;
-
 function getNoteSummaries(db: Database, noteIds: string[]): Map<string, NoteSummary> {
   const map = new Map<string, NoteSummary>();
   if (noteIds.length === 0) return map;
   const ids = [...new Set(noteIds)];
   const rows: SummaryRow[] = [];
-  for (let i = 0; i < ids.length; i += IN_CHUNK) {
-    const chunk = ids.slice(i, i + IN_CHUNK);
+  // Chunk under the DO 100-bound-param cap (see sql-in.ts).
+  for (const chunk of chunkForInClause(ids)) {
     const placeholders = chunk.map(() => "?").join(", ");
     rows.push(...db.prepare(
       `SELECT id, path, metadata, created_at, updated_at FROM notes WHERE id IN (${placeholders})`,
@@ -193,8 +191,8 @@ export function getLinksHydratedForNotes(
   // (source, target, relationship) primary key so a link whose endpoints
   // are both on the page is fetched once.
   const rowsByKey = new Map<string, LinkRow>();
-  for (let i = 0; i < ids.length; i += IN_CHUNK) {
-    const chunk = ids.slice(i, i + IN_CHUNK);
+  // Chunk under the DO 100-bound-param cap (see sql-in.ts).
+  for (const chunk of chunkForInClause(ids)) {
     const placeholders = chunk.map(() => "?").join(", ");
     for (const column of ["source_id", "target_id"] as const) {
       const rows = db.prepare(
@@ -265,12 +263,9 @@ export function getLinkCounts(
   const wantOutbound = direction === "outbound" || direction === "both";
   const wantInbound = direction === "inbound" || direction === "both";
 
-  // SQLite's default SQLITE_MAX_VARIABLE_NUMBER is 999 on older builds and
-  // 32766 on newer ones; chunk well under the conservative floor so the
-  // IN-list never trips the bind limit on a large page.
-  const CHUNK = 900;
-  for (let i = 0; i < ids.length; i += CHUNK) {
-    const chunk = ids.slice(i, i + CHUNK);
+  // Chunk under the Cloudflare Durable Object SQLite 100-bound-param cap
+  // (bun:sqlite tolerates 999+, DO SQLite rejects >100). See sql-in.ts.
+  for (const chunk of chunkForInClause(ids)) {
     const placeholders = chunk.map(() => "?").join(", ");
 
     if (wantOutbound) {

package/core/src/notes.ts

@@ -21,6 +21,7 @@ import {
 } from "./cursor.js";
 import { getIndexedField, releaseField } from "./indexed-fields.js";
 import { stripTagHash } from "./tag-hierarchy.js";
+import { chunkForInClause, IN_VIA_JSON_EACH, jsonEachParam } from "./sql-in.js";
 
 let idCounter = 0;
 
@@ -178,10 +179,26 @@ export function getNoteByPath(db: Database, path: string, extension?: string): N
 
 export function getNotes(db: Database, ids: string[]): Note[] {
   if (ids.length === 0) return [];
-  const placeholders = ids.map(() => "?").join(", ");
-  const rows = db.prepare(
-    `SELECT * FROM notes WHERE id IN (${placeholders}) ORDER BY created_at`,
-  ).all(...ids) as NoteRow[];
+  // Dedupe before chunking: a duplicate id straddling two chunk boundaries
+  // would otherwise be fetched (and returned) twice, unlike the old single
+  // IN-list which returned each matching row once regardless of duplicate
+  // params. Matches getNoteTagsForNotes / getNoteSummaries.
+  const uniqueIds = [...new Set(ids)];
+  // Chunk under the DO 100-bound-param cap (see sql-in.ts). Each chunk is its
+  // own IN-list query; results are merged and re-sorted by created_at (with id
+  // as a deterministic tiebreak) to preserve the single-statement ORDER BY.
+  const rows: NoteRow[] = [];
+  for (const chunk of chunkForInClause(uniqueIds)) {
+    const placeholders = chunk.map(() => "?").join(", ");
+    rows.push(...db.prepare(
+      `SELECT * FROM notes WHERE id IN (${placeholders})`,
+    ).all(...chunk) as NoteRow[]);
+  }
+  rows.sort((a, b) =>
+    a.created_at < b.created_at ? -1
+    : a.created_at > b.created_at ? 1
+    : a.id < b.id ? -1 : a.id > b.id ? 1 : 0,
+  );
   return notesWithTags(db, rows);
 }
 
@@ -756,9 +773,13 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
       // with an always-false condition; building `IN ()` would be a SQL error.
       conditions.push("0 = 1");
     } else {
-      const placeholders = opts.ids.map(() => "?").join(", ");
-      conditions.push(`n.id IN (${placeholders})`);
-      params.push(...opts.ids);
+      // Bind the id-set as ONE json_each param, not one `?` per id: this IN is
+      // embedded in a paginated statement (shared ORDER BY / LIMIT / OFFSET),
+      // so it can't be chunked, and `near` neighborhoods routinely exceed the
+      // DO 100-bound-param cap. json_each keeps the whole set at a single
+      // bound param. See sql-in.ts.
+      conditions.push(`n.id IN ${IN_VIA_JSON_EACH}`);
+      params.push(jsonEachParam(opts.ids));
     }
   }
 
@@ -1044,10 +1065,6 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   return fetchNotesByIdsOrdered(db, idRows.map((r) => r.id));
 }
 
-/** Chunk size for IN-list queries — comfortably under SQLite's conservative
- *  999 bound-variable floor (older builds), matching getLinkCounts. */
-const IN_CHUNK = 900;
-
 /**
  * Fetch full note rows for `ids`, preserving the input order, with tags
  * hydrated via ONE batched query per chunk (not one per note). Ids not
@@ -1056,8 +1073,9 @@ const IN_CHUNK = 900;
 function fetchNotesByIdsOrdered(db: Database, ids: string[]): Note[] {
   if (ids.length === 0) return [];
   const rowsById = new Map<string, NoteRow>();
-  for (let i = 0; i < ids.length; i += IN_CHUNK) {
-    const chunk = ids.slice(i, i + IN_CHUNK);
+  // Chunk under the DO 100-bound-param cap (see sql-in.ts) — a single export
+  // page (EXPORT_BATCH_SIZE=500) or a large query result exceeds it otherwise.
+  for (const chunk of chunkForInClause(ids)) {
     const placeholders = chunk.map(() => "?").join(", ");
     const rows = db.prepare(
       `SELECT * FROM notes WHERE id IN (${placeholders})`,
@@ -1084,8 +1102,8 @@ export function getNoteTagsForNotes(db: Database, noteIds: string[]): Map<string
   if (noteIds.length === 0) return map;
   const ids = [...new Set(noteIds)];
   for (const id of ids) map.set(id, []);
-  for (let i = 0; i < ids.length; i += IN_CHUNK) {
-    const chunk = ids.slice(i, i + IN_CHUNK);
+  // Chunk under the DO 100-bound-param cap (see sql-in.ts).
+  for (const chunk of chunkForInClause(ids)) {
     const placeholders = chunk.map(() => "?").join(", ");
     const rows = db.prepare(
       `SELECT note_id, tag_name FROM note_tags WHERE note_id IN (${placeholders}) ORDER BY tag_name`,

package/core/src/onboarding.ts

@@ -1,300 +1,18 @@
 /**
- * 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.
+ * DEPRECATED back-compat shim — the onboarding content moved to
+ * `seed-packs.ts` (named seed packs: `welcome` / `getting-started` /
+ * `surface-starter`, one canonical content module for both the bun and cloud
+ * runtimes).
  *
- * 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.
+ * Kept so existing importers (including out-of-repo consumers of core, e.g.
+ * parachute-cloud's `file:` dep) keep resolving. New code imports from
+ * `seed-packs.ts` directly — prefer the `SeedPack` objects + `applySeedPack`
+ * over these raw constants.
  */
-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/)
-`;
+export {
+  GETTING_STARTED_PATH,
+  GETTING_STARTED_CONTENT,
+  SURFACE_STARTER_PATH,
+  SURFACE_STARTER_CONTENT,
+} from "./seed-packs.ts";