@openparachute/vault 0.6.5-rc.2 → 0.6.5-rc.9

package/src/cli.ts

@@ -17,9 +17,9 @@
  *   parachute-vault status                  — show full status
  */
 
-import { resolve } from "path";
+import { resolve, join, dirname } from "path";
 import { homedir } from "os";
-import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, copyFileSync, chmodSync, readdirSync, statSync, renameSync } from "fs";
 // JSON import — resolved at module load, works for both dev runs
 // (`bun src/cli.ts …`) and the published package (`bunx @openparachute/vault`)
 // because package.json ships at the root next to src/.
@@ -140,6 +140,28 @@ import {
   verifyAndConsumeBackupCode,
   getTotpSecret,
 } from "./two-factor.ts";
+import {
+  planInstall,
+  detectTotalRamBytes,
+  isSharedLibFile,
+  MODELS,
+  type InstallPlan,
+  type ModelChoice,
+} from "./transcription/install.ts";
+import {
+  resolveTranscribeCppPaths,
+  resolveTranscriptionProviderName,
+  transcribeCppInstalled,
+  readManifest,
+  type TranscribeCppManifest,
+} from "./transcription/select.ts";
+import {
+  buildTranscribeCli,
+  cliSourceUrl,
+  compilerInstallHint,
+  TRANSCRIBE_CPP_SOURCE_REF,
+  type CliBuildResult,
+} from "./transcription/build.ts";
 
 // ---------------------------------------------------------------------------
 // Argument parsing
