@openparachute/vault 0.6.5-rc.9 → 0.6.5

package/core/src/seed-packs.ts

@@ -5,8 +5,9 @@
  * A pack is a named bundle of `tags` (upserted) + `notes` (created only when
  * no note already lives at the path). Three packs ship today:
  *
- *   - `welcome` — the person-voiced three-note welcome web + the `capture`
- *     tag the Notes surface expects. Default-seeded on vault creation.
+ *   - `welcome` — the five-guide welcome ring (Welcome, Capture anything, Tags
+ *     and the graph, Connect your AI, Yours to keep) + the `capture` / `guide`
+ *     tags the Notes surface expects. Default-seeded on creation.
  *   - `getting-started` — the AI-facing start-here guide (SKILL.md-style
  *     doctrine addressed to a connected assistant). Default-seeded.
  *   - `surface-starter` — the living starter guide for building a custom
@@ -14,6 +15,12 @@
  *     Surface Starter is out of the default seed) — added on demand via
  *     `parachute-vault add-pack surface-starter` or a console affordance.
  *
+ * Guides are the vault's skill files — the Parachute equivalent of a
+ * `SKILL.md`. They're tagged `#guide` (GUIDE_TAG): notes that teach how this
+ * vault works and how to work it, for you and your AI alike. Some (the welcome
+ * ring) are voiced to the person; some (Getting Started) to the assistant; all
+ * are plain markdown either reads — so no per-guide audience field is needed.
+ *
  * This module is the single source of truth for pack content across BOTH
  * runtimes: the bun vault (`src/onboarding-seed.ts` default seed + the
  * `add-pack` CLI verb) and the cloud vault DO (parachute-cloud
@@ -26,23 +33,63 @@
  * Getting Started / Surface Starter path + content constants.
  */
 
-import type { Store } from "./types.ts";
+import type { Store, TagFieldSchema } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Default vault descriptions — the single source of truth
+// ---------------------------------------------------------------------------
+
+/**
+ * The `vault-info` description a **brand-new** vault ships with. It's the first
+ * thing a connected AI reads about the vault, so it doubles as a nudge: orient
+ * the person, read the Getting Started brief, do one small real thing, and — once
+ * real structure lands — REPLACE this text with a current picture of the vault.
+ *
+ * Exported as the single source of truth; the runtimes (bun vault default seed +
+ * cloud vault DO) consume it in a follow-up PR. Not wired into `applySeedPack`
+ * here — a description is vault metadata, not a pack note.
+ */
+export const DEFAULT_VAULT_DESCRIPTION =
+  'This is a brand-new personal vault — just its starter guides so far; the person it belongs to is probably new to Parachute. Before helping them set it up, read the "Getting Started" note — it\'s your onboarding brief. Short version: start with a conversation, not a filing system; learn how they want to use this and where their notes live today; do one small real thing first. When the vault has real structure, replace this description (vault-info { description: "..." }) with a current picture of what lives here and how to work it — so every future session, yours or another AI\'s, starts oriented.';
+
+/**
+ * The `vault-info` description a vault gets when it was **imported/restored** —
+ * it arrived with content. Flips the AI's first job from seed-it to learn-it:
+ * orient over the existing shape, reflect it back, and only then replace this
+ * text with a current picture.
+ */
+export const IMPORTED_VAULT_DESCRIPTION =
+  'This vault was imported — it arrived with its own notes, tags, and history. Orient before you write: vault-info { include_stats: true }, list-tags, read a sample, and read "Getting Started" if present. Your first job is to learn the shape that\'s already here and reflect it back to the person — not to propose new structure cold. When you understand it, replace this description (vault-info { description: "..." }) with a current picture.';
 
 // ---------------------------------------------------------------------------
 // Pack shape
 // ---------------------------------------------------------------------------
 
-/** A tag declaration a pack upserts (identity row, not a schema migration). */
+/**
+ * A tag declaration a pack upserts (identity row, not a schema migration).
+ *
+ * `fields` carries an optional typed-metadata schema — the same
+ * `Record<field, { type, enum?, indexed? }>` shape `update-tag` accepts — so a
+ * pack can declare a schema-carrying tag. The applier passes it straight
+ * through to `upsertTagRecord`.
+ */
 export interface SeedPackTag {
   name: string;
   description: string;
   parent_names?: string[];
+  fields?: Record<string, TagFieldSchema>;
 }
 
-/** A note a pack seeds — created only when no note exists at `path`. */
+/**
+ * A note a pack seeds — created only when no note exists at `path`. `tags` +
+ * `metadata` are applied at create time (both runtimes' `createNote` accepts
+ * them); a guide note carries `tags: ["guide"]`.
+ */
 export interface SeedPackNote {
   path: string;
   content: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
 }
 
 /** A named bundle of starter tags + notes. */
@@ -83,58 +130,173 @@ export const NOTES_REQUIRED_TAGS: ReadonlyArray<SeedPackTag> = [
   },
 ];
 
