@openparachute/hub 0.7.2 → 0.7.3-rc.10

package/src/commands/serve.ts

@@ -37,13 +37,14 @@ import { readExposeState } from "../expose-state.ts";
 import { createDbHolder, defaultStatInode, startDbPathLivenessTimer } from "../hub-db-liveness.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
+import { getHubOrigin } from "../hub-settings.ts";
 import { writeHubFile } from "../hub.ts";
-import { createWsBridgeHandlers } from "../ws-bridge.ts";
 import { enrichedPath } from "../spawn-path.ts";
 import { Supervisor } from "../supervisor.ts";
 import { createUser, userCount } from "../users.ts";
 import { sanitizePublicOrigin } from "../vault-hub-origin-env.ts";
 import { WELL_KNOWN_DIR } from "../well-known.ts";
+import { createWsBridgeHandlers } from "../ws-bridge.ts";
 import { bootSupervisedModules } from "./serve-boot.ts";
 
 /**
@@ -217,12 +218,30 @@ function parsePort(raw: string | undefined): number | undefined {
  * remaining gap (rebuild the live spawn-env on `supervisor.restart` so the
  * first exposure propagates to already-running children without a manual
  * restart) is the deferred #532 follow-up; not implemented in this PR.
+ *
+ * DB ORIGIN, highest precedence (onboarding-streamline 2026-06-25, Caddy-direct
+ * zero-SSH path): the operator-set `hub_settings.hub_origin` is the tier-1 layer
+ * in the per-request `resolveIssuer` (hub-server.ts). The boot path MUST honor
+ * it too — otherwise a Caddy-fronted box whose ONLY canonical-origin source is
+ * the DB row (no `PARACHUTE_HUB_ORIGIN` env, no expose-state, no platform var)
+ * boots `serve` with no issuer, injects only loopback aliases into supervised
+ * children's `PARACHUTE_HUB_ORIGINS`, and vault/scribe then reject every token
+ * the hub mints under the public origin (which per-request `resolveIssuer` DOES
+ * stamp from the DB). Threading the DB origin in as the top input keeps the
+ * boot-time seed in lockstep with `resolveIssuer`'s tier-1. `serve()` reads the
+ * row off the opened hub DB and passes it as `dbHubOrigin`; tests pass it
+ * directly. It is sanitized like any other public-origin input (a stray
+ * loopback / non-http(s) DB value never pins the issuer).
  */
 export function resolveStartupIssuer(
-  opts: { issuer?: string },
+  opts: { issuer?: string; dbHubOrigin?: string },
   env: NodeJS.ProcessEnv,
   readExpose: () => string | undefined = defaultReadExposeHubOrigin,
 ): string | undefined {
+  // DB row first — mirrors `resolveIssuer`'s tier-1 (hub_settings.hub_origin).
+  // Sanitized so a stray loopback / non-http(s) value never pins the issuer.
+  const dbOrigin = sanitizePublicOrigin(opts.dbHubOrigin);
+  if (dbOrigin) return dbOrigin;
   const flyOrigin = flyDefaultOriginFromEnv(env);
   const explicit = (
     opts.issuer ??
@@ -435,7 +454,6 @@ export async function serve(opts: ServeOpts = {}): Promise<{
 
   const envPort = parsePort(env.PORT);
   const port = opts.port ?? envPort ?? DEFAULT_PORT;
-  const issuer = resolveStartupIssuer(opts, env);
   // Containers default to 0.0.0.0 so the platform's HTTP forwarder can
   // reach us; the `--hostname` flag / PARACHUTE_BIND_HOST is the escape
   // hatch for setups that want loopback-only inside a sidecar.
@@ -461,6 +479,24 @@ export async function serve(opts: ServeOpts = {}): Promise<{
   const dbPath = hubDbPath();
   // Self-heal-or-die DB holder (#594) + proactive ghost-fd watchdog (#610/#619).
   const { dbHolder, livenessTimer } = armServeDbWatchdog(dbPath, { log });
+  // Resolve the boot-time issuer AFTER the DB is open so the operator-set
+  // `hub_settings.hub_origin` (tier-1 in `resolveIssuer`) seeds the value the
+  // hub mints with AND the `PARACHUTE_HUB_ORIGINS` set injected into supervised
+  // children. This is what makes a Caddy-fronted, zero-SSH box (whose only
+  // canonical-origin source is the DB row) inject the public origin into
+  // vault/scribe so they accept hub-minted tokens. Pass it as `dbHubOrigin`;
+  // a malformed read can't crash startup — `getHubOrigin` is a plain SELECT
+  // and `resolveStartupIssuer` sanitizes the value.
+  let dbHubOrigin: string | undefined;
+  try {
+    dbHubOrigin = getHubOrigin(dbHolder.get()) ?? undefined;
+  } catch {
+    dbHubOrigin = undefined;
+  }
+  const issuer = resolveStartupIssuer(
+    { ...opts, ...(dbHubOrigin !== undefined ? { dbHubOrigin } : {}) },
+    env,
+  );
   const adminBootstrap = await seedInitialAdminIfNeeded(dbHolder.get(), env, log);
 
   if (adminBootstrap === "needs-setup") {

package/src/commands/setup.ts

@@ -11,6 +11,7 @@ import {
   KNOWN_MODULES,
   type ServiceSpec,
   composeServiceSpec,
+  focusForShort,
   knownServices,
 } from "../service-spec.ts";
 import type { ServiceEntry } from "../services-manifest.ts";
@@ -108,10 +109,14 @@ function defaultAvailability(): InteractiveAvailability {
 }
 
 /**
- * Survey the eligible services. We include the four first-party shortnames
- * (vault / notes / scribe / agent + runner) but flag agent as exploratory
- * in the blurb so operators don't grab it by reflex. `installed` is true when
- * the service has a row in services.json.
+ * Survey ALL known first-party shortnames (vault / notes / scribe / agent /
+ * runner / surface) regardless of tier — `installed` is true when the service
+ * has a row in services.json. The fresh-install OFFER is narrowed downstream
+ * by `isOfferable` (drops already-installed + `deprecated`-tier shorts —
+ * notes / runner); agent (`experimental`) is flagged exploratory in its blurb
+ * but stays offered. Surveying everything keeps `installed` detection complete
+ * (the "already installed" banner still lists a deprecated module an operator
+ * has on disk).
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
  * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
@@ -149,10 +154,30 @@ function surveyServices(manifestPath: string): ServiceChoice[] {
   });
 }
 
+/**
+ * A surveyed service is OFFERED on a fresh setup iff it is not already
+ * installed AND its discovery tier is not `deprecated` (2026-06-25). The
+ * deprecated tier (notes-daemon, runner) stays resolvable + manageable for an
+ * existing install — it just isn't pushed on a fresh box. `agent`
+ * (`experimental`) is still offered. Exported so the setup tests can pin the
+ * exclusion directly.
+ */
+export function isOfferable(choice: { short: string; installed: boolean }): boolean {
+  if (choice.installed) return false;
+  // No `declared` arg: the survey fires PRE-install, before any module.json is
+  // on disk to read a self-declared `focus` from — so the static default map is
+  // the only signal available + the right one here.
+  return focusForShort(choice.short) !== "deprecated";
+}
+
 const BLURBS: Record<string, string> = {
   vault: "knowledge graph (MCP) — your owner-authenticated note + tag store",
+  surface: "Parachute UI host — auto-installs Notes on first boot (the recommended UI path)",
+  // `app` is the pre-2026-05-27 name for `surface`; kept for any legacy survey row.
   app: "Parachute UI host — auto-installs Notes on first boot (recommended over notes-daemon)",
-  notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `app`)",
+  // notes / runner are `deprecated` (not offered on a fresh setup) — these
+  // blurbs only render if a legacy install surfaces them in the survey.
+  notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `surface`)",
   scribe: "audio transcription for dictation + recordings",
   runner: "vault-as-job-substrate — scheduled claude -p against vault job notes",
   agent:
@@ -306,7 +331,7 @@ export async function setup(opts: SetupOpts = {}): Promise<number> {
 
   const survey = surveyServices(manifestPath);
   const installed = survey.filter((s) => s.installed);
-  const offered = survey.filter((s) => !s.installed);
+  const offered = survey.filter(isOfferable);
 
   if (installed.length > 0) {
     log("Already installed:");

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/help.ts

@@ -28,6 +28,8 @@ Usage:
   parachute migrate --to-supervised move a legacy detached install to the managed hub
   parachute migrate [--dry-run]     archive legacy files at ecosystem root
   parachute auth <cmd>              identity (set password, manage 2FA)
+  parachute hub set-origin <url>    set the canonical public hub origin (OAuth issuer)
+                                    — for reverse-proxy / Caddy-direct boxes
   parachute vault <args...>         vault-specific ops (tokens, 2fa, config, init,
                                     etc.) — forwards to parachute-vault.
                                     For lifecycle, use \`parachute start|stop|restart|logs vault\`.
@@ -130,6 +132,7 @@ export function initHelp(): string {
 Usage:
   parachute init [--no-browser] [--no-expose-prompt]
                  [--expose none|tailnet|cloudflare]
+                 [--hub-origin <url>]
                  [--cli-wizard | --browser-wizard]
 
 What it does:
@@ -165,6 +168,11 @@ Flags:
                               none       — stay loopback-only
                               tailnet    — set up Tailscale serve (private to your tailnet)
                               cloudflare — set up Cloudflare Tunnel (your own domain)
+  --hub-origin <url>        set the canonical public origin (OAuth issuer) BEFORE
+                            the hub + modules start, so vault/scribe come up
+                            accepting it in one pass. For reverse-proxy /
+                            Caddy-direct boxes that bind loopback but are reached
+                            over a public HTTPS URL (e.g. https://<ip>.sslip.io).
   --cli-wizard              skip the "browser or CLI?" prompt and walk the wizard
                             in this terminal (hub#168 Cut 4)
   --browser-wizard          skip the prompt and open the browser wizard directly