@openparachute/vault 0.6.5-rc.2 → 0.6.5

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,48 @@ import {
   verifyAndConsumeBackupCode,
   getTotpSecret,
 } from "./two-factor.ts";
+import {
+  planInstall,
+  detectTotalRamBytes,
+  isSharedLibFile,
+  MODELS,
+  type InstallPlan,
+  type ModelChoice,
+} from "./transcription/install.ts";
+import {
+  resolveTranscribeCppPaths,
+  resolveTranscriptionProviderName,
+  transcribeCppInstalled,
+  probeTranscribeCliRunnable,
+  readManifest,
+  transcriptionHomeDir,
+  pythonVenvDir,
+  pythonManifestPath,
+  readPythonManifest,
+  resolveParakeetMlxBin,
+  resolveParakeetMlxModel,
+  resolveOnnxAsrBin,
+  resolveOnnxAsrModel,
+  parakeetMlxInstalled,
+  onnxAsrInstalled,
+  type TranscribeCppManifest,
+  type PythonInstallManifest,
+} from "./transcription/select.ts";
+import {
+  buildTranscribeCli,
+  cliSourceUrl,
+  compilerInstallHint,
+  TRANSCRIBE_CPP_SOURCE_REF,
+  type CliBuildResult,
+} from "./transcription/build.ts";
+import { downloadTo } from "./transcription/download.ts";
+import { selectDefaultProvider, NOMINAL_SLACK_GB, type TierPlan } from "./transcription/tiers.ts";
+import {
+  PYTHON_PROVIDERS,
+  buildDefaultPythonDeps,
+  installPythonBackend,
+  type PythonProviderName,
+} from "./transcription/install-python.ts";
 
 // ---------------------------------------------------------------------------
 // Argument parsing
