@openparachute/vault 0.6.5-rc.2 → 0.6.5

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";

package/core/src/schema.ts

@@ -41,7 +41,7 @@ CREATE TABLE IF NOT EXISTS notes (
 
 -- Tags: first-class identity carrying schema, hierarchy, and typed-link
 -- declarations. One row per tag; no notes-as-config sidecars for these
--- concerns. See parachute-patterns/patterns/tag-data-model.md.
+-- concerns. See docs/contracts/tag-data-model.md.
 --
 -- description    — human-readable blurb (markdown).
 -- fields         — JSON: indexed metadata field declarations per
@@ -136,7 +136,7 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 -- scoped_tags is a JSON-encoded array of root tag names that constrain the
 -- token's effective access (intersection with the scopes column). NULL
 -- means unscoped — full vault access per scopes. Introduced in v13 per
--- patterns/tag-scoped-tokens.md. Hierarchy expansion is applied at auth
+-- docs/contracts/tag-scoped-tokens.md. Hierarchy expansion is applied at auth
 -- time via getTagDescendants; the column stores root names only.
 --
 -- vault_name (v16) binds the token to a single vault. NULL means the
@@ -443,7 +443,7 @@ export function initSchema(db: Database): void {
   // Migrate v13 → v14: tag-data-model reshape. Augment `tags` row with
   // description/fields/relationships/parent_names/timestamps; copy data
   // from the v6-era tag_schemas sidecar and from `_tags/<name>` config
-  // notes; drop tag_schemas after copy. See patterns/tag-data-model.md.
+  // notes; drop tag_schemas after copy. See docs/contracts/tag-data-model.md.
   migrateToV14(db);
 
   // Migrate v14 → v15: retire the `_schemas/<name>` and `_schema_defaults`
@@ -650,7 +650,7 @@ function migrateToV12(db: Database): void {
  * (current full-vault behavior); a JSON array of root tag names narrows the
  * token's access to notes carrying one of those tags or a sub-tag thereof
  * (hierarchy expansion via getTagDescendants at auth time). See
- * parachute-patterns/patterns/tag-scoped-tokens.md.
+ * docs/contracts/tag-scoped-tokens.md.
  */
 function migrateToV13(db: Database): void {
   if (hasTable(db, "tokens") && !hasColumn(db, "tokens", "scoped_tags")) {
@@ -659,7 +659,7 @@ function migrateToV13(db: Database): void {
 }
 
 /**
- * Migrate v13 → v14: tag-data-model reshape (patterns/tag-data-model.md).
+ * Migrate v13 → v14: tag-data-model reshape (docs/contracts/tag-data-model.md).
  *
  * Augments the `tags` table with five new columns and one timestamp pair,
  * then copies pre-existing data from two notes-as-config sidecars: