@openparachute/vault 0.6.4 → 0.6.5-rc.10

package/src/onboarding-seed.test.ts

@@ -1,10 +1,16 @@
 /**
- * Unit tests for the onboarding-guide seeding (demo-prep Workstream A — A1/A2/A3).
+ * Unit tests for the default-pack seeding (originally demo-prep Workstream A —
+ * A1/A2/A3; reshaped for named seed packs).
  *
  * Store-direct (no CLI subprocess) so they're fast. Covers:
- *   - A1: seedOnboardingNotes writes Getting Started + Surface Starter.
- *   - A3: Surface Starter is linked from Getting Started (wikilink).
+ *   - default seed = `welcome` (3-note web + the capture tag) + `getting-started`
+ *     — and NOT `surface-starter` (out of the default seed, ratified 2026-07-02).
+ *   - A1: the Getting Started doctrine markers.
+ *   - A3 (reshaped): the welcome web's wikilinks resolve; Getting Started
+ *     points at the surface-starter PACK without a dangling wikilink.
  *   - idempotency: a re-run never clobbers an edited note.
+ *   - applySeedPack(surface-starter): the add-pack path works + is idempotent,
+ *     and the guide carries the surface doctrine (GAP 1/2 markers).
  *   - A2: the projection / vault-info pointer steers the AI at Getting Started.
  */
 
@@ -16,14 +22,28 @@ import { tmpdir } from "os";
 import { BunStore } from "./vault-store.ts";
 import { seedOnboardingNotes } from "./onboarding-seed.ts";
 import {
+  applySeedPack,
+  CONNECT_AI_PATH,
   GETTING_STARTED_PATH,
+  NOTES_REQUIRED_TAGS,
+  SURFACE_STARTER_PACK,
   SURFACE_STARTER_PATH,
-} from "../core/src/onboarding.ts";
+  TRY_LINKING_PATH,
+  WELCOME_PATH,
+} from "../core/src/seed-packs.ts";
 import {
   buildVaultProjection,
   projectionToMarkdown,
 } from "../core/src/vault-projection.ts";
 
+/** Every note path the default seed writes on a blank vault. */
+const DEFAULT_SEED_PATHS = [
+  WELCOME_PATH,
+  TRY_LINKING_PATH,
+  CONNECT_AI_PATH,
+  GETTING_STARTED_PATH,
+];
+
 let db: Database;
 let store: BunStore;
 let tmpDir: string;
@@ -40,14 +60,15 @@ afterEach(() => {
   rmSync(tmpDir, { recursive: true, force: true });
 });
 