+/**
+ * The `guide` tag — the vault's skill-file tag. Guides are the Parachute
+ * equivalent of a `SKILL.md`: notes that teach how this vault works and how to
+ * work it, for you and your AI alike. Plain markdown, so either reads them.
+ *
+ * Declared by every pack that ships guide notes (welcome / getting-started /
+ * surface-starter). The upserts converge on one row, so each pack stays
+ * self-sufficient — applying any one of them alone still lands the tag.
+ */
+export const GUIDE_TAG: SeedPackTag = {
+  name: "guide",
+  description:
+    "Guides — the vault's skill files. Notes that teach how this vault works and how to work it, for you and your AI alike. Plain markdown, so either reads them.",
+};
+
 export const WELCOME_PATH = "Welcome to your vault 🪂";
-export const TRY_LINKING_PATH = "Try linking notes";
+export const CAPTURE_ANYTHING_PATH = "Capture anything";
+export const TAGS_GRAPH_PATH = "Tags and the graph";
 export const CONNECT_AI_PATH = "Connect your AI";
+export const YOURS_TO_KEEP_PATH = "Yours to keep";
 
 /**
- * Build the `welcome` pack: a three-note welcome web (welcome → try-linking →
- * back, connect-AI → welcome) so the graph view shows a connected structure
- * from minute one, plus the `capture` tag above. The notes are ordinary
- * notes — no special flags, deletable like anything else.
+ * Build the `welcome` pack: the five-guide welcome ring — Welcome, Capture
+ * anything, Tags and the graph, Connect your AI, Yours to keep — plus the
+ * `capture` / `guide` tags. The guides are ordinary notes tagged `#guide`
+ * (the vault's skill-file tag). They form a
+ * small linked web (Welcome → all four; the rest chain 2→3→4→5→1; Connect
+ * your AI also links the AI-facing [[Getting Started]]) so the graph view
+ * shows a connected structure from minute one. Deletable like anything else.
  *
- * Content is ported EXACTLY from parachute-cloud workers/vault/src/welcome.ts
- * (person-voiced, addressed to the everyday user). `consoleOrigin` is the
- * origin of the operator's console (the cloud console, or a hub portal) —
- * when known, the Connect-your-AI note names it; when omitted (the bun vault
- * seeds at create time, often pre-expose, and must never bake in a loopback
- * origin) the line stays generic.
+ * These five bodies are the ratified guides (already live at
+ * parachute.computer/guides). `consoleOrigin` is the origin of the operator's
+ * console (the cloud console, or a hub portal) — when known, the Connect-your-AI
+ * note names it; when omitted (the bun vault seeds at create time, often
+ * pre-expose, and must never bake in a loopback origin) the line stays generic.
  */
 export function welcomePack(opts: { consoleOrigin?: string } = {}): SeedPack {
   const consoleLine = opts.consoleOrigin
     ? `Grab the connection URL from your console at ${opts.consoleOrigin}.`
     : `Grab the connection URL from your console.`;
+  const guideNote = { tags: ["guide"] };
   return {
     name: "welcome",
     description:
-      "A small linked welcome web (three notes) + the capture tag the Notes surface uses. Seeded by default on new vaults.",
-    tags: NOTES_REQUIRED_TAGS,
+      "The five-guide welcome ring (Welcome, Capture anything, Tags and the graph, Connect your AI, Yours to keep) — the vault's #guide skill files — plus the capture/guide tags. Seeded by default on new vaults.",
+    // capture (Notes surface) + guide (the skill-file tag). Upserts are idempotent.
+    tags: [...NOTES_REQUIRED_TAGS, GUIDE_TAG],
     // `[[wikilinks]]` resolve by note path — pending links auto-resolve when
     // the target is created, so order only affects how briefly a link sits
-    // unresolved during the seed.
+    // unresolved during the seed. Every [[target]] here resolves to a note the
+    // default seed writes (the four siblings + [[Getting Started]] from the
+    // getting-started pack) — no dangling links on a fresh vault.
     notes: [
       {
         path: WELCOME_PATH,
+        tags: ["guide"],
         content: `# ${WELCOME_PATH}
 
 This vault is yours.
-Write anything.
-Notes can link to each other, like this: [[${TRY_LINKING_PATH}]].
+
+Write anything — ideas, people, plans, wifi passwords. Notes can link to each
+other, like this: [[${CAPTURE_ANYTHING_PATH}]]. Follow that link and keep going — these
+guides form a small web you can wander:
+
+- [[${CAPTURE_ANYTHING_PATH}]] — get thoughts in and link them together
+- [[${TAGS_GRAPH_PATH}]] — structure that grows out of what you write
+- [[${CONNECT_AI_PATH}]] — any AI can read and write your vault
+- [[${YOURS_TO_KEEP_PATH}]] — export everything, anytime
+
+They're ordinary notes, tagged #guide. Edit them, add to them, or delete the
+lot — the vault is yours, remember.
 `,
       },
       {
-        path: TRY_LINKING_PATH,
-        content: `# ${TRY_LINKING_PATH}
+        path: CAPTURE_ANYTHING_PATH,
+        ...guideNote,
+        content: `# ${CAPTURE_ANYTHING_PATH}
+
+The one habit that makes a vault work: when a thought strikes, write it down.
+Don't sort it. Don't file it. Let it land.
+
+A note can be two words or two pages. The blog idea on a trail, the follow-up
+from a meeting, the dream at 2am — capture first. Organizing can happen later,
+or never; that's what tags and your AI are for.
+
+To connect two notes, wrap a note's name in double square brackets:
+[[${WELCOME_PATH}]] is a link back to where you started. If the note
+doesn't exist yet, the link waits patiently and connects the moment it does.
 
-Wrap a note's name in double square brackets to make a wikilink, like this one back to [[${WELCOME_PATH}]].
+That's the whole trick. Storage is easy — connection is everything. A linked
+note is a thought your future self, and your AI, can find again.
+
+Next: [[${TAGS_GRAPH_PATH}]].
+`,
+      },
+      {
+        path: TAGS_GRAPH_PATH,
+        ...guideNote,
+        content: `# ${TAGS_GRAPH_PATH}
+
+Notes and links come first. Tags come later, when you notice a pattern.
+
+A tag answers "what kind of thing is this?" — #person, #recipe, #idea. Tag a
+few notes the same way and a view lights up: all your people, all your recipes,
+everything half-finished. Your vault starts with just two:
+
+- #capture — the Notes app puts it on whatever you write or speak in directly,
+  marking your own raw words.
+- #guide — these notes.
+
+Underneath, everything is one graph: every note a node, every link an edge.
+Open the graph view and watch it grow; ask a connected AI "what's near this
+note?" and it walks the edges for you.
+
+The structure isn't a filing system you design on day one. It grows out of what
+you actually write — so don't over-organize an empty vault. Write, link, and
+let the shape appear.
+
+Next: [[${CONNECT_AI_PATH}]].
 `,
       },
       {
         path: CONNECT_AI_PATH,
+        ...guideNote,
         content: `# ${CONNECT_AI_PATH}
 
-Your vault speaks MCP. ${consoleLine}
-Start from [[${WELCOME_PATH}]].
+Your vault speaks MCP — an open standard — so any AI can read and write it:
+Claude, ChatGPT, Claude Code, Cursor, or an agent you build. ${consoleLine}
+
+Once you're connected, try:
+
+- "Read the Getting Started note and help me set this vault up."
+- "What did I want to write about?"
+- "Tag my untagged notes."
+
+Your AI sees what you see — the same notes, links, and tags — and what it
+writes lands here, as notes you can read, edit, or delete. There's even a note
+in this vault written for it: [[${GETTING_STARTED_PATH}]], the vault-design brief your
+AI reads so you don't have to.
+
+One memory, shared with every AI you choose to connect. That's the point.
+
+Next: [[${YOURS_TO_KEEP_PATH}]].
+`,
+      },
+      {
+        path: YOURS_TO_KEEP_PATH,
+        ...guideNote,
+        content: `# ${YOURS_TO_KEEP_PATH}
+
+Everything here — every note, tag, and link — exports as plain markdown files
+with the structure intact. On Parachute Cloud, it's the Export button in your
+console. Self-hosting, it's one command: \`parachute-vault export <dir>\`.
+
+What you get is a folder any app can open, and another Parachute can import
+losslessly. Move from our cloud to your own machine, or the other way — same
+software, same format, nothing held hostage between the doors.
+
+We build it this way on purpose. A connection you can't leave isn't a
+relationship. You can always leave — which is exactly why you can trust
+staying.
+
+Export isn't a feature we grudgingly support; it's the moral center of the
+design. We test it constantly, because a promise you don't test is just a
+hope.
+
+Back to [[${WELCOME_PATH}]].
 `,
       },
     ],
@@ -156,24 +318,98 @@ 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.
- * Mentions the Surface Starter PACK by name (no wikilink — the note isn't
- * seeded by default, and a dangling `[[Surface Starter]]` would sit unresolved
- * on every fresh vault).
+ * Voice: addressed to the connected AI ("you"), warm and practical, SKILL.md-style.
+ * ONE note, two labeled parts:
+ *   - Part 1 — Onboarding the person: lead with a real conversation, leverage
+ *     prior context, offer to survey their content, do one small real thing
+ *     first, the data-in menu (import UI / MCP bridge / paste-and-file — NOT the
+ *     CLI, NOT Obsidian-first), the arrived-with-content branch, and closing the
+ *     loop by updating the vault description (see DEFAULT_VAULT_DESCRIPTION).
+ *   - Part 2 — Vault mechanics: the preserved reference — what a vault is + the
+ *     tool list, tags-vs-paths-vs-schemas, write gotchas, the custom-surface
+ *     pointer, and "Adapt this note."
+ *
+ * Deliberately points AIs at the import UI + MCP bridge, never at a
+ * `parachute-vault import` CLI (that verb doesn't exist on cloud — the old copy
+ * shipped that live bug to every hosted user). Mentions the Surface Starter PACK
+ * by name (no wikilink — the note isn't seeded by default, and a dangling
+ * `[[Surface Starter]]` would sit unresolved on every fresh vault).
  */
 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.
+This is the **start-here guide** for this Parachute vault — instructions for a
+connected AI (you), like a \`SKILL.md\`. Read it when the vault is new, when
+you're orienting yourself, or when the person says *"help me set up my
+parachute."* You don't need to re-read it every session. It has two parts:
+**how to onboard the person** (start there if they're new) and **vault
+mechanics** (reference for operating the vault). It's a starting point, not a
+script — and it's editable (see "Adapt this note" at the end).
+
+---
+
+## Part 1 — Onboarding the person
+
+### Start with a conversation, not a filing system
+
+If this vault is fresh, this is probably the person's first real session with
+it. Don't start building — orient them, briefly, in your own words: this vault
+is **their** memory, one place every AI they choose to connect can read and
+write, and they can export all of it anytime as plain markdown. Then have a
+real conversation:
+
+- **How do they imagine using this?** A journal, a project brain, a people
+  directory, meeting notes, a commonplace book — or they don't know yet
+  (that's fine; capture-first works).
+- **Where do their notes and data live now?** Another app, a pile of markdown,
+  another Parachute — or nowhere yet.
+- **What's alive for them right now?** A project, a decision, a trip, a draft.
+  The first note should be about something real.
+
+**Use what you already know.** If you have memory or context about this person
+from working with them, bring it — propose the two or three kinds of
+information *they specifically* would want here ("you mention a lot of book
+ideas — want a place for those?"). Propose, confirm, then write; never
+bulk-create structure they didn't agree to. You can also **offer to survey**
+what they already have — "want me to look through what you've brought in and
+suggest a few ways to organize it?" — then read a sample and propose, don't
+impose.
+
+### Do one small real thing first
+
+The failure mode of every notes tool is over-organizing an empty vault. So:
+**one small real thing this session.** Capture a thought they actually have,
+file one document, or bring in one small batch — then stop and show them what
+happened. Structure grows from real notes (that's Part 2's design vocabulary).
+Setup is a relationship over many sessions, not an install step.
+
+Five short guides ship in this vault for the person to read (tagged \`#guide\`):
+[[Welcome to your vault 🪂]], [[Capture anything]], [[Tags and the graph]],
+[[Connect your AI]], and [[Yours to keep]]. Point them there for anything you'd
+otherwise lecture about — they're the return-point between sessions. If a
+session ends mid-setup, leave a breadcrumb (update this note or the vault
+description) so the next one picks up where you left off.
+
+### If this vault already has content
+
+Some vaults arrive full — an import, a restore, months of use. Then your first
+job is to **learn it, not seed it**: \`vault-info { include_stats: true }\`,
+\`list-tags\`, read a sample (\`query-notes { search: "..." }\`), then reflect the
+shape back to the person and ask what's missing or wrong. Propose structure
+only once you can describe what's already there.
+
+### Close the loop: describe the vault
+
+When the first real structure lands, update the vault description —
+\`vault-info { description: "..." }\` — so every future session (yours or another
+AI's) starts oriented: what this vault is for, its main tags, its conventions.
+The default description says "brand-new vault"; once that stops being true,
+replace it. Keep it a few sentences (the projection carries the schema detail,
+and this note carries the richer conventions — see "Adapt this note"). Bringing
+their existing data in is covered under "Bringing existing notes in" below.
+
+---
+
+## Part 2 — Vault mechanics
 
 ## What a Parachute vault is
 
@@ -267,33 +503,40 @@ A few behaviors worth knowing before you write at scale:
 
 (Full design guide, with copy-paste examples: https://parachute.computer/scripting/)
 
-## Importing existing notes
+## Bringing existing notes in
+
+If the person already keeps notes somewhere, help them bring what matters —
+start with what's alive for them, not the whole archive. What works today:
 
-If the operator already keeps notes (Obsidian, Markdown, etc.), bring them in
-rather than starting cold:
+- **Connect the source over MCP (the flexible path).** If their AI client can
+  add other MCP servers — a Google Drive server, a Notion server, a filesystem
+  server — connect it alongside this vault in the same session. Then read from
+  there and \`create-note\` here: a selective, conversational migration, no
+  export file needed.
+- **Paste and file.** They paste anything — a doc, a list, an export — and you
+  \`create-note\` it (batch mode for many at once).
+- **Import a Parachute export.** Moving between Parachute vaults (cloud ⇄
+  self-host) is lossless — on Parachute Cloud, the console's Import button —
+  ids, tags, links, schemas, and attachments round-trip.
 
-- **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.
+Bringing a whole Obsidian or Markdown library in is getting easier, and a
+flexible import is on the way; for now the connect-over-MCP and paste paths
+handle it without anyone touching a terminal. Whatever they bring, offer to
+survey it and suggest a first structure — read a sample, propose a small tag
+vocabulary, confirm, then apply. Don't impose structure silently.
 
-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.
+After bringing content in, orient: \`vault-info\` for the schema picture,
+\`list-tags\` for the vocabulary that arrived, \`query-notes { search: "..." }\`
+to spot-check.
 
 ## 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, add the **Surface Starter** guide to this vault — it's a
-seed pack that isn't installed by default. Run
-\`parachute-vault add-pack surface-starter\` (or use the console's add-pack
-affordance) to seed it; it covers building a surface with
-\`@openparachute/surface-client\` + \`@openparachute/surface-render\`.
+the starting point — get the notes and structure right first. When the person
+wants one, add the **Surface Starter** guide to this vault — an optional pack
+(not installed by default) that covers building a surface with
+\`@openparachute/surface-client\` + \`@openparachute/surface-render\`. On Parachute
+Cloud it's the console's add-pack affordance.
 
 ## Adapt this note
 
@@ -313,8 +556,16 @@ export const GETTING_STARTED_PACK: SeedPack = {
   name: "getting-started",
   description:
     "The AI-facing start-here guide: vault design vocabulary (tags/paths/schemas), imports, write gotchas. Seeded by default on new vaults.",
-  tags: [],
-  notes: [{ path: GETTING_STARTED_PATH, content: GETTING_STARTED_CONTENT }],
+  // Declares GUIDE_TAG too — each pack is self-sufficient; the upsert converges
+  // with the welcome pack's. This guide is written FOR the AI.
+  tags: [GUIDE_TAG],
+  notes: [
+    {
+      path: GETTING_STARTED_PATH,
+      tags: ["guide"],
+      content: GETTING_STARTED_CONTENT,
+    },
+  ],
 };
 
 // ---------------------------------------------------------------------------
@@ -450,8 +701,16 @@ export const SURFACE_STARTER_PACK: SeedPack = {
   name: "surface-starter",
   description:
     "A living starter guide for building a custom surface (UI) over this vault with the published surface packages. Opt-in — not seeded by default.",
-  tags: [],
-  notes: [{ path: SURFACE_STARTER_PATH, content: SURFACE_STARTER_CONTENT }],
+  // A guide too (written for the AI) — declares GUIDE_TAG so the opt-in
+  // add-pack path lands the tag even if this pack is applied on its own.
+  tags: [GUIDE_TAG],
+  notes: [
+    {
+      path: SURFACE_STARTER_PATH,
+      tags: ["guide"],
+      content: SURFACE_STARTER_CONTENT,
+    },
+  ],
 };
 
 // ---------------------------------------------------------------------------
@@ -541,18 +800,23 @@ export async function applySeedPack(
     await store.upsertTagRecord(decl.name, {
       description: decl.description,
       ...(decl.parent_names ? { parent_names: decl.parent_names } : {}),
+      ...(decl.fields ? { fields: decl.fields } : {}),
     });
     result.tags.push(decl.name);
   }
 
-  for (const { path, content } of pack.notes) {
-    const existing = await store.getNoteByPath(path);
+  for (const note of pack.notes) {
+    const existing = await store.getNoteByPath(note.path);
     if (existing) {
-      result.skippedNotes.push(path);
+      result.skippedNotes.push(note.path);
       continue;
     }
-    await store.createNote(content, { path });
-    result.seededNotes.push(path);
+    await store.createNote(note.content, {
+      path: note.path,
+      tags: note.tags,
+      metadata: note.metadata,
+    });
+    result.seededNotes.push(note.path);
   }
 
   return result;

package/core/src/tag-hierarchy.ts

@@ -9,7 +9,7 @@
  * History: pre-v14 vaults stored hierarchy in notes-as-config at
  * `_tags/<name>`. The v14 migration (see core/src/schema.ts:migrateToV14)
  * lifts those parent declarations onto the tags row and the resolver here
- * was swapped accordingly. See parachute-patterns/patterns/tag-data-model.md.
+ * was swapped accordingly. See docs/contracts/tag-data-model.md.
  *
  * Resolution model:
  * - Lazy: built on first access, cached on the store.

package/core/src/tag-schemas.ts

@@ -4,7 +4,7 @@
  * Each tag row carries: human-readable description, indexed metadata field
  * declarations (`fields`), typed-link relationship declarations
  * (`relationships`), and the hierarchy parent list (`parent_names`).
- * See parachute-patterns/patterns/tag-data-model.md.
+ * See docs/contracts/tag-data-model.md.
  *
  * This module retains the historical `tag-schemas` filename and exports
  * (`TagSchema`, `listTagSchemas`, `getTagSchema`, `upsertTagSchema`,
@@ -51,7 +51,7 @@ export interface TagFieldSchema {
  * `{ target_tag, cardinality }` declaration — but `relationships` is now an
  * opaque vocabulary map (see `TagRelationshipMap` / `validateRelationships`),
  * so this is one valid value shape among many, not a required one.
- * See patterns/tag-data-model.md §Relationships.
+ * See docs/contracts/tag-data-model.md §Relationships.
  */
 export type TagRelCardinality = "one" | "optional" | "many" | "many-required";
 

package/core/src/types.ts

@@ -406,7 +406,7 @@ export interface Store {
 
   // Tag records — full v14 identity row (description + fields + typed
   // relationships + parent_names + timestamps). See
-  // parachute-patterns/patterns/tag-data-model.md.
+  // docs/contracts/tag-data-model.md.
   listTagRecords(): Promise<TagRecord[]>;
   getTagRecord(tag: string): Promise<TagRecord | null>;
   /**

package/package.json

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

package/src/admin-spa.ts

@@ -8,7 +8,8 @@
  *
  * Per-vault mount (vault#252): the SPA lives under `/vault/<name>/admin/*`
  * rather than the origin-rooted `/admin/*` it shipped with. The hub only
- * proxies `/vault/<name>/*` paths (per parachute-patterns/module-protocol),
+ * proxies `/vault/<name>/*` paths (per the module protocol —
+ * https://github.com/ParachuteComputer/parachute-hub/blob/main/docs/contracts/module-protocol.md),
  * so an origin-rooted SPA is unreachable through the hub. Asset URLs are
  * relative (Vite `base: "./"`), so the same bundle works at any mount
  * point — no rebuild per vault.

package/src/auth.ts

@@ -123,7 +123,7 @@ export interface AuthResult {
    * Tag-allowlist (root tag names) for tag-scoped tokens. NULL = unscoped
    * (current full-vault behavior). Hub-issued JWTs and legacy YAML keys
    * always have null — tag scoping is a per-token vault-DB attribute, not
-   * an OAuth-claim concern. See patterns/tag-scoped-tokens.md.
+   * an OAuth-claim concern. See docs/contracts/tag-scoped-tokens.md.
    */
   scoped_tags: string[] | null;
   /**