@openparachute/vault 0.6.5-rc.15 → 0.6.5-rc.16

package/core/src/seed-packs.test.ts

@@ -23,6 +23,9 @@ import {
   applySeedPack,
   CAPTURE_ANYTHING_PATH,
   CONNECT_AI_PATH,
+  DEFAULT_VAULT_DESCRIPTION,
+  IMPORTED_VAULT_DESCRIPTION,
+  YOURS_TO_KEEP_PATH,
   GETTING_STARTED_CONTENT,
   GETTING_STARTED_PACK,
   GETTING_STARTED_PATH,
@@ -282,11 +285,38 @@ describe("getting-started pack", () => {
     // exist. It names the pack + the way to add it.
     expect(GETTING_STARTED_CONTENT).not.toContain("[[Surface Starter]]");
     expect(GETTING_STARTED_CONTENT).toContain("Surface Starter");
-    expect(GETTING_STARTED_CONTENT).toContain("add-pack surface-starter");
+    // Points at the add-pack flow (console affordance / CLI) without spelling
+    // out a terminal command — de-emphasise the CLI (Aaron 2026-07-06).
+    expect(GETTING_STARTED_CONTENT).toContain("add-pack");
     // The surface packages are still named for discoverability.
     expect(GETTING_STARTED_CONTENT).toContain("@openparachute/surface-client");
     expect(GETTING_STARTED_CONTENT).toContain("@openparachute/surface-render");
   });
+
+  test("Getting Started is onboarding-first + carries no dead CLI guidance (2026-07-06 rewrite)", () => {
+    // Two-part structure: onboarding conversation leads, mechanics reference follows.
+    expect(GETTING_STARTED_CONTENT).toContain("## Part 1 — Onboarding the person");
+    expect(GETTING_STARTED_CONTENT).toContain("## Part 2 — Vault mechanics");
+    // Points the person at the five human guides by name (all resolve to seeds).
+    for (const g of [WELCOME_PATH, CAPTURE_ANYTHING_PATH, TAGS_GRAPH_PATH, CONNECT_AI_PATH, YOURS_TO_KEEP_PATH]) {
+      expect(GETTING_STARTED_CONTENT).toContain("[[" + g + "]]");
+    }
+    // The old live bug: it told cloud AIs to run a CLI that doesn't exist there.
+    expect(GETTING_STARTED_CONTENT).not.toContain("parachute-vault import");
+    // Data-in leads with the import UI + MCP bridge, not the terminal.
+    expect(GETTING_STARTED_CONTENT).toContain("Import button");
+    expect(GETTING_STARTED_CONTENT).toContain("over MCP");
+  });
+
+  test("default vault-description constants orient + tell the AI to self-replace them", () => {
+    for (const d of [DEFAULT_VAULT_DESCRIPTION, IMPORTED_VAULT_DESCRIPTION]) {
+      expect(d.length).toBeGreaterThan(100);
+      expect(d).toContain("Getting Started");
+      expect(d).toContain("vault-info { description:"); // the self-replace instruction
+    }
+    expect(DEFAULT_VAULT_DESCRIPTION).toContain("brand-new");
+    expect(IMPORTED_VAULT_DESCRIPTION).toContain("imported");
+  });
 });
 
 describe("surface-starter pack", () => {

package/core/src/seed-packs.ts

@@ -34,6 +34,32 @@
 
 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
 // ---------------------------------------------------------------------------
@@ -306,24 +332,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
 
@@ -417,33 +517,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
 

package/package.json

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

package/src/onboarding-seed.test.ts

@@ -82,7 +82,10 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
     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");
+    // Data-in leads with the import UI + MCP bridge; the old `parachute-vault
+    // import` CLI line (a live bug on cloud) is gone (2026-07-06 rewrite).
+    expect(gs!.content).not.toContain("parachute-vault import");
+    expect(gs!.content).toContain("Bringing existing notes in");
     expect(gs!.content).toContain("Adapt this note");
 
     // The welcome ring: five person-voiced guide notes.
@@ -200,7 +203,7 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
     // Getting Started mentions the surface-starter PACK — not a wikilink to a
     // note that the default seed no longer creates.
     expect(gs!.content).not.toContain("[[Surface Starter]]");
-    expect(gs!.content).toContain("add-pack surface-starter");
+    expect(gs!.content).toContain("add-pack");
   });
 
   test("idempotent: a second seed run skips all notes (does not duplicate)", async () => {

package/src/vault-create.test.ts

@@ -414,7 +414,7 @@ describe("vault create — default pack seeding (welcome + getting-started)", ()
     // Surface Starter is out of the default seed — no note, no dangling link.
     expect(notes.find((n) => n.path === "Surface Starter")).toBeUndefined();
     expect(gs!.content).not.toContain("[[Surface Starter]]");
-    expect(gs!.content).toContain("add-pack surface-starter");
+    expect(gs!.content).toContain("add-pack");
 
     // The capture tag Notes requires arrives with the welcome pack, alongside
     // the guide (skill-file) + pinned tags — and nothing else (fresh-vault