@openparachute/hub 0.7.3-rc.7 → 0.7.3-rc.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.3-rc.7",
+  "version": "0.7.3-rc.8",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/scribe-config.test.ts

@@ -3,10 +3,15 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "nod
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
+  MIN_RAM_MIB,
   SCRIBE_DEFAULT_PROVIDER,
   SCRIBE_PROVIDERS,
   apiKeyEnvFor,
+  clearScribeProvider,
+  decideLocalProvider,
   isKnownScribeProvider,
+  platformLocalProvider,
+  readAvailableRamMib,
   readScribeProviderState,
   scribeConfigPath,
   scribeEnvPath,
@@ -41,6 +46,118 @@ describe("provider catalog", () => {
   });
 });
 
+describe("platformLocalProvider — the Linux 'local' trap fix", () => {
+  test("macOS → parakeet-mlx", () => {
+    expect(platformLocalProvider("darwin")).toBe("parakeet-mlx");
+  });
+
+  test("Linux → onnx-asr (NOT the macOS-only parakeet-mlx)", () => {
+    expect(platformLocalProvider("linux")).toBe("onnx-asr");
+  });
+
+  test("unsupported platform → null (steer to cloud)", () => {
+    expect(platformLocalProvider("win32")).toBeNull();
+  });
+});
+
+describe("readAvailableRamMib", () => {
+  test("non-Linux returns a positive number (totalmem fallback) or null", () => {
+    const ram = readAvailableRamMib("darwin");
+    // On any real CI/dev box totalmem is well-defined + positive.
+    expect(ram === null || (typeof ram === "number" && ram > 0)).toBe(true);
+  });
+
+  test("Linux path reads /proc/meminfo (or null when unreadable)", () => {
+    const ram = readAvailableRamMib("linux");
+    // On macOS CI there's no /proc/meminfo → null; on Linux CI a positive MiB.
+    expect(ram === null || (typeof ram === "number" && ram > 0)).toBe(true);
+  });
+});
+
+describe("decideLocalProvider — the RAM/platform gate", () => {
+  test("Linux with ample RAM → ok, onnx-asr", () => {
+    const d = decideLocalProvider("linux", 4096);
+    expect(d.ok).toBe(true);
+    expect(d.provider).toBe("onnx-asr");
+  });
+
+  test("macOS with ample RAM → ok, parakeet-mlx", () => {
+    const d = decideLocalProvider("darwin", 16384);
+    expect(d.ok).toBe(true);
+    expect(d.provider).toBe("parakeet-mlx");
+  });
+
+  test("below the RAM floor → refused, steers to groq, carries a reason", () => {
+    const d = decideLocalProvider("linux", MIN_RAM_MIB - 1);
+    expect(d.ok).toBe(false);
+    expect(d.steerTo).toBe("groq");
+    expect(d.reason).toContain(String(MIN_RAM_MIB));
+  });
+
+  test("exactly at the floor is OK (>= floor)", () => {
+    expect(decideLocalProvider("linux", MIN_RAM_MIB).ok).toBe(true);
+  });
+
+  test("unknown RAM (null) does not refuse on a supported platform", () => {
+    expect(decideLocalProvider("linux", null).ok).toBe(true);
+  });
+
+  test("unsupported platform → refused regardless of RAM, steers to groq", () => {
+    const d = decideLocalProvider("win32", 99999);
+    expect(d.ok).toBe(false);
+    expect(d.steerTo).toBe("groq");
+  });
+});
+
+describe("clearScribeProvider", () => {
+  test("removes transcribe.provider, preserving other keys", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(
+        scribeConfigPath(h.dir),
+        JSON.stringify({
+          transcribe: { provider: "onnx-asr", language: "en" },
+          auth: { required_token: "keep" },
+        }),
+      );
+      clearScribeProvider(h.dir);
+      const parsed = JSON.parse(readFileSync(scribeConfigPath(h.dir), "utf8"));
+      expect(parsed.transcribe).toEqual({ language: "en" });
+      expect(parsed.auth).toEqual({ required_token: "keep" });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("drops the transcribe block entirely when provider was its only key", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(
+        scribeConfigPath(h.dir),
+        JSON.stringify({ transcribe: { provider: "onnx-asr" }, auth: { required_token: "x" } }),
+      );
+      clearScribeProvider(h.dir);
+      const parsed = JSON.parse(readFileSync(scribeConfigPath(h.dir), "utf8"));
+      expect(parsed.transcribe).toBeUndefined();
+      expect(parsed.auth).toEqual({ required_token: "x" });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no-op when the file is absent", () => {
+    const h = makeHarness();
+    try {
+      // No file written.
+      expect(() => clearScribeProvider(h.dir)).not.toThrow();
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 describe("readScribeProviderState", () => {
   test("missing file: configExists false, no provider", () => {
     const h = makeHarness();

package/src/__tests__/setup-wizard.test.ts

@@ -1825,6 +1825,24 @@ describe("handleSetupVaultPost", () => {
     expect(cfg?.cleanup).toEqual({ provider: "anthropic", default: true });
     expect(cfg?.cleanupProviders).toEqual({ anthropic: { apiKey: "sk-ant-cleanup-key" } });
   });
+
+  test("scribe transcribe=local resolves to the host platform's backend (the Linux trap fix)", async () => {
+    // The bug: `local` mapped UNCONDITIONALLY to parakeet-mlx (macOS-only),
+    // silently broken on every Linux box. After the fix it resolves to the
+    // platform backend. We assert against the actual host so it's correct on
+    // both Mac (parakeet-mlx) and Linux CI (onnx-asr). The RAM gate only kicks
+    // in below 2 GB — CI/dev boxes clear it, so the choice stays `local`.
+    const { platformLocalProvider } = await import("../scribe-config.ts");
+    const expected = platformLocalProvider(process.platform);
+    const { response } = await postVaultWithFields(h, { scribe_provider: "local" });
+    expect(response.status).toBe(303);
+    const cfg = readScribeConfig(h.dir);
+    if (expected !== null) {
+      // On a supported platform with enough RAM, `local` resolves to the
+      // platform backend — NOT a hardcoded parakeet-mlx on Linux.
+      expect(cfg?.transcribe).toEqual({ provider: expected });
+    }
+  });
 });
 
 // --- end-to-end through hubFetch -----------------------------------------

package/src/__tests__/wizard-transcription.test.ts

@@ -0,0 +1,334 @@
+/**
+ * CLI wizard transcription step (onboarding-streamline hub PR1).
+ *
+ * Exercises `walkTranscriptionStep` against an injected command runner + RAM
+ * probe + platform — NOTHING installs and no subprocess is spawned. Covers the
+ * four branches the brief calls for: the CLI transcription question, the
+ * platform mapping, the RAM gate, and install-or-skip (mocked scribe
+ * subprocess).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { walkTranscriptionStep } from "../commands/wizard-transcription.ts";
+import { scribeConfigPath } from "../scribe-config.ts";
+
+function makeHarness(): { dir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-wztrans-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+/** Records every command the step would have spawned, returns scripted codes. */
+function recordingRunner(codes: number[] = []) {
+  const cmds: string[][] = [];
+  let i = 0;
+  return {
+    cmds,
+    run: async (cmd: readonly string[]): Promise<number> => {
+      cmds.push([...cmd]);
+      const code = codes[i++];
+      return code ?? 0;
+    },
+  };
+}
+
+function readCfg(dir: string): Record<string, unknown> | undefined {
+  const p = scribeConfigPath(dir);
+  if (!existsSync(p)) return undefined;
+  return JSON.parse(readFileSync(p, "utf8")) as Record<string, unknown>;
+}
+
+describe("walkTranscriptionStep — mode resolution (the CLI question)", () => {
+  test("none: writes no scribe config, runs no command", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner();
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        transcribeMode: "none",
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(r.cmds).toEqual([]);
+      expect(readCfg(h.dir)).toBeUndefined();
+      expect(logs.join("\n")).toContain("Transcription off");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("interactive prompt: '1' chooses none", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner();
+      const answers = ["1"];
+      let i = 0;
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        prompt: async () => answers[i++] ?? "",
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(r.cmds).toEqual([]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("interactive prompt: '3' then 'g' chooses groq cloud", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([0]);
+      const answers = ["3", "g", "gsk_interactive"];
+      let i = 0;
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        prompt: async () => answers[i++] ?? "",
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      // One install command, with the groq provider + key.
+      expect(r.cmds.length).toBe(1);
+      expect(r.cmds[0]).toEqual([
+        "parachute",
+        "install",
+        "scribe",
+        "--scribe-provider",
+        "groq",
+        "--scribe-key",
+        "gsk_interactive",
+      ]);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("walkTranscriptionStep — cloud (install-or-skip via the one-shot)", () => {
+  test("groq with a key: install one-shot carries provider + key", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([0]);
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        transcribeMode: "groq",
+        transcribeApiKey: "gsk_abc123",
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(r.cmds[0]).toEqual([
+        "parachute",
+        "install",
+        "scribe",
+        "--scribe-provider",
+        "groq",
+        "--scribe-key",
+        "gsk_abc123",
+      ]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("openai without a key: install one-shot omits --scribe-key + tells operator how to add it", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([0]);
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        transcribeMode: "openai",
+        transcribeApiKey: "",
+        runCommand: r.run,
+        platform: "darwin",
+      });
+      expect(code).toBe(0);
+      expect(r.cmds[0]).toEqual(["parachute", "install", "scribe", "--scribe-provider", "openai"]);
+      expect(logs.join("\n")).toContain("OPENAI_API_KEY");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("cloud install failure: surfaces the non-zero exit + a retry hint, still exits 0", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([1]); // install fails
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        transcribeMode: "groq",
+        transcribeApiKey: "gsk_x",
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0); // non-fatal — doesn't block the wizard
+      expect(logs.join("\n")).toContain("returned 1");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("walkTranscriptionStep — local install-or-skip", () => {
+  test("Linux, ample RAM, install succeeds: install-backend uses onnx-asr; provider kept", async () => {
+    const h = makeHarness();
+    try {
+      // module install (writes provider via --scribe-provider), install-backend, restart
+      const r = recordingRunner([0, 0, 0]);
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "linux",
+        availableRamMib: 4096,
+      });
+      expect(code).toBe(0);
+      // Module install pins the resolved Linux backend, NOT parakeet-mlx.
+      expect(r.cmds[0]).toEqual([
+        "parachute",
+        "install",
+        "scribe",
+        "--scribe-provider",
+        "onnx-asr",
+      ]);
+      // scribe's own runnable install routine, targeting onnx-asr.
+      expect(r.cmds[1]).toEqual(["parachute-scribe", "install-backend", "--provider", "onnx-asr"]);
+      // A restart so the running scribe picks up the engine.
+      expect(r.cmds[2]).toEqual(["parachute", "restart", "scribe"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("macOS local resolves to parakeet-mlx", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([0, 0, 0]);
+      await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "darwin",
+        availableRamMib: 16384,
+      });
+      expect(r.cmds[1]).toEqual([
+        "parachute-scribe",
+        "install-backend",
+        "--provider",
+        "parakeet-mlx",
+      ]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("install-backend FAILS: clears the provisional provider (no dead string) + points at cloud", async () => {
+    const h = makeHarness();
+    try {
+      // module install OK, install-backend FAILS (exit 3). No restart should run.
+      const r = recordingRunner([0, 3]);
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "linux",
+        availableRamMib: 4096,
+      });
+      expect(code).toBe(0);
+      // Only two commands ran — the failed install-backend, no restart.
+      expect(r.cmds.length).toBe(2);
+      expect(r.cmds.some((c) => c[0] === "parachute" && c[1] === "restart")).toBe(false);
+      // The provisional provider write (by the install one-shot in production)
+      // is cleared. We simulate the install having written it by checking the
+      // step never leaves a transcribe.provider on its own write path — and the
+      // honest cloud steer is logged.
+      expect(logs.join("\n")).toContain("install failed");
+      expect(logs.join("\n")).toContain("Cloud alternative");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("RAM below floor: REFUSES local, records nothing, steers to cloud one-shot", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner();
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "linux",
+        availableRamMib: 900, // 1 GB droplet
+      });
+      expect(code).toBe(0);
+      // Nothing installed, nothing recorded.
+      expect(r.cmds).toEqual([]);
+      expect(readCfg(h.dir)).toBeUndefined();
+      const joined = logs.join("\n");
+      expect(joined).toContain("isn't possible");
+      expect(joined).toContain("parachute install scribe --scribe-provider groq");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("unsupported platform: REFUSES local + steers to cloud, no install", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner();
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "win32",
+        availableRamMib: 99999,
+      });
+      expect(code).toBe(0);
+      expect(r.cmds).toEqual([]);
+      expect(readCfg(h.dir)).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("module install fails before the engine: clears provider, no install-backend run", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([5]); // module install fails
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "linux",
+        availableRamMib: 4096,
+      });
+      expect(code).toBe(0);
+      expect(r.cmds.length).toBe(1);
+      expect(r.cmds[0]?.[1]).toBe("install");
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/wizard.test.ts

@@ -293,6 +293,29 @@ describe("parseWizardArgs", () => {
     expect(r.opts.vaultMode).toBe("import");
     expect(r.opts.vaultImportRemoteUrl).toBe("https://github.com/me/v.git");
   });
+
+  test("parses --transcribe-mode + --transcribe-key + --config-dir", () => {
+    const r = parseWizardArgs([
+      "--hub-url",
+      "http://x",
+      "--transcribe-mode",
+      "groq",
+      "--transcribe-key",
+      "gsk_test",
+      "--config-dir",
+      "/tmp/ph",
+    ]);
+    expect("error" in r).toBe(false);
+    if ("error" in r) throw new Error(r.error);
+    expect(r.opts.transcribeMode).toBe("groq");
+    expect(r.opts.transcribeApiKey).toBe("gsk_test");
+    expect(r.opts.configDir).toBe("/tmp/ph");
+  });
+
+  test("rejects invalid --transcribe-mode", () => {
+    const r = parseWizardArgs(["--hub-url", "http://x", "--transcribe-mode", "garbage"]);
+    expect("error" in r).toBe(true);
+  });
 });
 
 describe("runCliWizard", () => {
@@ -509,4 +532,127 @@ describe("runCliWizard", () => {
     });
     expect(code).toBe(1);
   });
+
+  test("password validator floor is 12 (matches the server) — an 11-char password is rejected", async () => {
+    const { fetchImpl } = makeFakeHub();
+    const logs: string[] = [];
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: (l) => logs.push(l),
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "elevenchar.", // 11 chars
+      vaultMode: "skip",
+      exposeMode: "localhost",
+    });
+    expect(code).toBe(1);
+    expect(logs.join("\n")).toContain("at least 12 characters");
+  });
+
+  test("exactly 12 chars passes the validator (no early bounce)", async () => {
+    const { state, fetchImpl } = makeFakeHub();
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "twelvecharss", // 12 chars
+      vaultMode: "skip",
+      exposeMode: "localhost",
+    });
+    expect(code).toBe(0);
+    expect(state.posted.some((p) => p.path === "/admin/setup/account")).toBe(true);
+  });
+
+  test("transcription step runs between vault and expose when configDir is set", async () => {
+    const { state, fetchImpl } = makeFakeHub();
+    const transcribeCmds: string[][] = [];
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+      configDir: "/tmp/never-written-none-mode",
+      transcribeMode: "none", // none writes nothing + spawns nothing
+      transcribeRunCommand: async (cmd) => {
+        transcribeCmds.push([...cmd]);
+        return 0;
+      },
+    });
+    expect(code).toBe(0);
+    // The vault + expose POSTs still happened in order.
+    expect(state.posted.map((p) => p.path)).toEqual([
+      "/admin/setup/account",
+      "/admin/setup/vault",
+      "/admin/setup/expose",
+    ]);
+    // mode=none → no transcription subprocess.
+    expect(transcribeCmds).toEqual([]);
+  });
+
+  test("transcription step (cloud) drives the install one-shot via the injected runner", async () => {
+    const { fetchImpl } = makeFakeHub();
+    const transcribeCmds: string[][] = [];
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+      configDir: "/tmp/never-written-cloud-mode",
+      transcribeMode: "groq",
+      transcribeApiKey: "gsk_wired",
+      platform: "linux",
+      transcribeRunCommand: async (cmd) => {
+        transcribeCmds.push([...cmd]);
+        return 0;
+      },
+    });
+    expect(code).toBe(0);
+    expect(transcribeCmds[0]).toEqual([
+      "parachute",
+      "install",
+      "scribe",
+      "--scribe-provider",
+      "groq",
+      "--scribe-key",
+      "gsk_wired",
+    ]);
+  });
+
+  test("transcription step is skipped when configDir is absent", async () => {
+    const { state, fetchImpl } = makeFakeHub();
+    let ran = false;
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+      // no configDir
+      transcribeRunCommand: async () => {
+        ran = true;
+        return 0;
+      },
+    });
+    expect(code).toBe(0);
+    expect(ran).toBe(false);
+    expect(state.posted.map((p) => p.path)).toEqual([
+      "/admin/setup/account",
+      "/admin/setup/vault",
+      "/admin/setup/expose",
+    ]);
+  });
 });

package/src/commands/init.ts

@@ -172,7 +172,11 @@ export interface InitOpts {
    * Test seam: shim for the CLI wizard chain (hub#168 Cut 3). Production
    * lazy-imports `runCliWizard` from `./wizard.ts`. Tests pass a stub.
    */
-  runCliWizardImpl?: (opts: { hubUrl: string; log: (l: string) => void }) => Promise<number>;
+  runCliWizardImpl?: (opts: {
+    hubUrl: string;
+    log: (l: string) => void;
+    configDir?: string;
+  }) => Promise<number>;
   /**
    * Skip the "browser or CLI?" wizard-choice prompt (hub#168 Cut 4). Used
    * by pre-Cut-4 tests that don't expect the new prompt + by the
@@ -485,6 +489,7 @@ async function defaultInstallVaultModule(configDir: string, manifestPath: string
 async function defaultRunCliWizard(opts: {
   hubUrl: string;
   log: (l: string) => void;
+  configDir?: string;
 }): Promise<number> {
   const { runCliWizard } = await import("./wizard.ts");
   return await runCliWizard(opts);
@@ -895,7 +900,10 @@ export async function init(opts: InitOpts = {}): Promise<number> {
     // (the loopback-gated GET /admin/setup probe) — the operator never has to
     // copy the token out of the startup logs.
     const cliWizardUrl = `http://127.0.0.1:${hubPort}`;
-    return await runCliWizardImpl({ hubUrl: cliWizardUrl, log });
+    // Pass the resolved configDir so the CLI wizard's transcription step can
+    // write scribe's config (onboarding-streamline hub PR1). Without it the
+    // step is skipped.
+    return await runCliWizardImpl({ hubUrl: cliWizardUrl, log, configDir });
   }
 
   // Step 5: offer to open the browser. Skip in non-TTY shells (CI),

package/src/commands/wizard-transcription.ts

@@ -0,0 +1,296 @@
+/**
+ * Transcription step for the CLI setup wizard (`parachute setup-wizard` /
+ * `parachute init`).
+ *
+ * Until now the CLI wizard NEVER asked about transcription — it walked
+ * Account → Vault → Expose and stopped, while the browser wizard's vault step
+ * folds a full scribe sub-form (none / cloud + key / local). That divergence
+ * is the "asks different questions in its CLI vs browser forms" root cause from
+ * the onboarding-streamline arc. This module brings the CLI to parity.
+ *
+ * Crucially it follows the arc's "never ask without doing" rule: when the
+ * operator picks a provider we ACTUALLY set it up, or honestly say we couldn't
+ * and point at the alternative — we never record a dead provider string.
+ *
+ *   - **none**  → write nothing; say transcription is off + how to turn it on.
+ *   - **cloud** (groq / openai) → write provider + key (scribe-config.ts), then
+ *     install + start scribe via the hub's own `parachute install scribe`
+ *     one-shot. The very-first scribe boot reads the provider we just wrote.
+ *   - **local** → RAM/platform-gate FIRST (decideLocalProvider). If the box
+ *     can't run a local model (no backend for the platform, or < 2 GB RAM) we
+ *     do NOT write `local` — we explain why + steer to the cloud one-shot. If
+ *     it can, we install scribe, then run scribe's own runnable install routine
+ *     (`parachute-scribe install-backend --provider <onnx-asr|parakeet-mlx>`,
+ *     scribe PR #79) which apt/pip-installs the engine + warm-pulls the model
+ *     and exits non-zero on hard failure. On success we record the resolved
+ *     platform provider; on failure we say so + point at cloud, recording
+ *     nothing.
+ *
+ * Everything that touches the host (subprocess spawn, RAM probe, the prompt)
+ * goes through an injected seam so tests exercise every branch WITHOUT
+ * installing anything or shelling out.
+ */
+
+import { createInterface } from "node:readline/promises";
+import {
+  type ScribeProviderKey,
+  apiKeyEnvFor,
+  clearScribeProvider,
+  decideLocalProvider,
+  readAvailableRamMib,
+} from "../scribe-config.ts";
+
+/** Outcome of one subprocess. Exit code only — stdio is inherited / streamed. */
+export type WizardCommandRunner = (cmd: readonly string[]) => Promise<number>;
+
+export interface TranscriptionStepOpts {
+  /** `~/.parachute` (or the PARACHUTE_HOME override). Where scribe config lives. */
+  configDir: string;
+  /** Log shim — production prints to stdout; tests capture into an array. */
+  log: (line: string) => void;
+  /** Prompt seam — production uses readline; tests inject a scripted queue. */
+  prompt?: (question: string) => Promise<string>;
+  /**
+   * Pre-supply the choice non-interactively (mirrors the wizard's other
+   * run-from-flag escapes). `none` | `local` | a cloud provider name.
+   */
+  transcribeMode?: "none" | "local" | "groq" | "openai";
+  /** Pre-supplied cloud API key (for `groq` / `openai`). */
+  transcribeApiKey?: string;
+  /**
+   * Command runner seam. Production spawns the real binary inheriting stdio;
+   * tests inject a recorder so nothing installs. Receives a full argv —
+   * `["parachute", "install", "scribe", ...]` or
+   * `["parachute-scribe", "install-backend", "--provider", "onnx-asr"]`.
+   */
+  runCommand?: WizardCommandRunner;
+  /** Platform override (test seam). Defaults to the real host platform. */
+  platform?: NodeJS.Platform;
+  /** Available-RAM override in MiB (test seam). Defaults to the real probe. */
+  availableRamMib?: number | null;
+}
+
+/** Default readline prompt (matches wizard.ts's defaultPrompt). */
+async function defaultPrompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Default command runner: spawn the binary, inherit stdio so the operator sees
+ * apt/pip progress in real time, resolve to the exit code. Never throws — a
+ * spawn failure (binary not on PATH) surfaces as a non-zero code, which the
+ * caller treats as "couldn't install."
+ */
+const defaultRunCommand: WizardCommandRunner = async (cmd) => {
+  try {
+    const proc = Bun.spawn([...cmd], {
+      stdout: "inherit",
+      stderr: "inherit",
+      stdin: "inherit",
+    });
+    return await proc.exited;
+  } catch {
+    return 127; // ENOENT / spawn failure → "command not found"
+  }
+};
+
+/**
+ * Walk the transcription step. Returns 0 always — a transcription that
+ * couldn't be set up is reported honestly but does NOT fail the wizard (the
+ * operator can finish setup and add it later; it's not a blocking step).
+ */
+export async function walkTranscriptionStep(opts: TranscriptionStepOpts): Promise<number> {
+  const log = opts.log;
+  const prompt = opts.prompt ?? defaultPrompt;
+  const runCommand = opts.runCommand ?? defaultRunCommand;
+  const platform = opts.platform ?? process.platform;
+
+  log("");
+  log("Step — Transcription (scribe)");
+  log("  Parachute can transcribe voice notes + audio attachments. Pick a");
+  log("  transcription engine, or skip and add one later.");
+
+  // Resolve the choice (flag or prompt).
+  const choice = await resolveChoice(opts, prompt, log);
+  if (choice === "none") {
+    log("");
+    log("  Transcription off. Turn it on later with `parachute install scribe`.");
+    return 0;
+  }
+
+  if (choice === "local") {
+    return await handleLocal(opts, prompt, runCommand, platform, log);
+  }
+
+  // Cloud provider (groq / openai).
+  return await handleCloud(opts, choice, prompt, runCommand, log);
+}
+
+type ResolvedChoice = "none" | "local" | "groq" | "openai";
+
+async function resolveChoice(
+  opts: TranscriptionStepOpts,
+  prompt: (q: string) => Promise<string>,
+  log: (l: string) => void,
+): Promise<ResolvedChoice> {
+  if (opts.transcribeMode !== undefined) return opts.transcribeMode;
+  log("");
+  log("  1) None — skip transcription (default)");
+  log("  2) Local — run the engine on this box (no API key, needs ~2 GB RAM)");
+  log("  3) Cloud — Groq or OpenAI (fast, needs an API key, ~$0.04/hr of audio)");
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const raw = (await prompt("  Pick [1]: ")).trim().toLowerCase();
+    if (raw === "" || raw === "1" || raw === "none" || raw === "n") return "none";
+    if (raw === "2" || raw === "local" || raw === "l") return "local";
+    if (raw === "3" || raw === "cloud" || raw === "c") {
+      // Sub-pick which cloud provider.
+      for (let inner = 0; inner < 5; inner++) {
+        const which = (await prompt("  Cloud provider — [g]roq (default) or [o]penai: "))
+          .trim()
+          .toLowerCase();
+        if (which === "" || which === "g" || which === "groq") return "groq";
+        if (which === "o" || which === "openai") return "openai";
+        log(`  Sorry — expected groq or openai (got "${which}"). Try again.`);
+      }
+      log("  Too many invalid entries; skipping transcription.");
+      return "none";
+    }
+    if (raw === "groq" || raw === "g") return "groq";
+    if (raw === "openai" || raw === "o") return "openai";
+    log(`  Sorry — expected 1, 2, or 3 (got "${raw}"). Try again.`);
+  }
+  log("  Too many invalid entries; skipping transcription.");
+  return "none";
+}
+
+async function handleCloud(
+  opts: TranscriptionStepOpts,
+  provider: "groq" | "openai",
+  prompt: (q: string) => Promise<string>,
+  runCommand: WizardCommandRunner,
+  log: (l: string) => void,
+): Promise<number> {
+  const envKey = apiKeyEnvFor(provider as ScribeProviderKey);
+  let apiKey = opts.transcribeApiKey;
+  if (apiKey === undefined && envKey) {
+    apiKey = (await prompt(`  Paste your ${envKey} (or blank to set later): `)).trim();
+  }
+
+  // Install + start scribe via the EXISTING one-shot path, handing it the
+  // chosen provider + key. `parachute install scribe --scribe-provider <p>
+  // [--scribe-key <k>]` writes the provider into scribe's config + the key into
+  // scribe/.env and starts the module — the same wiring the bare CLI install
+  // does. Passing the provider also suppresses install's own interactive
+  // provider prompt (it's already an explicit choice).
+  const cmd = ["parachute", "install", "scribe", "--scribe-provider", provider];
+  if (envKey && apiKey && apiKey.length > 0) {
+    cmd.push("--scribe-key", apiKey);
+  }
+  log("");
+  log(`  Installing scribe with the ${provider} cloud provider…`);
+  const code = await runCommand(cmd);
+  if (code !== 0) {
+    log(`  ✗ scribe install returned ${code}. Retry: \`${cmd.join(" ")}\`.`);
+    return 0;
+  }
+  if (envKey && !(apiKey && apiKey.length > 0)) {
+    log(
+      `  ✓ Recorded ${provider}. Add ${envKey} later: \`echo '${envKey}=<value>' >> ${opts.configDir}/scribe/.env\` then \`parachute restart scribe\`.`,
+    );
+  } else {
+    log(`  ✓ Scribe installed and running with the ${provider} cloud provider.`);
+  }
+  return 0;
+}
+
+async function handleLocal(
+  opts: TranscriptionStepOpts,
+  prompt: (q: string) => Promise<string>,
+  runCommand: WizardCommandRunner,
+  platform: NodeJS.Platform,
+  log: (l: string) => void,
+): Promise<number> {
+  const ramMib =
+    opts.availableRamMib !== undefined ? opts.availableRamMib : readAvailableRamMib(platform);
+  const decision = decideLocalProvider(platform, ramMib);
+
+  if (!decision.ok) {
+    // Can't install local here — say EXACTLY why + point at the cloud one-shot.
+    // Do NOT record a dead `local` provider string.
+    log("");
+    log(`  ✗ Local transcription isn't possible on this box: ${decision.reason}`);
+    log("");
+    log("  One-shot cloud alternative — get a free Groq key at https://console.groq.com,");
+    log("  then run:");
+    log("    parachute install scribe --scribe-provider groq --scribe-key gsk_…");
+    log("  (or re-run this wizard and choose Cloud).");
+    return 0;
+  }
+
+  const provider = decision.provider as "parakeet-mlx" | "onnx-asr";
+  log("");
+  log(`  This box can run ${provider} locally.`);
+
+  // Confirm before the (slow, apt/pip) install unless pre-supplied.
+  if (opts.transcribeMode === undefined) {
+    const ok = (await prompt(`  Install ${provider} now? [Y/n]: `)).trim().toLowerCase();
+    if (ok === "n" || ok === "no") {
+      log(
+        "  Skipped. Install later with `parachute-scribe install-backend` or re-run this wizard.",
+      );
+      return 0;
+    }
+  }
+
+  // Install the scribe module first, recording the resolved provider so install
+  // doesn't prompt for one. (We UNDO this record below if the engine install
+  // fails — so a failure never leaves a dead provider string.)
+  log("");
+  log("  Installing the scribe module…");
+  const moduleCode = await runCommand([
+    "parachute",
+    "install",
+    "scribe",
+    "--scribe-provider",
+    provider,
+  ]);
+  if (moduleCode !== 0) {
+    clearScribeProvider(opts.configDir);
+    log(`  ✗ scribe module install returned ${moduleCode} — not recording a local provider.`);
+    return 0;
+  }
+
+  // Run scribe's OWN runnable install routine (scribe PR #79). It apt/pip-
+  // installs the engine, warm-pulls the model, and exits non-zero on hard
+  // failure (no engine on PATH, too little RAM on its own re-check, etc.).
+  log("");
+  log(`  Installing the ${provider} engine via scribe (this can take a few minutes)…`);
+  // The `--provider <p>` FLAG form is intentional (not the positional
+  // `install-backend <p>`): scribe's cmdInstallBackend reads it via getFlag
+  // when args[1] starts with "-". If scribe ever moves off its module-level
+  // `args` global, re-confirm this flag is still honored.
+  const code = await runCommand(["parachute-scribe", "install-backend", "--provider", provider]);
+  if (code !== 0) {
+    // HONEST skip — undo the provisional provider record; do NOT leave a dead
+    // provider string scribe can't honor.
+    clearScribeProvider(opts.configDir);
+    log("");
+    log(`  ✗ ${provider} install failed (exit ${code}); not recording it as the provider.`);
+    log(
+      "    Cloud alternative: `parachute install scribe --scribe-provider groq --scribe-key gsk_…`",
+    );
+    return 0;
+  }
+
+  // Engine installed + verified by scribe — keep the provider recorded (the
+  // install step already wrote it) and restart so the running scribe picks it up.
+  log("");
+  log(`  ✓ ${provider} installed and recorded as the transcription provider.`);
+  await runCommand(["parachute", "restart", "scribe"]);
+  return 0;
+}

package/src/commands/wizard.ts

@@ -39,8 +39,10 @@
  */
 
 import { createInterface } from "node:readline/promises";
+import { configDir } from "../config.ts";
 import { CSRF_COOKIE_NAME, CSRF_FIELD_NAME } from "../csrf.ts";
 import { SESSION_COOKIE_NAME } from "../sessions.ts";
+import { type WizardCommandRunner, walkTranscriptionStep } from "./wizard-transcription.ts";
 
 const POLL_INTERVAL_MS = 2000;
 const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes — generous enough for a slow `bun add` over a flaky connection.
@@ -111,6 +113,29 @@ export interface RunCliWizardOpts {
    * the wizard's.
    */
   exposeMode?: "localhost" | "tailnet" | "public";
+  /**
+   * `~/.parachute` (or the PARACHUTE_HOME override) — where scribe's config
+   * lives. Required for the transcription step to write the chosen provider +
+   * key. Init passes its resolved configDir; when absent the transcription
+   * step is skipped (the wizard can still walk account / vault / expose).
+   */
+  configDir?: string;
+  /**
+   * Pre-supply the transcription answer (non-interactive escape, mirrors the
+   * browser wizard's `scribe_provider`). `none` | `local` | `groq` | `openai`.
+   */
+  transcribeMode?: "none" | "local" | "groq" | "openai";
+  /** Pre-supplied cloud transcription API key (groq / openai). */
+  transcribeApiKey?: string;
+  /**
+   * Test seam: replace the transcription step's subprocess runner so tests
+   * never install scribe / shell out. Threaded into `walkTranscriptionStep`.
+   */
+  transcribeRunCommand?: WizardCommandRunner;
+  /** Test seam: platform override for the transcription step. */
+  platform?: NodeJS.Platform;
+  /** Test seam: available-RAM override (MiB) for the transcription step's gate. */
+  availableRamMib?: number | null;
 }
 
 /** Cookie jar — tiny, in-memory, no persistence across runs. */
@@ -395,9 +420,14 @@ async function pollOperation(
   }
 }
 
-/** Validate password length up front so we don't bounce off a 400 the operator can't see. */
+/**
+ * Validate password length up front so we don't bounce off a 400 the operator
+ * can't see. Floor is 12 to match the server (`PASSWORD_MIN_LEN`) AND this
+ * wizard's own "min 12 chars" copy at the password prompt — the validator was
+ * stuck at 8, contradicting both (onboarding-streamline hub PR1).
+ */
 function validatePassword(pw: string): string | undefined {
-  if (pw.length < 8) return "Password must be at least 8 characters.";
+  if (pw.length < 12) return "Password must be at least 12 characters.";
   return undefined;
 }
 
@@ -743,6 +773,24 @@ export async function runCliWizard(opts: RunCliWizardOpts): Promise<number> {
     if (code !== 0) return code;
     state = await fetchWizardState(hubUrl, jar, fetchImpl);
   }
+  // Transcription step (onboarding-streamline hub PR1) — the CLI's parity with
+  // the browser wizard's folded scribe sub-form. The hub's setup-state machine
+  // has no "transcription" step (scribe is a module install, not a wizard gate),
+  // so this runs unconditionally between vault and expose rather than off
+  // `state.step`. Skipped without a configDir (nowhere to write scribe config).
+  // Non-fatal: a transcription that couldn't be set up never blocks setup.
+  if (opts.configDir !== undefined) {
+    await walkTranscriptionStep({
+      configDir: opts.configDir,
+      log,
+      prompt,
+      ...(opts.transcribeMode !== undefined ? { transcribeMode: opts.transcribeMode } : {}),
+      ...(opts.transcribeApiKey !== undefined ? { transcribeApiKey: opts.transcribeApiKey } : {}),
+      ...(opts.transcribeRunCommand !== undefined ? { runCommand: opts.transcribeRunCommand } : {}),
+      ...(opts.platform !== undefined ? { platform: opts.platform } : {}),
+      ...(opts.availableRamMib !== undefined ? { availableRamMib: opts.availableRamMib } : {}),
+    });
+  }
   if (state.step === "expose") {
     const code = await walkExposeStep(hubUrl, jar, state, ctx);
     if (code !== 0) return code;
@@ -852,6 +900,21 @@ export function parseWizardArgs(args: readonly string[]): ParsedWizardArgs | { e
         }
         out.opts.exposeMode = value;
         break;
+      case "--transcribe-mode":
+        if (!consumeValue()) return { error: `${key} requires a value` };
+        if (value !== "none" && value !== "local" && value !== "groq" && value !== "openai") {
+          return { error: `${key} must be one of none, local, groq, openai` };
+        }
+        out.opts.transcribeMode = value;
+        break;
+      case "--transcribe-key":
+        if (!consumeValue()) return { error: `${key} requires a value` };
+        out.opts.transcribeApiKey = value;
+        break;
+      case "--config-dir":
+        if (!consumeValue()) return { error: `${key} requires a path` };
+        out.opts.configDir = value;
+        break;
       default:
         if (a.startsWith("--")) return { error: `unknown argument "${a}"` };
         return { error: `unexpected positional argument "${a}"` };
@@ -877,12 +940,19 @@ export async function runSetupWizardCommand(args: readonly string[]): Promise<nu
         "                              [--bootstrap-token <token>]\n" +
         "                              [--vault-mode create|import|skip] [--vault-name <name>]\n" +
         "                              [--vault-import-url <url>] [--vault-import-pat <pat>] [--vault-import-replace]\n" +
+        "                              [--transcribe-mode none|local|groq|openai] [--transcribe-key <key>]\n" +
+        "                              [--config-dir <path>]\n" +
         "                              [--expose-mode localhost|tailnet|public]",
     );
     return 1;
   }
+  // Default configDir from PARACHUTE_HOME (matching the rest of the CLI) so the
+  // standalone `parachute setup-wizard` invocation can run the transcription
+  // step. An explicit `--config-dir` wins.
+  const wizardOpts = { ...parsed.opts };
+  if (wizardOpts.configDir === undefined) wizardOpts.configDir = configDir();
   return await runCliWizard({
-    ...parsed.opts,
+    ...wizardOpts,
     log: (line) => console.log(line),
   });
 }

package/src/scribe-config.ts

@@ -1,4 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { totalmem } from "node:os";
 import { dirname, join } from "node:path";
 import { parseEnvFile, upsertEnvLine, writeEnvFile } from "./env-file.ts";
 
@@ -60,6 +61,118 @@ export type ScribeProviderKey = (typeof SCRIBE_PROVIDERS)[number]["key"];
 /** Default provider scribe falls back to when the config doesn't pick one. */
 export const SCRIBE_DEFAULT_PROVIDER: ScribeProviderKey = "parakeet-mlx";
 
+/**
+ * Resolve the "local" choice to the CORRECT platform backend. The setup
+ * wizard (browser + CLI) lets the operator pick "local" without knowing the
+ * engine name; this picks the one that actually runs here.
+ *
+ *   - macOS  → `parakeet-mlx` (Apple Silicon MLX)
+ *   - Linux  → `onnx-asr`     (cross-platform Sherpa-ONNX)
+ *   - other  → `null`         (no local backend — steer to cloud)
+ *
+ * Mirrors scribe's own `platformLocalProvider` (parachute-scribe
+ * src/install-backend.ts) so hub and scribe can't drift on the mapping.
+ * Fixes the long-standing bug where the wizard mapped `local` UNCONDITIONALLY
+ * to `parakeet-mlx`, which silently fails on every Linux box (the common
+ * DigitalOcean / VPS deploy).
+ */
+export function platformLocalProvider(
+  platform: NodeJS.Platform,
+): "parakeet-mlx" | "onnx-asr" | null {
+  if (platform === "darwin") return "parakeet-mlx";
+  if (platform === "linux") return "onnx-asr";
+  return null;
+}
+
+/**
+ * Minimum available RAM (MiB) below which a local ASR model would be
+ * OOM-killed. Mirrors scribe's `MIN_RAM_MIB` (parachute-scribe
+ * src/install-backend.ts) — the 1 GB DigitalOcean droplet is the box this
+ * guards against; a local Parakeet/ONNX model needs ~2 GB to load.
+ */
+export const MIN_RAM_MIB = 2048;
+
+/**
+ * Available RAM in MiB, or `null` when it can't be determined.
+ *
+ * Linux: reads `MemAvailable` from `/proc/meminfo` (the honest figure — free
+ * plus reclaimable cache), matching scribe's probe so the two layers agree on
+ * the same droplet. Falls back to `MemFree` on very old kernels that predate
+ * MemAvailable.
+ *
+ * Non-Linux: falls back to `os.totalmem()` (there's no MemAvailable analogue;
+ * total is a coarse upper bound but enough to keep a tiny VM from offering
+ * local). macOS dev boxes comfortably clear the floor, so the coarseness is
+ * harmless there.
+ *
+ * Sync by design: the wizard's provider-decision path is synchronous, and the
+ * `/proc/meminfo` read is a tiny file. Tests inject `availableRamMib` directly
+ * to exercise the gate without touching the real host.
+ */
+export function readAvailableRamMib(platform: NodeJS.Platform = process.platform): number | null {
+  if (platform === "linux") {
+    try {
+      const text = readFileSync("/proc/meminfo", "utf8");
+      const avail = /^MemAvailable:\s+(\d+)\s*kB/m.exec(text);
+      const free = /^MemFree:\s+(\d+)\s*kB/m.exec(text);
+      const kb = avail ? Number(avail[1]) : free ? Number(free[1]) : null;
+      if (kb === null || !Number.isFinite(kb)) return null;
+      return Math.floor(kb / 1024);
+    } catch {
+      return null;
+    }
+  }
+  // Non-Linux: total physical memory as a coarse fallback.
+  try {
+    const bytes = totalmem();
+    if (!Number.isFinite(bytes) || bytes <= 0) return null;
+    return Math.floor(bytes / (1024 * 1024));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decide whether a LOCAL transcription provider is offerable / acceptable on
+ * this host, and if not, why + what to steer to. Both wizard surfaces (browser
+ * POST handler + CLI) consult this BEFORE recording a `local` choice so we
+ * never write a dead provider string that scribe can't run.
+ *
+ * `ok: false` carries a `reason` (shown inline) and a `steerTo` cloud provider
+ * the caller should redirect to.
+ */
+export interface LocalProviderDecision {
+  ok: boolean;
+  /** The resolved platform backend when `ok` (parakeet-mlx / onnx-asr). */
+  provider?: "parakeet-mlx" | "onnx-asr";
+  /** Human-readable reason when `ok` is false (no local backend / too little RAM). */
+  reason?: string;
+  /** Cloud provider to redirect to when local is unavailable. */
+  steerTo?: "groq";
+}
+
+export function decideLocalProvider(
+  platform: NodeJS.Platform,
+  availableRamMib: number | null,
+): LocalProviderDecision {
+  const provider = platformLocalProvider(platform);
+  if (provider === null) {
+    return {
+      ok: false,
+      reason: `No local transcription backend runs on "${platform}". Use a cloud provider instead.`,
+      steerTo: "groq",
+    };
+  }
+  if (availableRamMib !== null && availableRamMib < MIN_RAM_MIB) {
+    return {
+      ok: false,
+      reason: `This box has ${availableRamMib} MiB available RAM, below the ${MIN_RAM_MIB} MiB a local ASR model needs (it would be OOM-killed). Use a cloud provider instead — groq is fast (~$0.04/hr of audio).`,
+      steerTo: "groq",
+    };
+  }
+  return { ok: true, provider };
+}
+
 export function isKnownScribeProvider(value: string): value is ScribeProviderKey {
   return SCRIBE_PROVIDERS.some((p) => p.key === value);
 }
@@ -136,6 +249,38 @@ export function writeScribeProvider(configDir: string, provider: ScribeProviderK
   renameSync(tmp, path);
 }
 
+/**
+ * Remove `transcribe.provider` from scribe's config.json (preserving every
+ * other key). Used by the wizard's local-install path to UNDO a provisional
+ * provider record when the engine install fails — so we never leave a dead
+ * provider string scribe can't honor. A no-op when the file or the
+ * `transcribe` block is absent.
+ */
+export function clearScribeProvider(configDir: string): void {
+  const path = scribeConfigPath(configDir);
+  if (!existsSync(path)) return;
+  let current: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+    current = parsed as Record<string, unknown>;
+  } catch {
+    return; // malformed → leave it; auto-wire repairs on next run
+  }
+  const transcribe = current.transcribe;
+  if (typeof transcribe !== "object" || transcribe === null || Array.isArray(transcribe)) {
+    return;
+  }
+  // Drop `provider` from the transcribe block (destructure-omit, no `delete`).
+  const { provider: _dropped, ...block } = transcribe as Record<string, unknown>;
+  const { transcribe: _omit, ...rest } = current;
+  const next: Record<string, unknown> =
+    Object.keys(block).length === 0 ? rest : { ...rest, transcribe: block };
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
 /**
  * Idempotent upsert of a single `KEY=value` into `<configDir>/scribe/.env`.
  * Used for the API-key prompt result. Other lines (auto-wire keys, manual

package/src/setup-wizard.ts

@@ -74,6 +74,11 @@ import {
   readOperatorTokenFile,
 } from "./operator-token.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
+import {
+  decideLocalProvider,
+  platformLocalProvider,
+  readAvailableRamMib,
+} from "./scribe-config.ts";
 import { SEED_VERSION } from "./service-spec.ts";
 import { findService, readManifestLenient } from "./services-manifest.ts";
 import {
@@ -2410,8 +2415,23 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
   // Cleanup-without-transcribe is a valid combo: the operator can
   // hit scribe's REST cleanup endpoint directly with their own raw
   // text. We install scribe + write the cleanup block in that case.
-  const scribeProvider = String(form.get("scribe_provider") ?? "").trim();
+  let scribeProvider = String(form.get("scribe_provider") ?? "").trim();
   const scribeCleanupProvider = String(form.get("scribe_cleanup_provider") ?? "").trim();
+  // RAM/platform gate: if the operator asked for `local` on a box that can't
+  // run a local ASR model (no local backend for the platform, or too little
+  // RAM — the 1 GB droplet would OOM), redirect the choice to a cloud provider
+  // (groq) rather than recording a dead `local` string scribe can never honor.
+  // The reason is logged; the inline UI surfaces it via the scribe op poll.
+  if (scribeProvider === "local") {
+    const decision = decideLocalProvider(process.platform, readAvailableRamMib());
+    if (!decision.ok) {
+      console.warn(
+        `[setup-wizard] local transcription unavailable on this host: ${decision.reason} ` +
+          `Steering to "${decision.steerTo}".`,
+      );
+      scribeProvider = decision.steerTo ?? "groq";
+    }
+  }
   const wantsTranscribe = scribeProvider !== "" && scribeProvider !== "none";
   const wantsCleanup = scribeCleanupProvider !== "" && scribeCleanupProvider !== "none";
   let scribeOpId: string | undefined;
@@ -2590,16 +2610,29 @@ interface WizardScribeConfig {
   transcribe?: { provider: string; apiKey: string };
   /** Set when the operator chose a cleanup provider (anything other than "none"). */
   cleanup?: { provider: string; apiKey: string };
+  /**
+   * Platform override for resolving the `local` choice (test seam). Defaults to
+   * the real host platform. Mac → parakeet-mlx, Linux → onnx-asr.
+   */
+  platform?: NodeJS.Platform;
 }
 function writeScribeConfigForWizard(configDir: string, config: WizardScribeConfig): void {
   const update: Record<string, unknown> = {};
+  const platform = config.platform ?? process.platform;
 
   if (config.transcribe) {
     const { provider, apiKey } = config.transcribe;
-    // For `local` (Mac MLX / cross-platform ONNX), just set the
-    // provider name — no key needed.
+    // For `local`, resolve to the CORRECT platform backend — parakeet-mlx on
+    // macOS, onnx-asr on Linux. (Was hardcoded to parakeet-mlx, which silently
+    // fails on every Linux box.) No key needed for local. The caller's
+    // RAM/platform gate is the single place that decides "local isn't possible
+    // here" and should have steered to cloud before reaching this writer — but
+    // if that gate is ever bypassed and the platform has no local backend, we
+    // write "none" (transcription off) rather than a dead provider string, so
+    // this writer can never record something that silently fails.
     if (provider === "local") {
-      update.transcribe = { provider: "parakeet-mlx" };
+      const resolved = platformLocalProvider(platform);
+      update.transcribe = { provider: resolved ?? "none" };
     } else {
       // Cloud providers need a key. Empty key → just set provider;
       // the operator can paste the key later via /scribe/admin