@@ -181,6 +203,9 @@ switch (command) {
   case "create":
     await cmdCreate(cmdArgs);
     break;
+  case "add-pack":
+    await cmdAddPack(cmdArgs);
+    break;
   case "list":
   case "ls":
     cmdList();
@@ -246,6 +271,9 @@ switch (command) {
   case "schema":
     await cmdSchema(cmdArgs);
     break;
+  case "transcription":
+    await cmdTranscription(cmdArgs);
+    break;
   case "help":
   case "--help":
   case "-h":
@@ -3496,6 +3524,390 @@ function printHistoryUsage(): void {
   console.error("  --json           Emit the history as JSON instead of the human-readable list");
 }
 
+// ---------------------------------------------------------------------------
+// Transcription — `parachute-vault transcription <subcommand>` (scribe-fold 2a)
+// ---------------------------------------------------------------------------
+
+/**
+ * `parachute-vault transcription install` — set up the local `transcribe-cpp`
+ * provider: detect OS/arch + RAM, pick a tier-appropriate GGUF model
+ * (scribe#82 fix — Parakeet floored to ≥4GB), download the prebuilt
+ * transcribe-cli release asset + the model into
+ * `~/.parachute/transcription/`, and switch `TRANSCRIPTION_PROVIDER` in the
+ * vault `.env`. Idempotent (skips already-present files unless `--force`),
+ * non-fatal. `--dry-run`/`--plan` prints the selection without downloading —
+ * the path tests exercise (no network).
+ *
+ * `parachute-vault transcription status` — show the configured provider +
+ * install state.
+ */
+async function cmdTranscription(args: string[]) {
+  const sub = args[0];
+  if (sub === "install") {
+    await cmdTranscriptionInstall(args.slice(1));
+    return;
+  }
+  if (sub === "status" || sub === undefined) {
+    cmdTranscriptionStatus();
+    return;
+  }
+  console.error(`Unknown transcription subcommand: ${sub}`);
+  console.error("Usage: parachute-vault transcription install [--dry-run] [--model <id>] [--provider <name>]");
+  console.error("       parachute-vault transcription status");
+  process.exit(1);
+}
+
+/** Render an install plan for the human (shared by --dry-run + the real run). */
+function printTranscriptionPlan(plan: InstallPlan): void {
+  console.log(`Host:  ${plan.platform}/${plan.arch}, ${plan.totalRamGb}GB RAM`);
+  if (!plan.supported) {
+    console.log(`\n  ${plan.refused ? "Refused" : "Unsupported"}: ${plan.reason}`);
+    return;
+  }
+  const m = plan.model!;
+  console.log(`Binary: ${plan.asset!.asset}`);
+  console.log(`Model:  ${m.name}  (${m.file})`);
+  console.log(`        ${m.note}`);
+  console.log(`        ~${m.approxSizeMb}MB download, ~${m.approxRuntimeGb}GB peak RAM while transcribing`);
+}
+
+async function cmdTranscriptionInstall(args: string[]) {
+  const dryRun = args.includes("--dry-run") || args.includes("--plan");
+  const force = args.includes("--force");
+  const yes = args.includes("--yes") || args.includes("-y");
+  const overrideModel = takeArgValue(args, "--model").value;
+  const provider = takeArgValue(args, "--provider").value ?? "transcribe-cpp";
+
+  if (provider === "scribe-http") {
+    // Just flip config back to the remote provider — no download.
+    if (dryRun) {
+      console.log("Would set TRANSCRIPTION_PROVIDER=scribe-http in the vault .env (remote provider; no download).");
+      return;
+    }
+    setEnvVar("TRANSCRIPTION_PROVIDER", "scribe-http");
+    console.log("Set TRANSCRIPTION_PROVIDER=scribe-http. Restart vault to apply. (Remote provider — no local binary/model needed.)");
+    return;
+  }
+  if (provider !== "transcribe-cpp") {
+    console.error(`Unknown --provider "${provider}". Valid: transcribe-cpp, scribe-http.`);
+    process.exit(1);
+  }
+
+  const plan = planInstall({
+    platform: process.platform,
+    arch: process.arch,
+    totalRamBytes: detectTotalRamBytes(),
+    overrideModel,
+  });
+
+  console.log("Transcription install plan (transcribe-cpp — local, no Python):\n");
+  printTranscriptionPlan(plan);
+
+  if (!plan.supported) {
+    // Refused / unsupported is not a hard error — it's a steer to remote.
+    console.log("\nNo local install performed. See the note above.");
+    process.exit(dryRun ? 0 : 1);
+  }
+
+  const paths = resolveTranscribeCppPaths();
+  console.log(`\nInstall dir: ${paths.dir}`);
+
+  if (dryRun) {
+    console.log("\n(--dry-run) No files downloaded.");
+    return;
+  }
+
+  if (!yes) {
+    const ok = await confirm(`Download ~${plan.footprintMb}MB and install to ${paths.dir}?`, true);
+    if (!ok) {
+      console.log("Aborted.");
+      return;
+    }
+  }
+
+  // ffmpeg hint (non-fatal — the transcode path checks at runtime).
+  if (!Bun.which("ffmpeg")) {
+    console.warn(
+      "\n⚠  ffmpeg not found on PATH. transcribe-cli needs 16kHz mono WAV; non-WAV capture audio is transcoded via ffmpeg.\n" +
+        "   Install it: apt install ffmpeg  (Debian/Ubuntu)  |  brew install ffmpeg  (macOS)",
+    );
+  }
+
+  try {
+    mkdirSync(paths.binDir, { recursive: true });
+    mkdirSync(paths.libsDir, { recursive: true });
+    mkdirSync(paths.modelsDir, { recursive: true });
+
+    // 1) Release library bundle → extract the runtime dylibs/sos into libs/.
+    //    transcribe.cpp v0.1.1 ships a LIBRARY, not a prebuilt transcribe-cli,
+    //    so a CLI is usually NOT placed here — `installTranscribeLibs` still
+    //    opportunistically places one if a (future) asset includes it.
+    const existingLibs = (readdirSync(paths.libsDir) as string[]).filter(isSharedLibFile);
+    let libFiles = existingLibs;
+    if (existingLibs.length && !force) {
+      console.log(`\n✓ runtime libraries already present (${paths.libsDir}) — skipping (use --force to re-download).`);
+    } else {
+      console.log(`\nDownloading ${plan.asset!.asset} …`);
+      libFiles = await installTranscribeLibs(plan, paths);
+      console.log(
+        libFiles.length
+          ? `✓ Extracted ${libFiles.length} runtime library file(s) → ${paths.libsDir}`
+          : `⚠  no shared libraries found in ${plan.asset!.asset} (the asset layout may have changed).`,
+      );
+    }
+
+    // 2) Model GGUF.
+    const modelDest = join(paths.modelsDir, plan.model!.file);
+    if (existsSync(modelDest) && !force) {
+      console.log(`✓ model already present (${modelDest}) — skipping (use --force to re-download).`);
+    } else {
+      console.log(`Downloading model ${plan.model!.file} (~${plan.model!.approxSizeMb}MB) …`);
+      await downloadTo(plan.model!.url, modelDest);
+    }
+
+    // 3) Build transcribe-cli from source against the extracted dylibs.
+    //    transcribe.cpp v0.1.1 ships a LIBRARY, not a prebuilt CLI, so we
+    //    compile examples/cli/main.cpp + examples/common/wav.cpp against
+    //    libtranscribe (a tiny ~127KB compile — no ggml rebuild). Non-fatal:
+    //    any failure keeps the current provider + prints guidance.
+    const buildResult = await maybeBuildTranscribeCli(paths, libFiles, force);
+
+    // 4) Manifest.
+    const manifest: TranscribeCppManifest = {
+      version: plan.asset!.asset,
+      asset: plan.asset!.asset,
+      binFile: "transcribe-cli",
+      model: plan.model!.name,
+      modelFile: plan.model!.file,
+      libFiles,
+      binBuiltFrom: buildResult?.ok ? TRANSCRIBE_CPP_SOURCE_REF : undefined,
+      os: plan.platform,
+      arch: plan.arch,
+      ram_gb: plan.totalRamGb,
+      installedAt: new Date().toISOString(),
+    };
+    writeFileSync(paths.manifestPath, JSON.stringify(manifest, null, 2));
+
+    // 5) CLI resolution + provider switch — honest, no silent success. `binPath`
+    //    resolves to TRANSCRIBE_CPP_BIN or the built binary; we activate
+    //    transcribe-cpp only when one actually exists, else we keep the current
+    //    provider and report the acquisition gap rather than taking
+    //    transcription offline behind a provider that can't run.
+    if (existsSync(paths.binPath)) {
+      setEnvVar("TRANSCRIPTION_PROVIDER", "transcribe-cpp");
+      console.log(`\n✓ Installed and activated → TRANSCRIPTION_PROVIDER=transcribe-cpp set in the vault .env.`);
+      console.log(`  CLI:   ${paths.binPath}`);
+      console.log(`  Restart vault to activate:  parachute restart vault`);
+    } else {
+      console.log(`\n✓ Libraries + model installed to ${paths.dir} — transcription is NOT yet activated.`);
+      console.log(noRunnableCliGuidance(paths, buildResult));
+    }
+  } catch (err) {
+    console.error(`\nInstall failed: ${err instanceof Error ? err.message : String(err)}`);
+    console.error("The verb is idempotent — fix the issue and re-run. Or use the remote provider: parachute-vault transcription install --provider scribe-http");
+    process.exit(1);
+  }
+}
+
+/** Download a URL to a destination file (streamed via fetch → Bun.write). */
+async function downloadTo(url: string, dest: string): Promise<void> {
+  const resp = await fetch(url, { redirect: "follow" });
+  if (!resp.ok) throw new Error(`download failed (${resp.status}) for ${url}`);
+  await Bun.write(dest, resp);
+}
+
+/**
+ * Download the release tarball, extract it, and place its runtime shared
+ * libraries (libtranscribe + libggml `.dylib`/`.so`) into `paths.libsDir`,
+ * returning the extracted lib filenames. transcribe.cpp v0.1.1 ships a LIBRARY,
+ * not a prebuilt `transcribe-cli` — so we also look for a CLI binary (a future
+ * asset may include one) and, if present, place it at `paths.binPath` + chmod +x
+ * (the caller decides activation from whether a CLI exists). Uses system `tar`
+ * (present on Linux + macOS). Kept out of the plan/dry-run path so tests never
+ * hit the network.
+ */
+async function installTranscribeLibs(
+  plan: InstallPlan,
+  paths: ReturnType<typeof resolveTranscribeCppPaths>,
+): Promise<string[]> {
+  const tmpRoot = join(paths.dir, ".dl");
+  mkdirSync(tmpRoot, { recursive: true });
+  const tarball = join(tmpRoot, plan.asset!.asset);
+  await downloadTo(plan.asset!.url, tarball);
+
+  const extractDir = join(tmpRoot, "x");
+  rmSync(extractDir, { recursive: true, force: true });
+  mkdirSync(extractDir, { recursive: true });
+  const tarProc = Bun.spawnSync(["tar", "-xzf", tarball, "-C", extractDir]);
+  if (tarProc.exitCode !== 0) {
+    throw new Error(`tar extract failed: ${new TextDecoder().decode(tarProc.stderr)}`);
+  }
+
+  // Walk the extracted tree: keep the shared libs, opportunistically place a CLI.
+  mkdirSync(paths.libsDir, { recursive: true });
+  const libFiles: string[] = [];
+  for (const rel of readdirSync(extractDir, { recursive: true }) as string[]) {
+    const abs = join(extractDir, rel);
+    if (!statSync(abs).isFile()) continue;
+    const base = rel.split("/").pop()!;
+    if (isSharedLibFile(base)) {
+      copyFileSync(abs, join(paths.libsDir, base));
+      libFiles.push(base);
+    } else if (base === "transcribe-cli") {
+      copyFileSync(abs, paths.binPath);
+      chmodSync(paths.binPath, 0o755);
+    }
+  }
+  rmSync(tmpRoot, { recursive: true, force: true });
+  return libFiles;
+}
+
+/**
+ * Build `transcribe-cli` from source against the extracted dylibs, honoring
+ * idempotency + the `TRANSCRIBE_CPP_BIN` operator override. Returns the build
+ * result, or `null` when the build was intentionally skipped (already built /
+ * operator-provided binary / no libs to link). Non-fatal — logs progress and
+ * warnings; failures come back as a typed `{ ok:false }` the caller reports.
+ */
+async function maybeBuildTranscribeCli(
+  paths: ReturnType<typeof resolveTranscribeCppPaths>,
+  libFiles: string[],
+  force: boolean,
+): Promise<CliBuildResult | null> {
+  if (process.env.TRANSCRIBE_CPP_BIN?.trim()) {
+    console.log(
+      existsSync(paths.binPath)
+        ? `\n✓ Using operator-provided TRANSCRIBE_CPP_BIN=${paths.binPath} — skipping source build.`
+        : `\n⚠  TRANSCRIBE_CPP_BIN=${paths.binPath} is set but no file exists there — skipping source build; nothing will be activated until it points at a real binary.`,
+    );
+    return null;
+  }
+  if (existsSync(paths.binPath) && !force) {
+    console.log(`\n✓ transcribe-cli already built (${paths.binPath}) — skipping build (use --force to rebuild).`);
+    return null;
+  }
+  if (libFiles.length === 0) {
+    console.warn(`\n⚠  no runtime libraries were extracted — cannot build transcribe-cli. Skipping build.`);
+    return null;
+  }
+
+  console.log(`\nBuilding transcribe-cli from source (transcribe.cpp @ ${TRANSCRIBE_CPP_SOURCE_REF.slice(0, 12)}) …`);
+  mkdirSync(paths.binDir, { recursive: true });
+  const srcDir = join(paths.dir, ".src");
+  const result = await buildTranscribeCli(
+    { srcDir, libsDir: paths.libsDir, binPath: paths.binPath },
+    {
+      platform: process.platform,
+      which: (c) => Bun.which(c),
+      fetchSource: async (files, dir) => {
+        rmSync(dir, { recursive: true, force: true });
+        for (const rel of files) {
+          const dest = join(dir, rel);
+          mkdirSync(dirname(dest), { recursive: true });
+          await downloadTo(cliSourceUrl(rel), dest);
+        }
+      },
+      compile: (cmd) => {
+        const p = Bun.spawnSync(cmd);
+        return { exitCode: p.exitCode ?? 1, stderr: new TextDecoder().decode(p.stderr) };
+      },
+      exists: existsSync,
+      removeBin: (p) => rmSync(p, { force: true }),
+      rename: (from, to) => renameSync(from, to),
+    },
+  );
+
+  if (result.ok) {
+    chmodSync(paths.binPath, 0o755); // belt-and-suspenders; the compiler emits 0755
+    rmSync(srcDir, { recursive: true, force: true }); // tidy — source is re-fetchable
+    console.log(`✓ Built transcribe-cli → ${result.binPath}`);
+  } else {
+    // Keep srcDir on failure so the printed compile command can be re-run by hand.
+    console.warn(`⚠  transcribe-cli build failed (${result.stage}): ${result.message}`);
+    if (result.command) console.warn(`   compile command tried:\n     ${result.command}`);
+  }
+  return result;
+}
+
+/**
+ * The "no runnable CLI" guidance printed when activation can't proceed —
+ * tailored to WHY (build failed at toolchain vs compile, or was skipped).
+ */
+function noRunnableCliGuidance(
+  paths: ReturnType<typeof resolveTranscribeCppPaths>,
+  build: CliBuildResult | null,
+): string {
+  const lines: string[] = [];
+  if (build && !build.ok && build.stage === "toolchain") {
+    lines.push(
+      `\n⚠  Could not build transcribe-cli — ${build.message}`,
+      "   To finish, either:",
+      `     • install a C++ compiler and re-run this verb (${compilerInstallHint(process.platform)}); OR`,
+      "     • build transcribe-cli yourself, point TRANSCRIBE_CPP_BIN at it, and re-run; OR",
+      "     • use the remote provider:  parachute-vault transcription install --provider scribe-http",
+    );
+  } else if (build && !build.ok && build.stage === "fetch") {
+    lines.push(
+      `\n⚠  Could not fetch the transcribe-cli source — ${build.message}`,
+      "   The libraries + model are installed; only the source download failed (check network/proxy).",
+      "   To finish, either:",
+      "     • re-run this verb once connectivity is restored; OR",
+      "     • build transcribe-cli yourself, point TRANSCRIBE_CPP_BIN at it, and re-run; OR",
+      "     • use the remote provider:  parachute-vault transcription install --provider scribe-http",
+    );
+  } else if (build && !build.ok) {
+    lines.push(
+      `\n⚠  transcribe-cli build failed (${build.stage}). The libraries + model are installed;`,
+      "   the CLI is not. To finish, either:",
+      "     • fix the toolchain and re-run this verb; OR",
+      "     • build transcribe-cli yourself (the compile command tried is printed above),",
+      "       point TRANSCRIBE_CPP_BIN at the result, and re-run; OR",
+      "     • use the remote provider:  parachute-vault transcription install --provider scribe-http",
+    );
+  } else {
+    // Build skipped (no libs, or an operator-provided binary that isn't present).
+    lines.push(
+      "\n⚠  No runnable transcribe-cli is available yet. To finish, either:",
+      `     • re-run this verb so it builds a transcribe-cli against ${paths.libsDir} (needs a C++ compiler); OR`,
+      "     • point TRANSCRIBE_CPP_BIN at a transcribe-cli you built, and re-run; OR",
+      "     • use the remote provider:  parachute-vault transcription install --provider scribe-http",
+    );
+  }
+  lines.push("   Your current provider is unchanged — check with `parachute-vault transcription status`.");
+  return lines.join("\n");
+}
+
+/** `parachute-vault transcription status` — provider + install state. */
+function cmdTranscriptionStatus(): void {
+  const active = resolveTranscriptionProviderName();
+  console.log(`Configured provider: ${active}`);
+  const paths = resolveTranscribeCppPaths();
+  const manifest = readManifest(paths.manifestPath);
+  const cliPresent = existsSync(paths.binPath);
+  const installed = transcribeCppInstalled(paths); // runnable CLI + model both present
+  console.log(`transcribe-cpp runnable: ${installed ? "yes" : "no"}`);
+  if (manifest) {
+    console.log(`  model:   ${manifest.model} (${manifest.modelFile})`);
+    console.log(
+      `  libs:    ${paths.libsDir}${manifest.libFiles?.length ? ` (${manifest.libFiles.length} file(s))` : ""}`,
+    );
+    console.log(
+      cliPresent
+        ? `  cli:     ${paths.binPath}${manifest.binBuiltFrom ? ` (built from source @ ${manifest.binBuiltFrom.slice(0, 12)})` : ""}`
+        : `  cli:     NOT FOUND — re-run \`transcription install\` to build one (needs a C++ compiler), or set TRANSCRIBE_CPP_BIN`,
+    );
+    console.log(`  ram:     ${manifest.ram_gb}GB at install (${manifest.os}/${manifest.arch})`);
+  } else {
+    console.log(`  (nothing installed — run: parachute-vault transcription install)`);
+  }
+  if (active === "transcribe-cpp" && !installed) {
+    console.log(
+      "\n⚠  provider is transcribe-cpp but no runnable transcribe-cli is installed — transcription is offline until a CLI is available (TRANSCRIBE_CPP_BIN, or a build from source).",
+    );
+  }
+  console.log(`\nAvailable models (override with --model): ${Object.values(MODELS).map((m: ModelChoice) => m.name).join(", ")}`);
+}
+
 // ---------------------------------------------------------------------------
 // Schema maintenance — `parachute-vault schema <subcommand>`
 // ---------------------------------------------------------------------------
@@ -3962,11 +4374,14 @@ async function createVault(
   // row is written — vault is a pure hub resource-server post-0.5.0.
   const seedStore = getVaultStore(name);
 
-  // Seed the in-vault onboarding guide (Getting Started + Surface Starter) so a
-  // connected AI can read it and help the operator set the vault up. Idempotent
-  // + best-effort: only writes notes that are absent, and never fails the
-  // create. Runs BEFORE the mirror bootstrap so the seeded notes land in the
-  // initial mirror commit. See src/onboarding-seed.ts + core/src/onboarding.ts.
+  // Seed the default packs (welcome web + capture tag, Getting Started guide)
+  // 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. Surface Starter is NOT
+  // default-seeded — `parachute-vault add-pack surface-starter` adds it later.
+  // Idempotent + best-effort: only writes notes that are absent, and never
+  // fails the create. Runs BEFORE the mirror bootstrap so the seeded content
+  // lands in the initial mirror commit. See src/onboarding-seed.ts +
+  // core/src/seed-packs.ts.
   await seedOnboardingNotesBestEffort(seedStore);
 
   // Default new vaults to an internal live mirror (local git backup of the
@@ -4088,6 +4503,99 @@ function installMcpConfig(opts: InstallMcpConfigOpts): void {
   writeFileSync(targetPath, JSON.stringify(config, null, 2) + "\n");
 }
 
+/**
+ * `parachute-vault add-pack <pack> [--vault <name>]` — apply a named seed
+ * pack (starter notes + tags) to a vault.
+ *
+ * New vaults default-seed the `welcome` + `getting-started` packs at create;
+ * this verb adds the opt-in ones (today: `surface-starter`) — or re-applies a
+ * default pack to an older vault that predates it. Idempotent per item: a
+ * note is created only when no note lives at its path (a re-run never
+ * clobbers an edited note); tag upserts converge on the same rows.
+ *
+ * Unlike `import` (bulk stream writes, vault#323 daemon-busy guard), this is
+ * a handful of tiny writes against a WAL database, so it runs fine next to a
+ * live daemon; a write-lock collision (SQLITE_BUSY) is caught with a
+ * retry-is-safe message instead of pre-emptively demanding a daemon stop.
+ */
+async function cmdAddPack(args: string[]) {
+  let vaultName = "default";
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--vault") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--vault requires a value.");
+        process.exit(1);
+      }
+      vaultName = v;
+    } else {
+      positional.push(arg);
+    }
+  }
+  const packName = positional[0];
+
+  const { listSeedPacks, getSeedPack, applySeedPack } = await import(
+    "../core/src/seed-packs.ts"
+  );
+
+  const printPacks = () => {
+    console.error("\nAvailable packs:");
+    for (const p of listSeedPacks()) {
+      console.error(`  ${p.name.padEnd(17)} ${p.description}`);
+    }
+  };
+
+  if (!packName) {
+    console.error("Usage: parachute-vault add-pack <pack> [--vault <name>]");
+    printPacks();
+    process.exit(1);
+  }
+
+  const pack = getSeedPack(packName);
+  if (!pack) {
+    console.error(`Unknown pack: "${packName}"`);
+    printPacks();
+    process.exit(1);
+  }
+
+  const config = readVaultConfig(vaultName);
+  if (!config) {
+    console.error(`Vault "${vaultName}" not found. Run: parachute-vault create ${vaultName}`);
+    process.exit(1);
+  }
+
+  const store = getVaultStore(vaultName);
+  try {
+    const result = await applySeedPack(store, pack);
+    console.log(`Pack "${pack.name}" applied to vault "${vaultName}":`);
+    for (const path of result.seededNotes) {
+      console.log(`  + note  ${path}`);
+    }
+    for (const path of result.skippedNotes) {
+      console.log(`  = note  ${path} (already exists — left untouched)`);
+    }
+    for (const tag of result.tags) {
+      console.log(`  ~ tag   ${tag} (upserted)`);
+    }
+    if (result.seededNotes.length === 0 && result.tags.length === 0) {
+      console.log("  Nothing to add — everything was already in place.");
+    }
+  } catch (err) {
+    const message = (err as Error)?.message ?? String(err);
+    if (message.includes("SQLITE_BUSY") || (err as { code?: string })?.code === "SQLITE_BUSY") {
+      console.error(
+        `error: the vault database is busy (a running daemon holds the write lock). ` +
+          `add-pack is idempotent — re-run it, or stop the daemon first with: parachute stop vault`,
+      );
+    } else {
+      console.error(`error: failed to apply pack "${pack.name}": ${message}`);
+    }
+    process.exit(1);
+  }
+}
+
 function usage() {
   console.log(`
 Parachute Vault — self-hosted knowledge graph
@@ -4153,6 +4661,14 @@ Vaults:
                                            opt-in upgrade). --no-mirror creates a bare vault with no mirror config.
                                            Operators can flip the server-wide default with 'default_mirror: off' in
                                            config.yaml (recommended for cloud / disk-constrained boxes).
+  parachute-vault add-pack <pack> [--vault <name>]
+                                           Add a named seed pack (starter notes + tags) to a vault
+                                           (default vault: "default"). Run with no arguments to list
+                                           the available packs. New vaults seed the "welcome" +
+                                           "getting-started" packs automatically; "surface-starter"
+                                           is opt-in via this command. Idempotent: notes are only
+                                           created when absent — a re-run never clobbers an edited
+                                           note.
   parachute-vault list                     List all vaults
   parachute-vault remove <name> [--yes]    Remove a vault
   parachute-vault mcp-install [--mint|--token <t>]
@@ -4298,6 +4814,25 @@ Schema maintenance:
                                                        Writes through strict enforcement (migrate
                                                        bypass). See \`schema migrate-field --help\`.
 
+Transcription (scribe-fold):
+  parachute-vault transcription install [--dry-run] [--model <id>] [--force] [--yes]
+                                           Install the local transcribe-cpp provider — detects
+                                           OS/arch + RAM, downloads the transcribe.cpp runtime
+                                           libraries + a RAM-tier-appropriate GGUF model into
+                                           ~/.parachute/transcription/. NOTE: v0.1.1 ships a library,
+                                           not a CLI — it activates (sets
+                                           TRANSCRIPTION_PROVIDER=transcribe-cpp) only when a runnable
+                                           transcribe-cli is available (TRANSCRIBE_CPP_BIN or a build
+                                           from source), else it reports the gap. --dry-run prints the
+                                           pick + footprint without downloading. --model overrides the
+                                           RAM-tier choice (whisper-tiny.en | whisper-small.en |
+                                           parakeet-tdt-0.6b-v3). --force re-downloads; --yes skips the
+                                           confirm. Needs ffmpeg on PATH to transcode audio to 16kHz
+                                           mono WAV (hinted if missing).
+  parachute-vault transcription install --provider scribe-http
+                                           Switch back to the remote scribe-http provider (no download).
+  parachute-vault transcription status     Show the configured provider + local install state.
+
 ── Advanced / standalone ──────────────────────────────────────────────
 
 Direct daemon controls. For normal use, prefer the Parachute Hub wrappers