-describe("seedOnboardingNotes (A1/A3)", () => {
-  test("seeds Getting Started + Surface Starter on a blank vault", async () => {
+describe("seedOnboardingNotes — default packs (welcome + getting-started)", () => {
+  test("seeds the welcome web + Getting Started on a blank vault — and NOT Surface Starter", async () => {
     const result = await seedOnboardingNotes(store);
-    expect(result.seeded.sort()).toEqual(
-      [GETTING_STARTED_PATH, SURFACE_STARTER_PATH].sort(),
-    );
+    expect(result.seeded.sort()).toEqual([...DEFAULT_SEED_PATHS].sort());
     expect(result.skipped).toEqual([]);
 
+    // Surface Starter is OUT of the default seed (button/CLI only).
+    expect(await store.getNoteByPath(SURFACE_STARTER_PATH)).toBeNull();
+
     const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
     expect(gs).not.toBeNull();
     expect(gs!.content).toContain("# Getting Started");
@@ -59,26 +80,28 @@ describe("seedOnboardingNotes (A1/A3)", () => {
     expect(gs!.content).toContain("parachute-vault import");
     expect(gs!.content).toContain("Adapt this note");
 
-    const ss = await store.getNoteByPath(SURFACE_STARTER_PATH);
-    expect(ss).not.toBeNull();
-    expect(ss!.content).toContain("# Surface Starter");
-    // A3: the two surface packages by name.
-    expect(ss!.content).toContain("@openparachute/surface-client");
-    expect(ss!.content).toContain("@openparachute/surface-render");
-    expect(ss!.content).toContain("createVaultSurface");
-    expect(ss!.content).toContain("NoteRenderer");
+    // The welcome web: three person-voiced notes.
+    for (const path of [WELCOME_PATH, TRY_LINKING_PATH, CONNECT_AI_PATH]) {
+      expect(await store.getNoteByPath(path)).not.toBeNull();
+    }
+  });
 
-    // GAP 2: warn that a surface can't be run/developed from this MCP session.
-    expect(ss!.content).toContain("not from this");
-    expect(ss!.content.toLowerCase()).toContain("browser");
+  test("seeds the ONE capture tag Notes requires (byte-equal semantics)", async () => {
+    const result = await seedOnboardingNotes(store);
+    expect(result.tags).toEqual(["capture"]);
 
-    // GAP 1: a real, copy-paste end-to-end snippet — every load-bearing symbol
-    // present, verified against the surface-client / surface-render source.
-    expect(ss!.content).toContain("clientName"); // the one required createVaultSurface option
-    expect(ss!.content).toContain("getClient");
-    expect(ss!.content).toContain("queryNotes");
-    expect(ss!.content).toContain("handleCallback");
-    expect(ss!.content).toContain("resolve="); // NoteRenderer wikilink resolver prop
+    for (const decl of NOTES_REQUIRED_TAGS) {
+      const record = await store.getTagRecord(decl.name);
+      expect(record).not.toBeNull();
+      expect(record!.description).toBe(decl.description);
+      expect(record!.parent_names ?? []).toEqual(decl.parent_names ?? []);
+    }
+
+    // The retired subtype tags are NOT seeded — entry method is note
+    // metadata.source (text|voice), not taxonomy (2026-07-03). Existing
+    // vaults carrying these tags stay valid; new vaults don't get them.
+    expect(await store.getTagRecord("capture/text")).toBeNull();
+    expect(await store.getTagRecord("capture/voice")).toBeNull();
   });
 
   test("GAP 4: Getting Started shows a concrete update-tag fields example + write gotchas", async () => {
@@ -98,29 +121,39 @@ describe("seedOnboardingNotes (A1/A3)", () => {
     expect(gs!.content).toContain("first listed value");
   });
 
-  test("A3: Getting Started links to Surface Starter via a resolved wikilink", async () => {
+  test("A3 (reshaped): the welcome web's wikilinks resolve; Getting Started has no dangling Surface Starter link", async () => {
     await seedOnboardingNotes(store);
-    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
-    expect(gs!.content).toContain("[[Surface Starter]]");
 
-    // Wikilink auto-resolution: Getting Started → Surface Starter link row.
-    const ss = await store.getNoteByPath(SURFACE_STARTER_PATH);
-    const outbound = await store.getLinks(gs!.id, { direction: "outbound" });
-    expect(outbound.some((l) => l.targetId === ss!.id)).toBe(true);
+    // welcome → try-linking, try-linking → welcome, connect-AI → welcome.
+    const welcome = await store.getNoteByPath(WELCOME_PATH);
+    const tryLinking = await store.getNoteByPath(TRY_LINKING_PATH);
+    const connectAi = await store.getNoteByPath(CONNECT_AI_PATH);
+
+    const welcomeOut = await store.getLinks(welcome!.id, { direction: "outbound" });
+    expect(welcomeOut.some((l) => l.targetId === tryLinking!.id)).toBe(true);
+    const tryOut = await store.getLinks(tryLinking!.id, { direction: "outbound" });
+    expect(tryOut.some((l) => l.targetId === welcome!.id)).toBe(true);
+    const connectOut = await store.getLinks(connectAi!.id, { direction: "outbound" });
+    expect(connectOut.some((l) => l.targetId === welcome!.id)).toBe(true);
+
+    // Getting Started mentions the surface-starter PACK — not a wikilink to a
+    // note that the default seed no longer creates.
+    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
+    expect(gs!.content).not.toContain("[[Surface Starter]]");
+    expect(gs!.content).toContain("add-pack surface-starter");
   });
 
-  test("idempotent: a second seed run skips both (does not duplicate)", async () => {
+  test("idempotent: a second seed run skips all notes (does not duplicate)", async () => {
     await seedOnboardingNotes(store);
     const second = await seedOnboardingNotes(store);
     expect(second.seeded).toEqual([]);
-    expect(second.skipped.sort()).toEqual(
-      [GETTING_STARTED_PATH, SURFACE_STARTER_PATH].sort(),
-    );
+    expect(second.skipped.sort()).toEqual([...DEFAULT_SEED_PATHS].sort());
 
     // Exactly one note per path — no duplicates.
     const all = await store.queryNotes({});
-    expect(all.filter((n) => n.path === GETTING_STARTED_PATH)).toHaveLength(1);
-    expect(all.filter((n) => n.path === SURFACE_STARTER_PATH)).toHaveLength(1);
+    for (const path of DEFAULT_SEED_PATHS) {
+      expect(all.filter((n) => n.path === path)).toHaveLength(1);
+    }
   });
 
   test("idempotent: never clobbers an operator-edited Getting Started", async () => {
@@ -139,6 +172,59 @@ describe("seedOnboardingNotes (A1/A3)", () => {
   });
 });
 
+describe("applySeedPack — surface-starter via add-pack", () => {
+  test("applies the Surface Starter guide onto a default-seeded vault", async () => {
+    await seedOnboardingNotes(store);
+    const result = await applySeedPack(store, SURFACE_STARTER_PACK);
+    expect(result.pack).toBe("surface-starter");
+    expect(result.seededNotes).toEqual([SURFACE_STARTER_PATH]);
+    expect(result.skippedNotes).toEqual([]);
+    expect(result.tags).toEqual([]);
+
+    const ss = await store.getNoteByPath(SURFACE_STARTER_PATH);
+    expect(ss).not.toBeNull();
+    expect(ss!.content).toContain("# Surface Starter");
+    // A3: the two surface packages by name.
+    expect(ss!.content).toContain("@openparachute/surface-client");
+    expect(ss!.content).toContain("@openparachute/surface-render");
+    expect(ss!.content).toContain("createVaultSurface");
+    expect(ss!.content).toContain("NoteRenderer");
+
+    // GAP 2: warn that a surface can't be run/developed from this MCP session.
+    expect(ss!.content).toContain("not from this");
+    expect(ss!.content.toLowerCase()).toContain("browser");
+
+    // GAP 1: a real, copy-paste end-to-end snippet — every load-bearing symbol
+    // present, verified against the surface-client / surface-render source.
+    expect(ss!.content).toContain("clientName"); // the one required createVaultSurface option
+    expect(ss!.content).toContain("getClient");
+    expect(ss!.content).toContain("queryNotes");
+    expect(ss!.content).toContain("handleCallback");
+    expect(ss!.content).toContain("resolve="); // NoteRenderer wikilink resolver prop
+
+    // Its [[Getting Started]] wikilink resolves against the default seed.
+    const gs = await store.getNoteByPath(GETTING_STARTED_PATH);
+    const outbound = await store.getLinks(ss!.id, { direction: "outbound" });
+    expect(outbound.some((l) => l.targetId === gs!.id)).toBe(true);
+  });
+
+  test("idempotent: a re-apply skips and never clobbers an edited note", async () => {
+    await applySeedPack(store, SURFACE_STARTER_PACK);
+    const ss = await store.getNoteByPath(SURFACE_STARTER_PATH);
+    const edited = "# Surface Starter\n\nWe built ours with Solid.";
+    await store.updateNote(ss!.id, { content: edited });
+
+    const rerun = await applySeedPack(store, SURFACE_STARTER_PACK);
+    expect(rerun.seededNotes).toEqual([]);
+    expect(rerun.skippedNotes).toEqual([SURFACE_STARTER_PATH]);
+
+    const after = await store.getNoteByPath(SURFACE_STARTER_PATH);
+    expect(after!.content).toBe(edited);
+    const all = await store.queryNotes({});
+    expect(all.filter((n) => n.path === SURFACE_STARTER_PATH)).toHaveLength(1);
+  });
+});
+
 describe("vault-info / projection pointer (A2)", () => {
   test("projection carries getting_started when the note exists", async () => {
     // Absent before seeding → no pointer.

package/src/onboarding-seed.ts

@@ -1,74 +1,69 @@
 /**
- * Seed the in-vault onboarding guide on vault creation.
+ * Seed the default packs on vault creation.
  *
- * A freshly-created vault gets a `Getting Started` note (AI-legible doctrine)
- * and a linked `Surface Starter` note, so a connected AI can read the guide and
- * help the operator set the vault up — and keep growing it over time.
+ * A freshly-created vault gets the `welcome` pack (the person-voiced
+ * three-note welcome web + the `capture` tag the Notes surface expects) and
+ * the `getting-started` pack (the AI-legible start-here doctrine) — so the
+ * first minute shows a small living graph, and a connected AI can read the
+ * guide and help the operator set the vault up.
  *
- * IDEMPOTENT + create-time only: each note is written ONLY when absent. A
- * re-init, restart, or re-run never clobbers a note the operator/AI has since
- * edited. Existing vaults are unaffected — this runs on the create path, not as
- * a sweep over existing vaults.
+ * The `surface-starter` pack is deliberately NOT part of the default seed
+ * (ratified 2026-07-02): it's added on demand via
+ * `parachute-vault add-pack surface-starter` or a console affordance.
  *
- * Best-effort + non-fatal: seeding must NEVER fail a vault create. Any error is
- * caught and logged; the vault is still usable without the guide.
+ * IDEMPOTENT + create-time only: each note is written ONLY when absent (tag
+ * upserts converge on the same rows). A re-init, restart, or re-run never
+ * clobbers a note the operator/AI has since edited. Existing vaults are
+ * unaffected — this runs on the create path, not as a sweep over existing
+ * vaults.
  *
- * See the demo-prep Workstream A (A1/A2/A3).
+ * Best-effort + non-fatal: seeding must NEVER fail a vault create. Any error
+ * is caught and logged; the vault is still usable without the starter content.
+ *
+ * Pack contents live in core/src/seed-packs.ts (shared with the cloud vault).
  */
 
 import {
-  GETTING_STARTED_PATH,
-  GETTING_STARTED_CONTENT,
-  SURFACE_STARTER_PATH,
-  SURFACE_STARTER_CONTENT,
-} from "../core/src/onboarding.ts";
+  applySeedPack,
+  GETTING_STARTED_PACK,
+  welcomePack,
+} from "../core/src/seed-packs.ts";
 import type { Store } from "../core/src/types.ts";
 
 interface SeedResult {
-  /** Paths actually written this run (absent ones). Empty when both pre-existed. */
+  /** Note paths actually written this run (absent ones). Empty when all pre-existed. */
   seeded: string[];
-  /** Paths skipped because the note already existed (idempotency). */
+  /** Note paths skipped because the note already existed (idempotency). */
   skipped: string[];
+  /** Tag names upserted (idempotent by nature). */
+  tags: string[];
 }
 
 /**
- * Write a single onboarding note only if no note already lives at `path`.
- * Returns true when it wrote (was absent), false when it skipped (present).
- */
-async function seedNoteIfAbsent(
-  store: Store,
-  path: string,
-  content: string,
-): Promise<boolean> {
-  const existing = await store.getNoteByPath(path);
-  if (existing) return false;
-  await store.createNote(content, { path });
-  return true;
-}
-
-/**
- * Seed the onboarding notes into `store`, idempotently. Surface Starter is
- * created first so the `[[Surface Starter]]` wikilink in Getting Started
- * resolves immediately (the create path also auto-resolves later, but this
- * keeps the link live from the first write).
+ * Seed the default packs (`welcome` + `getting-started`) into `store`,
+ * idempotently. Welcome first so the welcome web exists before the guide
+ * lands (wikilinks auto-resolve either way; this just keeps the seed's
+ * unresolved-link window minimal).
  */
 export async function seedOnboardingNotes(store: Store): Promise<SeedResult> {
   const seeded: string[] = [];
   const skipped: string[] = [];
+  const tags: string[] = [];
 
-  for (const [path, content] of [
-    [SURFACE_STARTER_PATH, SURFACE_STARTER_CONTENT],
-    [GETTING_STARTED_PATH, GETTING_STARTED_CONTENT],
-  ] as const) {
-    const wrote = await seedNoteIfAbsent(store, path, content);
-    (wrote ? seeded : skipped).push(path);
+  // No consoleOrigin: create-time runs are often pre-expose, and a baked-in
+  // loopback origin would go stale — the generic line is the safe default.
+  for (const pack of [welcomePack(), GETTING_STARTED_PACK]) {
+    const result = await applySeedPack(store, pack);
+    seeded.push(...result.seededNotes);
+    skipped.push(...result.skippedNotes);
+    tags.push(...result.tags);
   }
 
-  return { seeded, skipped };
+  return { seeded, skipped, tags };
 }
 
 /**
- * Best-effort wrapper for the create path: seed the onboarding notes, swallow
+ * Best-effort wrapper for the create path: seed the default packs, swallow
  * and log any error so a seeding failure never fails the vault create.
  */
 export async function seedOnboardingNotesBestEffort(store: Store): Promise<void> {
@@ -76,7 +71,7 @@ export async function seedOnboardingNotesBestEffort(store: Store): Promise<void>
     await seedOnboardingNotes(store);
   } catch (err) {
     console.error(
-      `Note: onboarding guide not seeded (${(err as Error)?.message ?? err}). ` +
+      `Note: starter content not seeded (${(err as Error)?.message ?? err}). ` +
         `The vault was still created; you can connect an AI and ask it to set things up.`,
     );
   }

package/src/routes.ts

@@ -14,6 +14,7 @@
 import type { Store, Note, QueryOpts } from "../core/src/types.ts";
 import { TAG_EXPAND_MODES, stripTagHash, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
+import { transactionAsync } from "../core/src/txn.ts";
 import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, mergeMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
 import {
   parseContentRange,
@@ -28,6 +29,10 @@ import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
 import { IndexedFieldError } from "../core/src/indexed-fields.ts";
 import { buildVaultProjection, resolveTagInheritance } from "../core/src/vault-projection.ts";
+import {
+  resolveTranscriptionCapability,
+  type TranscriptionCapability,
+} from "./transcription/capability.ts";
 import { loadSchemaConfig } from "../core/src/schema-defaults.ts";
 import {
   buildExpandVisibility,
@@ -1143,17 +1148,16 @@ async function handleNotesInner(
       // don't collide with concurrent single-item callers on the shared
       // bun:sqlite connection.
       const batched = items.length > 1;
-      if (batched) db.exec("BEGIN");
-      try {
+      const runBatch = async (): Promise<void> => {
         for (const item of items) {
           // Validate extension before reaching the Store (vault#328).
-          // Thrown inside the BEGIN block — outer catch rolls the batch
-          // back, same shape as the path-conflict path.
+          // Thrown inside the batch transaction — rolls the batch back,
+          // same shape as the path-conflict path.
           const extension = item.extension !== undefined
             ? validateExtension(item.extension)
             : undefined;
           // Strict-schema gate (vault#299) — reject before any write so a
-          // mid-batch violation rolls back via the outer BEGIN/ROLLBACK.
+          // mid-batch violation rolls back the batch transaction.
           gateStrictWrite(store, writeCtx, {
             path: item.path,
             tags: item.tags,
@@ -1181,9 +1185,10 @@ async function handleNotesInner(
 
           created.push((await store.getNote(note.id)) ?? note);
         }
-        if (batched) db.exec("COMMIT");
+      };
+      try {
+        await (batched ? transactionAsync(db, runBatch) : runBatch());
       } catch (e: any) {
-        if (batched) db.exec("ROLLBACK");
         // Duck-type for module-boundary robustness (matches the PATCH branch).
         if (e && e.code === "PATH_CONFLICT") {
           return json(
@@ -2327,11 +2332,24 @@ export async function handleVault(
   store: Store,
   vaultConfig: VaultConfigLike,
   persist?: () => void,
+  /**
+   * Injection seam (scribe-fold Phase 1) for the transcription capability
+   * probe on the GET landing. Production omits it and resolves the live
+   * default (scribe-http) provider's availability; tests inject a deterministic
+   * resolver. Kept separate from the `auto_transcribe` POLICY toggle: this
+   * reports whether transcription is actually POSSIBLE (a provider is
+   * configured AND available), which is what a surface gates its mic on.
+   */
+  resolveCapability: () => Promise<TranscriptionCapability> = resolveTranscriptionCapability,
 ): Promise<Response> {
   const url = new URL(req.url);
 
   if (req.method === "GET") {
     const result: Record<string, unknown> = vaultResponse(vaultConfig);
+    // Transcription capability flag — `enabled` iff a provider is configured
+    // and available. `minutes_remaining` is omitted (cloud/plan concern;
+    // self-host is unmetered). This is the field Notes gates the mic on.
+    result.transcription = await resolveCapability();
     if (parseBool(parseQuery(url, "include_stats"), false)) {
       result.stats = await store.getVaultStats();
     }

package/src/server.ts

@@ -30,6 +30,20 @@ import { setTranscriptionWorker } from "./transcription-registry.ts";
 import { assetsDir } from "./routes.ts";
 import { resolveScribeAuthToken, ensureScribeBearer } from "./scribe-env.ts";
 import { getCachedScribeUrl } from "./scribe-discovery.ts";
+import { TranscribeCppProvider } from "./transcription/providers/transcribe-cpp.ts";
+import { ParakeetMlxProvider } from "./transcription/providers/parakeet-mlx.ts";
+import { OnnxAsrProvider } from "./transcription/providers/onnx-asr.ts";
+import {
+  resolveTranscriptionProviderName,
+  resolveTranscribeCppPaths,
+  transcribeCppInstalled,
+  resolveParakeetMlxBin,
+  resolveParakeetMlxModel,
+  resolveOnnxAsrBin,
+  resolveOnnxAsrModel,
+  parakeetMlxInstalled,
+  onnxAsrInstalled,
+} from "./transcription/select.ts";
 import { readEnvFile, setEnvVar } from "./config.ts";
 import { resolveBindHostname } from "./bind.ts";
 import { MirrorManager } from "./mirror-manager.ts";
@@ -107,40 +121,102 @@ registerConfiguredTriggers();
  * Authorization header on a 401 and transcription fails with a friendly
  * error captured on the transcript note.
  */
-const scribeUrl = getCachedScribeUrl();
 let transcriptionWorker: TranscriptionWorker | null = null;
-if (scribeUrl) {
-  // Generate + persist the shared bearer on first boot. Subsequent boots
-  // pick up the existing value and don't rotate. Loading the .env back
-  // into process.env happens above (`loadEnvFile()`); we re-load here to
-  // pick up the just-written value without restart.
-  const { created, token } = ensureScribeBearer(readEnvFile, setEnvVar);
-  if (created) {
-    process.env.SCRIBE_AUTH_TOKEN = token;
-    console.log("[transcribe] generated SCRIBE_AUTH_TOKEN (32 bytes, base64url) — mirror this value into scribe's config");
-  }
-  transcriptionWorker = startTranscriptionWorker({
-    vaultList: () => listVaults(),
-    getStore: (name) => getVaultStore(name),
-    scribeUrl,
-    scribeToken: resolveScribeAuthToken(),
-    resolveAssetsDir: (vault) => assetsDir(vault),
-    getAudioRetention: (vault) => readVaultConfig(vault)?.audio_retention ?? "keep",
-    getContextPredicates: (vault) => readVaultConfig(vault)?.transcription?.context,
-  });
-  // Event-driven hot path — the `attachment:created` hook fires the worker
-  // in a microtask instead of waiting for the 30s sweep.
+
+// Shared worker wiring: the event-driven `attachment:created` hot path + the
+// REST-retry registry. Same for whichever provider the worker was built with.
+function wireTranscriptionWorker(worker: TranscriptionWorker): void {
   registerTranscriptionHook(
     defaultHookRegistry,
-    transcriptionWorker,
+    worker,
     (store) => getVaultNameForStore(store as never),
   );
-  // Expose the worker to the REST retry endpoint so retries kick immediately
-  // instead of waiting for the sweep. Idempotent on second boot.
-  setTranscriptionWorker(transcriptionWorker);
-  console.log(`[transcribe] worker started → ${scribeUrl}`);
+  setTranscriptionWorker(worker);
+}
+
+// Fields the worker needs regardless of provider (queue/retention/context).
+const commonWorkerOpts = {
+  vaultList: () => listVaults(),
+  getStore: (name: string) => getVaultStore(name),
+  resolveAssetsDir: (vault: string) => assetsDir(vault),
+  getAudioRetention: (vault: string) => readVaultConfig(vault)?.audio_retention ?? "keep",
+  getContextPredicates: (vault: string) => readVaultConfig(vault)?.transcription?.context,
+};
+
+// Provider selection (scribe-fold Phase 2a). Default is `scribe-http` — unset
+// TRANSCRIPTION_PROVIDER means the existing scribe-http path runs unchanged.
+const providerName = resolveTranscriptionProviderName();
+if (providerName === "transcribe-cpp") {
+  // Local, no-Python provider: subprocess a transcribe-cli. Only start the
+  // worker when a runnable CLI + model are actually present — otherwise every
+  // pending item would terminal-fail with `missing_provider`. (v0.1.1 ships a
+  // library, not a CLI, so this gate stays closed until TRANSCRIBE_CPP_BIN or a
+  // build-from-source CLI exists.) `transcribeCppInstalled` is a cheap
+  // existsSync check (no spawn), matching `available()`.
+  const tcPaths = resolveTranscribeCppPaths();
+  if (transcribeCppInstalled(tcPaths)) {
+    transcriptionWorker = startTranscriptionWorker({
+      ...commonWorkerOpts,
+      provider: new TranscribeCppProvider({ binPath: tcPaths.binPath, modelPath: tcPaths.modelPath }),
+    });
+    wireTranscriptionWorker(transcriptionWorker);
+    console.log(`[transcribe] worker started → transcribe-cpp (${tcPaths.modelPath})`);
+  } else {
+    console.log(
+      "[transcribe] TRANSCRIPTION_PROVIDER=transcribe-cpp but no runnable transcribe-cli + model installed — see `parachute-vault transcription status` (v0.1.1 ships a library, not a CLI; set TRANSCRIBE_CPP_BIN or build one)",
+    );
+  }
+} else if (providerName === "parakeet-mlx" || providerName === "onnx-asr") {
+  // Python-based local providers (scribe-fold Phase 2b): subprocess the
+  // parakeet-mlx / onnx-asr CLI. Only start the worker when a runnable binary
+  // resolves (env override → managed venv → PATH) — otherwise every pending
+  // item would terminal-fail with `missing_provider`. Cheap existsSync check
+  // (no spawn), matching the providers' `available()`.
+  const installed = providerName === "parakeet-mlx" ? parakeetMlxInstalled() : onnxAsrInstalled();
+  if (installed) {
+    const provider =
+      providerName === "parakeet-mlx"
+        ? new ParakeetMlxProvider({
+            binPath: resolveParakeetMlxBin(),
+            model: resolveParakeetMlxModel(),
+          })
+        : new OnnxAsrProvider({ binPath: resolveOnnxAsrBin(), model: resolveOnnxAsrModel() });
+    transcriptionWorker = startTranscriptionWorker({ ...commonWorkerOpts, provider });
+    wireTranscriptionWorker(transcriptionWorker);
+    console.log(`[transcribe] worker started → ${providerName}`);
+  } else {
+    console.log(
+      `[transcribe] TRANSCRIPTION_PROVIDER=${providerName} but no runnable ${providerName} binary found — run \`parachute-vault transcription install\` (see \`transcription status\`)`,
+    );
+  }
 } else {
-  console.log("[transcribe] worker disabled (no scribe in services.json and SCRIBE_URL unset)");
+  // Default scribe-http path — behavior-preserving (Phase 1). Start the worker
+  // if scribe is discoverable; otherwise transcription is a no-op.
+  //
+  // Scribe URL resolution order (per `scribe-discovery.ts`): `SCRIBE_URL` env
+  // var, then `~/.parachute/services.json` `parachute-scribe` entry, then none.
+  //
+  // Bearer generation (vault#353): if neither `SCRIBE_AUTH_TOKEN` nor the
+  // legacy `SCRIBE_TOKEN` is set, generate a fresh 32-byte base64url bearer
+  // and persist it to vault's `.env` so subsequent restarts use the same
+  // value. The operator (or hub install) mirrors this bearer to scribe.
+  const scribeUrl = getCachedScribeUrl();
+  if (scribeUrl) {
+    const { created, token } = ensureScribeBearer(readEnvFile, setEnvVar);
+    if (created) {
+      process.env.SCRIBE_AUTH_TOKEN = token;
+      console.log("[transcribe] generated SCRIBE_AUTH_TOKEN (32 bytes, base64url) — mirror this value into scribe's config");
+    }
+    transcriptionWorker = startTranscriptionWorker({
+      ...commonWorkerOpts,
+      scribeUrl,
+      scribeToken: resolveScribeAuthToken(),
+    });
+    wireTranscriptionWorker(transcriptionWorker);
+    console.log(`[transcribe] worker started → ${scribeUrl}`);
+  } else {
+    console.log("[transcribe] worker disabled (no scribe in services.json and SCRIBE_URL unset)");
+  }
 }
 
 if (process.env.VAULT_AUTH_TOKEN?.trim()) {
@@ -206,9 +282,10 @@ if (listVaults().length === 0) {
       }
       writeGlobalConfig(globalConfig);
       console.log(`Auto-created vault "${vaultName}" (API key: ${fullKey})`);
-      // Seed the in-vault onboarding guide so a connected AI can self-orient and
-      // help set the vault up — same as the `create`/`init` CLI path. Idempotent
-      // + best-effort (never fails first boot). Mirrors createVault() in cli.ts.
+      // Seed the default packs (welcome web + capture tag, Getting Started
+      // guide) so a connected AI can self-orient and help set the vault up —
+      // same as the `create`/`init` CLI path. Idempotent + best-effort (never
+      // fails first boot). Mirrors createVault() in cli.ts.
       await seedOnboardingNotesBestEffort(getVaultStore(vaultName));
     } else if (firstBoot.source === "env-invalid") {
       // PARACHUTE_VAULT_NAME was set but failed validation — do NOT silently