@@ -181,6 +223,9 @@ switch (command) {
   case "create":
     await cmdCreate(cmdArgs);
     break;
+  case "add-pack":
+    await cmdAddPack(cmdArgs);
+    break;
   case "list":
   case "ls":
     cmdList();
@@ -246,6 +291,9 @@ switch (command) {
   case "schema":
     await cmdSchema(cmdArgs);
     break;
+  case "transcription":
+    await cmdTranscription(cmdArgs);
+    break;
   case "help":
   case "--help":
   case "-h":
@@ -3496,6 +3544,629 @@ 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 a LOCAL transcription
+ * provider. With no `--provider`, the ratified RAM/arch/OS tier table
+ * (scribe-fold Phase 2b, `tiers.ts`) picks the host's default:
+ *
+ *   - macOS Apple Silicon 8GB+ → parakeet-mlx (Python venv, MLX)
+ *   - Linux 4GB+               → onnx-asr (Python venv, int8 ONNX)
+ *   - Linux ~2GB               → transcribe-cpp + small whisper GGUF
+ *   - ~1GB / below floor       → remote steer (scribe-http), never forced
+ *
+ * The pick + footprint is printed and the operator confirms (or overrides
+ * with `--provider`/`--model`). Every path is idempotent + non-fatal, and
+ * activation is HONEST: `TRANSCRIPTION_PROVIDER` flips only when a runnable
+ * binary actually exists (PRs #532/#533 precedent). `--dry-run`/`--plan`
+ * prints the selection without downloading.
+ *
+ * `parachute-vault transcription status` — show the configured provider +
+ * per-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) {
+    await cmdTranscriptionStatus();
+    return;
+  }
+  console.error(`Unknown transcription subcommand: ${sub}`);
+  console.error(
+    "Usage: parachute-vault transcription install [--dry-run] [--model <id>] [--provider <transcribe-cpp|parakeet-mlx|onnx-asr|scribe-http>]",
+  );
+  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 providerArg = takeArgValue(args, "--provider").value;
+
+  if (providerArg === "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;
+  }
+
+  let provider: string;
+  let tierModel: string | undefined;
+  if (providerArg) {
+    if (!["transcribe-cpp", "parakeet-mlx", "onnx-asr"].includes(providerArg)) {
+      console.error(
+        `Unknown --provider "${providerArg}". Valid: transcribe-cpp, parakeet-mlx, onnx-asr, scribe-http.`,
+      );
+      process.exit(1);
+    }
+    provider = providerArg;
+  } else {
+    // Auto-default: the ratified RAM/arch/OS tier table (tiers.ts). Probe the
+    // host, print the pick + footprint; the operator confirms below (or
+    // re-runs with --provider/--model to override).
+    const tier = selectDefaultProvider({
+      platform: process.platform,
+      arch: process.arch,
+      totalRamBytes: detectTotalRamBytes(),
+    });
+    printTierPick(tier);
+    if (tier.provider === "scribe-http") {
+      // Remote steer — never force a local install on a below-tier box.
+      console.log("\nNo local install performed. To point at a remote provider now:");
+      console.log("  parachute-vault transcription install --provider scribe-http");
+      if (tier.localOptIn) {
+        console.log(`\nLocal opt-in (explicit only — not auto-installed): ${tier.localOptIn.note}`);
+      }
+      process.exit(dryRun ? 0 : 1);
+    }
+    provider = tier.provider;
+    tierModel = tier.model;
+    console.log("");
+  }
+
+  if (provider === "transcribe-cpp") {
+    // The tier's model pick (e.g. the Linux ~2GB whisper-small tier) seeds the
+    // transcribe-cpp flow; an explicit --model always wins.
+    await runTranscribeCppInstall({ dryRun, force, yes, overrideModel: overrideModel ?? tierModel });
+    return;
+  }
+  await runPythonProviderInstall(provider as PythonProviderName, {
+    dryRun,
+    force,
+    yes,
+    overrideModel,
+  });
+}
+
+/** Print the tier-table pick for this host (the install auto-default). */
+function printTierPick(tier: TierPlan): void {
+  console.log(`Host: ${tier.platform}/${tier.arch}, ${tier.totalRamGb}GB RAM`);
+  console.log(`Tier default: ${tier.provider}${tier.model ? ` (${tier.model})` : ""}`);
+  console.log(`  ${tier.reason}`);
+  if (tier.approxDiskMb) {
+    console.log(`  ~${tier.approxDiskMb}MB download${tier.peakRamNote ? `, ${tier.peakRamNote}` : ""}`);
+  }
+  console.log("  (override with --provider <transcribe-cpp|parakeet-mlx|onnx-asr|scribe-http>)");
+}
+
+/**
+ * Install a Python-based local provider (parakeet-mlx / onnx-asr) into the
+ * managed venv under `~/.parachute/transcription/venv/` and — honestly —
+ * activate it only when a runnable binary verified (`install-python.ts` owns
+ * the apt/venv/warm-pull steps; activation + manifest stay here, mirroring
+ * the transcribe-cpp flow).
+ */
+async function runPythonProviderInstall(
+  provider: PythonProviderName,
+  opts: { dryRun: boolean; force: boolean; yes: boolean; overrideModel?: string },
+): Promise<void> {
+  const spec = PYTHON_PROVIDERS[provider];
+  const venv = pythonVenvDir();
+  // `--model` wins; else env/manifest/ratified default. The pick lands in the
+  // install manifest, which the runtime model resolution reads back.
+  const model =
+    opts.overrideModel ??
+    (provider === "parakeet-mlx" ? resolveParakeetMlxModel() : resolveOnnxAsrModel());
+  const totalRamGb = Math.round((detectTotalRamBytes() / 2 ** 30) * 10) / 10;
+
+  console.log(`Transcription install plan (${provider} — local, Python venv):\n`);
+  console.log(`Host:    ${process.platform}/${process.arch}, ${totalRamGb}GB RAM`);
+  console.log(`Package: ${spec.pipTarget} → ${venv}`);
+  console.log(`Model:   ${model}`);
+  console.log(`         ~${spec.approxDiskMb}MB model download, ${spec.peakRamNote}`);
+
+  if (opts.dryRun) {
+    // Preview the guards the real run would hit — pure, no side effects.
+    if (spec.platform && spec.platform !== process.platform) {
+      console.log(`\n  Refused: ${provider} only runs on ${spec.platform}; this host is ${process.platform}.`);
+    } else if (spec.arch && spec.arch !== process.arch) {
+      console.log(`\n  Refused: ${provider} needs ${spec.arch} (Apple Silicon); this host is ${process.arch}.`);
+    } else if (totalRamGb < spec.minRamGb - NOMINAL_SLACK_GB && !opts.force) {
+      console.log(`\n  Refused: ${totalRamGb}GB RAM < the ~${spec.minRamGb}GB ${provider} floor. ${spec.ramFloorRationale}`);
+    }
+    console.log("\n(--dry-run) Nothing installed.");
+    return;
+  }
+
+  if (!opts.yes) {
+    const ok = await confirm(
+      `Install ${spec.pipTarget} into ${venv} (model ~${spec.approxDiskMb}MB ${provider === "parakeet-mlx" ? "downloads on first use" : "warm-pulled now"})?`,
+      true,
+    );
+    if (!ok) {
+      console.log("Aborted.");
+      return;
+    }
+  }
+
+  const outcome = await installPythonBackend(buildDefaultPythonDeps(), {
+    provider,
+    force: opts.force,
+    model,
+  });
+
+  if (!outcome.ok || !outcome.binPath) {
+    console.error(`\n✗ ${outcome.summary}`);
+    console.error(
+      "Your current provider is unchanged — 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);
+  }
+
+  // Manifest + honest activation (a runnable binary exists — verified above).
+  const manifest: PythonInstallManifest = {
+    provider,
+    pipTarget: spec.pipTarget,
+    bin: outcome.binPath,
+    venv: outcome.venv ?? "",
+    model,
+    os: process.platform,
+    arch: process.arch,
+    ram_gb: totalRamGb,
+    installedAt: new Date().toISOString(),
+  };
+  mkdirSync(transcriptionHomeDir(), { recursive: true });
+  writeFileSync(pythonManifestPath(), JSON.stringify(manifest, null, 2));
+
+  setEnvVar("TRANSCRIPTION_PROVIDER", provider);
+  console.log(`\n✓ Installed and activated → TRANSCRIPTION_PROVIDER=${provider} set in the vault .env.`);
+  console.log(`  Binary: ${outcome.binPath}`);
+  console.log(`  Model:  ${model}`);
+  if (provider === "parakeet-mlx") {
+    console.log(`  NOTE: the model (~${spec.approxDiskMb}MB) downloads into the HuggingFace cache on the first transcription.`);
+  }
+  console.log(`  Restart vault to activate:  parachute restart vault`);
+}
+
+async function runTranscribeCppInstall(opts: {
+  dryRun: boolean;
+  force: boolean;
+  yes: boolean;
+  overrideModel?: string;
+}) {
+  const { dryRun, force, yes, overrideModel } = opts;
+  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 EXECUTES (`--help` exits 0 —
+    //    vault#534: an existsSync-only check activated Linux installs whose CLI
+    //    exited 1 on every run). Otherwise we keep the current provider and
+    //    report the gap rather than taking transcription offline behind a
+    //    provider that can't run.
+    if (existsSync(paths.binPath)) {
+      const probe = await probeTranscribeCliRunnable(paths.binPath);
+      if (probe.ok) {
+        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} (verified runnable)`);
+        console.log(`  Restart vault to activate:  parachute restart vault`);
+      } else {
+        console.log(
+          `\n⚠  transcribe-cli exists at ${paths.binPath} but is NOT runnable (${probe.reason}).`,
+        );
+        console.log("   NOT activating transcribe-cpp — your current provider is unchanged.");
+        console.log(noRunnableCliGuidance(paths, buildResult));
+      }
+    } 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 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);
+        }
+      },
+      readFile: (p) => readFileSync(p, "utf8"),
+      writeFile: (p, content) => writeFileSync(p, content),
+      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 && build.stage === "patch") {
+    lines.push(
+      `\n⚠  Could not apply the vault#534 backend-init source patch — ${build.message}`,
+      "   The pinned upstream source no longer matches the patch anchor. This needs a code fix",
+      "   (re-anchor or drop the patch), not a toolchain fix. Until then, either:",
+      "     • build a 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 + per-provider install state. */
+async function cmdTranscriptionStatus(): Promise<void> {
+  const active = resolveTranscriptionProviderName();
+  console.log(`Configured provider: ${active}`);
+
+  // What the ratified tier table would pick for this host (install default).
+  const tier = selectDefaultProvider({
+    platform: process.platform,
+    arch: process.arch,
+    totalRamBytes: detectTotalRamBytes(),
+  });
+  console.log(
+    `Tier default for this host (${tier.platform}/${tier.arch}, ${tier.totalRamGb}GB): ${tier.provider}${tier.model ? ` (${tier.model})` : ""}`,
+  );
+
+  // transcribe-cpp — prebuilt libs + GGUF model + built CLI. "runnable" is an
+  // EXECUTED verdict, not a stat: `--help` must actually exit 0 (vault#534 —
+  // an existsSync-only check said "yes" on Linux while the CLI exited 1 on
+  // every real transcription because its dlopen'd CPU backends never loaded).
+  const paths = resolveTranscribeCppPaths();
+  const manifest = readManifest(paths.manifestPath);
+  const cliPresent = existsSync(paths.binPath);
+  const filesPresent = transcribeCppInstalled(paths); // CLI + model both on disk
+  let installed = false;
+  let notRunnableReason: string | undefined;
+  if (!filesPresent) {
+    notRunnableReason = !cliPresent ? "no transcribe-cli binary" : "no GGUF model on disk";
+  } else {
+    const probe = await probeTranscribeCliRunnable(paths.binPath);
+    installed = probe.ok;
+    notRunnableReason = probe.reason;
+  }
+  console.log(`\ntranscribe-cpp runnable: ${installed ? "yes" : `no (${notRunnableReason})`}`);
+  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(`  (not installed — run: parachute-vault transcription install --provider transcribe-cpp)`);
+  }
+
+  // parakeet-mlx / onnx-asr — Python venv providers (scribe-fold Phase 2b).
+  const pyManifest = readPythonManifest(pythonManifestPath());
+  const pkBin = resolveParakeetMlxBin();
+  const pkRunnable = parakeetMlxInstalled();
+  console.log(`\nparakeet-mlx runnable: ${pkRunnable ? "yes" : "no"}`);
+  if (pkRunnable) {
+    console.log(`  bin:     ${pkBin}`);
+    console.log(`  model:   ${resolveParakeetMlxModel()} (HF cache; downloads on first use)`);
+  } else {
+    console.log(
+      process.platform === "darwin" && process.arch === "arm64"
+        ? `  (not installed — run: parachute-vault transcription install${tier.provider === "parakeet-mlx" ? "" : " --provider parakeet-mlx"})`
+        : "  (macOS Apple Silicon only)",
+    );
+  }
+
+  const oxBin = resolveOnnxAsrBin();
+  const oxRunnable = onnxAsrInstalled();
+  console.log(`onnx-asr runnable: ${oxRunnable ? "yes" : "no"}`);
+  if (oxRunnable) {
+    console.log(`  bin:     ${oxBin}`);
+    console.log(`  model:   ${resolveOnnxAsrModel()} (HF cache)`);
+  } else {
+    console.log(
+      `  (not installed — run: parachute-vault transcription install${tier.provider === "onnx-asr" ? "" : " --provider onnx-asr"})`,
+    );
+  }
+  if (pyManifest) {
+    console.log(
+      `  python install: ${pyManifest.provider} (${pyManifest.pipTarget}) @ ${pyManifest.installedAt}${pyManifest.venv ? ` — venv ${pyManifest.venv}` : ""}`,
+    );
+  }
+
+  // Offline warning when the ACTIVE provider isn't runnable.
+  const activeRunnable =
+    active === "scribe-http" ||
+    (active === "transcribe-cpp" && installed) ||
+    (active === "parakeet-mlx" && pkRunnable) ||
+    (active === "onnx-asr" && oxRunnable);
+  if (!activeRunnable) {
+    console.log(
+      `\n⚠  provider is ${active} but no runnable ${active} install was found — transcription is offline until one is available (\`parachute-vault transcription install\`).`,
+    );
+  }
+  console.log(
+    `\nAvailable transcribe-cpp models (override with --model): ${Object.values(MODELS).map((m: ModelChoice) => m.name).join(", ")}`,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Schema maintenance — `parachute-vault schema <subcommand>`
 // ---------------------------------------------------------------------------
@@ -3962,11 +4633,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 +4762,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 +4920,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 +5073,30 @@ 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 this host's tier-default LOCAL provider (probes
+                                           OS/arch + RAM, prints the pick + footprint, confirms):
+                                             macOS Apple Silicon 8GB+ → parakeet-mlx (Python venv, MLX)
+                                             Linux 4GB+               → onnx-asr (Python venv, int8 ONNX)
+                                             Linux ~2GB               → transcribe-cpp + small whisper GGUF
+                                             ~1GB / below floor       → remote steer (never forced)
+                                           Activation is honest: TRANSCRIPTION_PROVIDER flips only when
+                                           a runnable binary exists. Idempotent; --dry-run prints the
+                                           pick without downloading; --force re-downloads / bypasses the
+                                           RAM floor on an explicit --provider; --yes skips the confirm.
+  parachute-vault transcription install --provider <name>
+                                           Override the tier default. transcribe-cpp downloads the
+                                           runtime libs + a GGUF (--model overrides the RAM-tier pick:
+                                           whisper-tiny.en | whisper-small.en | parakeet-tdt-0.6b-v3;
+                                           builds transcribe-cli from source — needs a C++ compiler).
+                                           parakeet-mlx / onnx-asr install a Python venv under
+                                           ~/.parachute/transcription/venv (needs python3; apt-installs
+                                           python3/ffmpeg on Linux). scribe-http switches back to the
+                                           remote provider (no download).
+  parachute-vault transcription status     Show the configured provider, this host's tier default, and
+                                           per-provider install state.
+
 ── Advanced / standalone ──────────────────────────────────────────────
 
 Direct daemon controls. For normal use, prefer the Parachute Hub wrappers