@openparachute/hub 0.5.13 → 0.5.14-rc.10

package/src/setup-wizard.ts

@@ -38,21 +38,24 @@
  */
 
 import type { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { type OperationsRegistry, runInstall, specFor } from "./api-modules-ops.ts";
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
-import { brandMarkSvg, WORDMARK_TEXT } from "./brand.ts";
 import {
   BOOTSTRAP_TOKEN_PREFIX,
   consumeBootstrapToken,
   getBootstrapToken,
   verifyBootstrapToken,
 } from "./bootstrap-token.ts";
+import { WORDMARK_TEXT, brandMarkSvg } from "./brand.ts";
 import {
   CSRF_FIELD_NAME,
   ensureCsrfToken,
   renderCsrfHiddenInput,
   verifyCsrfToken,
 } from "./csrf.ts";
+import { type ExposeState, readExposeState } from "./expose-state.ts";
 import {
   SETUP_EXPOSE_MODES,
   type SetupExposeMode,
@@ -62,6 +65,7 @@ import {
   openFirstClientAutoApproveWindow,
   setSetting,
 } from "./hub-settings.ts";
+import { signAccessToken } from "./jwt-sign.ts";
 import { escapeHtml } from "./oauth-ui.ts";
 import { mintOperatorToken } from "./operator-token.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
@@ -104,6 +108,71 @@ function escapeAttr(s: string): string {
   return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }
 
+/**
+ * The CLI wizard (hub#168 Cut 3) sends `Accept: application/json` on
+ * every GET; the browser sends `Accept: text/html, …`. We branch the GET
+ * handler's response shape on this header. Same DB / state-derivation
+ * path both ways — only the rendering forks.
+ *
+ * POSTs from the CLI wizard send `Content-Type: application/json`;
+ * browser POSTs send `application/x-www-form-urlencoded`. The POST
+ * handlers parse-into-the-same-shape with `readBodyFields` below.
+ */
+function wantsJsonResponse(req: Request): boolean {
+  const accept = req.headers.get("accept") ?? "";
+  return accept.includes("application/json");
+}
+
+/**
+ * Best-effort body parser shared by every wizard POST handler. Branches
+ * on Content-Type:
+ *   * `application/json` → parses the body as JSON, projects each
+ *     top-level field into a `Map<string, string>` (matches the
+ *     FormData getter shape the rest of the handlers use).
+ *   * Anything else → standard `req.formData()` (the historical browser
+ *     path).
+ *
+ * Returns a tuple of `[fields, isJson]`. `isJson` lets the handler
+ * decide between a 303 redirect (browser) and a 200 JSON envelope
+ * (CLI). The fields-getter API is intentionally lossy on JSON arrays /
+ * nested objects — every wizard field today is a plain string, so the
+ * Map<string, string> shape is sufficient. If we ever need arrays here,
+ * extend with a `getAll(name)` shim.
+ */
+async function readBodyFields(req: Request): Promise<{
+  get: (name: string) => string | null;
+  isJson: boolean;
+}> {
+  const contentType = req.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    let parsed: Record<string, unknown> = {};
+    try {
+      parsed = (await req.json()) as Record<string, unknown>;
+    } catch {
+      // Malformed JSON falls through to an empty map — the handlers'
+      // existing field-validation surfaces the right error message.
+      parsed = {};
+    }
+    return {
+      isJson: true,
+      get: (name: string) => {
+        const v = parsed[name];
+        if (typeof v === "string") return v;
+        if (typeof v === "number" || typeof v === "boolean") return String(v);
+        return null;
+      },
+    };
+  }
+  const form = await req.formData();
+  return {
+    isJson: false,
+    get: (name: string) => {
+      const v = form.get(name);
+      return typeof v === "string" ? v : null;
+    },
+  };
+}
+
 // --- state derivation ----------------------------------------------------
 
 /**
@@ -139,13 +208,41 @@ export interface DerivedWizardState {
  */
 export const FIRST_VAULT_SHORT: CuratedModuleShort = "vault";
 
+/**
+ * Map a live exposure layer (`expose-state.json`) onto the wizard's
+ * `setup_expose_mode`. The two enums overlap exactly on the layers the
+ * exposure file can carry: `ExposeLayer` is `tailnet | public`, both of
+ * which are valid `SetupExposeMode` values. (There's no `localhost`
+ * exposure layer — running nothing is the absence of a state file, which
+ * `readExposeState` reports as `undefined`, so a missing/unexposed hub
+ * never seeds and the wizard still asks.)
+ *
+ * Returns `undefined` when no exposure is live (or the reader throws on
+ * a malformed file — we swallow that and fall through to "still ask"
+ * rather than crashing the wizard GET).
+ */
+function exposeModeFromLiveState(read: () => ExposeState | undefined): SetupExposeMode | undefined {
+  let state: ExposeState | undefined;
+  try {
+    state = read();
+  } catch {
+    // A corrupt expose-state.json shouldn't brick the wizard. Treat it
+    // as "no live exposure" and let the operator answer the step.
+    return undefined;
+  }
+  if (!state) return undefined;
+  // `ExposeLayer` ⊆ `SetupExposeMode` ("tailnet" | "public").
+  return state.layer;
+}
+
 /**
  * Read DB + services.json to decide which step the wizard should render.
  * Idempotent — re-running after partial setup picks up where it left
  * off. Mostly read-only, with one specific write: on Render (or any
- * platform `detectAutoExposeMode` recognizes), the first call auto-
- * seeds `setup_expose_mode = "public"` so the wizard skips the expose
- * step. Subsequent calls find the setting present and are read-only.
+ * platform `detectAutoExposeMode` recognizes), OR when a live tailscale
+ * exposure (`expose-state.json`) is already up, the first call auto-
+ * seeds `setup_expose_mode` so the wizard skips the expose step.
+ * Subsequent calls find the setting present and are read-only.
  */
 export function deriveWizardState(deps: {
   db: Database;
@@ -156,13 +253,28 @@ export function deriveWizardState(deps: {
    * SetupWizardDeps.env.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Optional injected reader for the live exposure state
+   * (`~/.parachute/expose-state.json`). Defaults to the real
+   * `readExposeState`. Mirrors the `init.ts` seam (`readExposeStateFn`)
+   * so tests can drive the "a tailnet layer is already live" branch
+   * without writing a real state file. When `setup_expose_mode` is
+   * unset, the live exposure layer auto-seeds the setting (see below).
+   */
+  readExposeStateFn?: () => ExposeState | undefined;
 }): DerivedWizardState {
   const hasAdmin = userCount(deps.db) > 0;
   // The wizard's first-vault provisioning uses the curated `vault` short,
   // which maps to `parachute-vault` in services.json.
   const vaultSpec = specFor(FIRST_VAULT_SHORT);
   const vaultEntry = findService(vaultSpec.manifestName, deps.manifestPath);
-  const hasVault = vaultEntry !== undefined;
+  // hub#168 Cut 2: `setup_vault_skipped === "true"` advances the wizard
+  // past the vault step even when no vault row exists. The operator
+  // explicitly chose Skip; the module is installed (Cut 1) but no
+  // instance was provisioned. Treat as "vault step is done" for the
+  // purposes of state-derivation so the wizard moves to expose.
+  const vaultSkipped = getSetting(deps.db, "setup_vault_skipped") === "true";
+  const hasVault = vaultEntry !== undefined || vaultSkipped;
   // Expose-mode is the operator's "how will this hub be reached?" answer
   // (hub#268 Item 2). Stored as a hub_setting; the wizard's expose step
   // sets it; absence means we should still ask. EXCEPT — if we're
@@ -178,6 +290,23 @@ export function deriveWizardState(deps: {
   ) {
     setSetting(deps.db, "setup_expose_mode", "public");
   }
+  // hub#406 team-onboarding bug: `setup_expose_mode` (the wizard's
+  // answer) and `expose-state.json` (the live tailscale exposure) are
+  // orthogonal axes. An operator who ran `parachute expose tailnet`
+  // before opening the wizard has a live tailnet layer but no
+  // `setup_expose_mode` setting — so the wizard re-asked "how will this
+  // hub be reached?" even though tailnet was already up. Auto-seed the
+  // setting from the live exposure layer (tailnet→"tailnet",
+  // public→"public") so the answered-by-action case is treated as
+  // satisfied, mirroring the Render/Fly auto-seed above. Reading the
+  // live state is injected for testability (defaults to the real
+  // reader); a malformed/missing file falls through to "still ask."
+  if (getSetting(deps.db, "setup_expose_mode") === undefined) {
+    const seeded = exposeModeFromLiveState(deps.readExposeStateFn ?? readExposeState);
+    if (seeded !== undefined) {
+      setSetting(deps.db, "setup_expose_mode", seeded);
+    }
+  }
   const hasExposeMode = getSetting(deps.db, "setup_expose_mode") !== undefined;
   let step: WizardStep;
   // Note: `"account"` is a visual-only step in the progress header —
@@ -221,6 +350,18 @@ export interface SetupWizardDeps {
   registry?: OperationsRegistry;
   /** Test seam: stub `bun add` / `bun remove` runner. */
   run?: (cmd: readonly string[]) => Promise<number>;
+  /**
+   * Test seam: stub the bun-link detection used by `runInstall` to
+   * short-circuit `bun add -g` when a package is already linked
+   * locally (smoke 2026-05-27 finding 1). Production omits this and
+   * the production detection at `src/bun-link.ts` probes the real
+   * filesystem. Tests that need to assert "bun add -g WAS called"
+   * pass `() => false`; tests asserting the skip path pass `() => true`.
+   *
+   * Threaded through to `ApiModulesOpsDeps.isLinked` on every
+   * `runInstall` call from the wizard.
+   */
+  isLinked?: (pkg: string) => boolean;
   /**
    * Test seam: override the process env that `detectAutoExposeMode`
    * consults. Production omits this and the helper reads `process.env`
@@ -228,6 +369,14 @@ export interface SetupWizardDeps {
    * without mutating the real process env.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Test seam: inject the live-exposure reader `deriveWizardState`
+   * consults to auto-seed `setup_expose_mode` from a live
+   * `parachute expose tailnet|public` (hub#406). Production omits this
+   * and the real `readExposeState` is used. Mirrors `init.ts`'s
+   * `readExposeStateFn` seam.
+   */
+  readExposeStateFn?: () => ExposeState | undefined;
 }
 
 /**
@@ -247,7 +396,9 @@ export interface SetupWizardDeps {
  * (RAILWAY_ENVIRONMENT), DigitalOcean App Platform (DIGITALOCEAN_APP_*),
  * etc. Each only auto-detects when the platform clearly owns the public URL.
  */
-export function detectAutoExposeMode(env: Record<string, string | undefined>): "public" | undefined {
+export function detectAutoExposeMode(
+  env: Record<string, string | undefined>,
+): "public" | undefined {
   // Render always sets `RENDER_EXTERNAL_URL` to a real `https://` URL on
   // any web service. `startsWith("https://")` is the precise shape; we
   // also accept `http://` as a defensive fallback in case Render ever
@@ -449,6 +600,14 @@ export interface RenderVaultStepProps {
   errorMessage?: string;
   /** Pre-fill the vault name input after a validation failure. */
   vaultName?: string;
+  /**
+   * When the runtime is a hosted container (Render / Fly), the scribe
+   * sub-form hides the "local provider" option — Whisper / parakeet
+   * don't run usefully in the constrained container. Defaults to false
+   * (treat as self-host, show local option) — production wizard renders
+   * always pass an explicit value via detectAutoExposeMode.
+   */
+  cloudHost?: boolean;
   /**
    * When an install op is in progress, render the polling shape: no
    * form, just the op log + auto-refresh.
@@ -458,13 +617,28 @@ export interface RenderVaultStepProps {
     status: "pending" | "running" | "succeeded" | "failed";
     log: readonly string[];
     error?: string;
+    /**
+     * Optional scribe install op_id, threaded through so the success
+     * redirect carries `&op_scribe=<id>` and the done step picks up the
+     * in-flight scribe install via the existing per-tile op-poll
+     * mechanism (`buildInstallTiles` reads `op_<short>` query param).
+     */
+    scribeOpId?: string;
   };
 }
 
 export function renderVaultStep(props: RenderVaultStepProps): string {
-  const { csrfToken, errorMessage, operation, vaultName } = props;
+  const { csrfToken, errorMessage, operation, vaultName, cloudHost } = props;
   if (operation) return renderVaultOpStep({ operation });
   const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
+  // hub#168 Cut 2: three-branch vault step. The browser form now sends
+  // `mode=create|import|skip` along with the existing vault_name. Defaults
+  // to create when nothing's selected (back-compat with pre-#168 form
+  // posts that didn't ship a mode field — still works through the same
+  // handler). The radio's `data-shows` attribute drives an inline
+  // <script> block that hides import-specific fields when create/skip
+  // is selected. No SPA bundle, no module deps — same posture as the
+  // existing scribe sub-form's mode-switching JS.
   // hub#267: the typed name now flows end-to-end via
   // `PARACHUTE_VAULT_NAME`. Vault#342 added the env var read on
   // first-boot — hub spawns vault with the env var set and vault's
@@ -513,7 +687,25 @@ export function renderVaultStep(props: RenderVaultStepProps): string {
       ${error}
       <form method="POST" action="/admin/setup/vault" class="auth-form">
         ${renderCsrfHiddenInput(csrfToken)}
-        <label class="field">
+        <fieldset class="vault-mode-block">
+          <legend class="field-label">How do you want to start?</legend>
+          <label class="vault-mode-option">
+            <input type="radio" name="mode" value="create" checked data-shows="name" />
+            <span class="vault-mode-title">Create a new vault</span>
+            <span class="vault-mode-desc">Start fresh. The wizard creates an empty vault under the name below.</span>
+          </label>
+          <label class="vault-mode-option">
+            <input type="radio" name="mode" value="import" data-shows="name,import" />
+            <span class="vault-mode-title">Import from a git repo</span>
+            <span class="vault-mode-desc">Clone a previously-exported vault from GitHub / GitLab / any HTTPS git remote.</span>
+          </label>
+          <label class="vault-mode-option">
+            <input type="radio" name="mode" value="skip" data-shows="" />
+            <span class="vault-mode-title">Skip — create a vault later</span>
+            <span class="vault-mode-desc">The vault module is installed; create or import a vault any time from the admin UI.</span>
+          </label>
+        </fieldset>
+        <label class="field vault-name-field">
           <span class="field-label">Vault name</span>
           <input type="text" name="vault_name"
             autofocus minlength="2" maxlength="32"
@@ -523,12 +715,201 @@ export function renderVaultStep(props: RenderVaultStepProps): string {
           <span class="field-hint">lowercase letters, digits, <code>-</code>, <code>_</code>;
             2–32 chars. Leave blank for <code>${DEFAULT_VAULT_NAME}</code>.</span>
         </label>
-        <button type="submit" class="btn btn-primary">Create vault & finish</button>
+        <fieldset class="vault-import-block" style="display: none;">
+          <legend class="field-label">Import source</legend>
+          <label class="field">
+            <span class="field-label">Remote URL</span>
+            <input type="text" name="remote_url" spellcheck="false" autocomplete="off"
+              placeholder="https://github.com/you/your-vault.git" />
+            <span class="field-hint">HTTPS or SSH clone URL. The repo must be a Parachute vault export — i.e. it carries a <code>.parachute/vault.yaml</code> at the root.</span>
+          </label>
+          <label class="field">
+            <span class="field-label">Personal access token (optional)</span>
+            <input type="password" name="pat" autocomplete="off"
+              placeholder="ghp_… / glpat-… / etc." />
+            <span class="field-hint">Required for private repos. Used in-memory for this import only — not stored. Set up push credentials later from the vault's mirror settings.</span>
+          </label>
+          <label class="vault-mode-option">
+            <input type="radio" name="import_mode" value="merge" checked />
+            <span class="vault-mode-title">Merge into a fresh vault (default)</span>
+            <span class="vault-mode-desc">Recommended on a brand-new install — the vault starts empty, so merge is effectively "import everything."</span>
+          </label>
+          <label class="vault-mode-option">
+            <input type="radio" name="import_mode" value="replace" />
+            <span class="vault-mode-title">Replace (wipes any existing notes first)</span>
+            <span class="vault-mode-desc">Only useful if you re-ran the wizard on an existing vault. Otherwise picks the same shape as merge.</span>
+          </label>
+        </fieldset>
+        ${renderScribeSubForm(cloudHost === true)}
+        <button type="submit" class="btn btn-primary">Continue</button>
       </form>
+      <script>
+        (function () {
+          // Show/hide vault-name + import block based on the picked mode.
+          // The radio carries data-shows listing the visible block suffixes
+          // (name, import); the show/hide loop reads them and flips display
+          // on the matching block. Skip mode hides everything below the
+          // mode picker.
+          var radios = document.querySelectorAll('input[name="mode"]');
+          var nameField = document.querySelector('.vault-name-field');
+          var importBlock = document.querySelector('.vault-import-block');
+          function sync() {
+            var picked = document.querySelector('input[name="mode"]:checked');
+            var shows = picked ? (picked.dataset.shows || '') : '';
+            var nameVisible = shows.indexOf('name') !== -1;
+            var importVisible = shows.indexOf('import') !== -1;
+            if (nameField) nameField.style.display = nameVisible ? '' : 'none';
+            if (importBlock) importBlock.style.display = importVisible ? '' : 'none';
+          }
+          radios.forEach(function (r) { r.addEventListener('change', sync); });
+          sync();
+        })();
+      </script>
     </div>`;
   return baseDocument("Set up your Parachute hub — vault", body);
 }
 
+/**
+ * Scribe install sub-form embedded in the vault step (folded in
+ * 2026-05-27 per Aaron's team-meeting directive: "folding the scribe
+ * question into the vault step is a good idea"). Operator answers
+ * scribe-related questions in the same form as vault name, the POST
+ * handler kicks both installs in parallel, and the done screen polls
+ * scribe's progress via the existing per-tile op-poll mechanism.
+ *
+ * The provider list adapts to the runtime context:
+ *   - Cloud container (Render / Fly): local transcribers (parakeet,
+ *     whisper) don't fit in 512MB + can't reach hardware acceleration.
+ *     We hide them. Groq is the default (fast cloud Whisper, ~$0.04/hr
+ *     of audio); OpenAI is the alternative.
+ *   - Local (Mac / Linux): parakeet-mlx is the default on Mac (silicon
+ *     MLX); falls back to onnx-asr cross-platform. Cloud providers
+ *     stay available as choices for operators who'd rather pay than
+ *     run local inference.
+ *
+ * The API key input shows conditionally — only when a cloud provider
+ * is selected. It's a plain text input (no `type=password`) because
+ * (a) the operator just pasted it from their provider's dashboard, and
+ * (b) showing it lets them verify they pasted correctly before submit.
+ * Mode-switching between providers via the radio is handled by an
+ * inline `<script>` block — no SPA bundle, no module deps.
+ *
+ * The "Skip — no transcription" option is third and unchecked by
+ * default. Most operators want voice transcription once they know
+ * they can; the default-on posture matches the auto-transcribe default
+ * flip that landed in vault#373.
+ */
+function renderScribeSubForm(cloudHost: boolean): string {
+  const localBlock = cloudHost
+    ? ""
+    : `
+        <label class="scribe-provider-option">
+          <input type="radio" name="scribe_provider" value="local"${cloudHost ? "" : " checked"} data-needs-key="false" />
+          <span class="provider-name">Local <small>(Mac MLX or ONNX — no API key needed)</small></span>
+        </label>`;
+  const groqDefault = cloudHost ? " checked" : "";
+  // Cleanup providers that need a host-side binary or local server
+  // (claude-code → `claude` CLI + `claude setup-token`; ollama → local
+  // Ollama server) are hidden on cloud hosts (Render / Fly). The
+  // remaining cloud-friendly choices (anthropic / openai / groq /
+  // gemini) stay visible — they only need an API key.
+  const claudeCodeCleanupBlock = cloudHost
+    ? ""
+    : `
+              <label class="scribe-provider-option">
+                <input type="radio" name="scribe_cleanup_provider" value="claude-code" data-needs-key="false" />
+                <span class="provider-name">Claude Code <small>(subscription auth — run <code>claude setup-token</code> on this host)</small></span>
+              </label>`;
+  const ollamaCleanupBlock = cloudHost
+    ? ""
+    : `
+              <label class="scribe-provider-option">
+                <input type="radio" name="scribe_cleanup_provider" value="ollama" data-needs-key="false" />
+                <span class="provider-name">Ollama <small>(local LLM — requires Ollama running on this machine)</small></span>
+              </label>`;
+  return `
+        <details class="scribe-suboptions" open>
+          <summary class="cursor-pointer">
+            <span class="field-label">Enable voice transcription</span>
+            <span class="field-hint"> · Scribe installs alongside vault, transcribes audio attachments automatically</span>
+          </summary>
+          <div class="scribe-provider-block">
+            <p class="field-hint">Pick a transcription provider. You can change this later in <code>/admin/modules</code>.</p>
+            <div class="scribe-provider-list">
+              ${localBlock}
+              <label class="scribe-provider-option">
+                <input type="radio" name="scribe_provider" value="groq"${groqDefault} data-needs-key="true" />
+                <span class="provider-name">Groq <small>(~\$0.04/hr of audio, fast)</small></span>
+              </label>
+              <label class="scribe-provider-option">
+                <input type="radio" name="scribe_provider" value="openai" data-needs-key="true" />
+                <span class="provider-name">OpenAI Whisper <small>(~\$0.36/hr of audio)</small></span>
+              </label>
+              <label class="scribe-provider-option">
+                <input type="radio" name="scribe_provider" value="none" data-needs-key="false" />
+                <span class="provider-name">Skip — no transcription</span>
+              </label>
+            </div>
+            <label class="field scribe-api-key-field" data-shows-on="cloud">
+              <span class="field-label">API key</span>
+              <input type="password" name="scribe_api_key" autocomplete="off" placeholder="gsk_… or sk-…" />
+              <span class="field-hint">Pasted directly into <code>~/.parachute/scribe/config.json</code> on this hub (file mode 0o600). Leave blank to skip and set later in the admin SPA.</span>
+            </label>
+            <fieldset class="scribe-cleanup-block">
+              <legend class="field-label">Cleanup <small>(optional LLM polish pass on transcripts)</small></legend>
+              <p class="field-hint">After transcription, scribe can run a cleanup pass to fix punctuation, capitalization, and obvious transcription glitches. Pick a provider, or skip.</p>
+              <div class="scribe-provider-list">
+                <label class="scribe-provider-option">
+                  <input type="radio" name="scribe_cleanup_provider" value="none" checked data-needs-key="false" />
+                  <span class="provider-name">Skip cleanup <small>(default — raw transcripts only)</small></span>
+                </label>
+                ${claudeCodeCleanupBlock}
+                <label class="scribe-provider-option">
+                  <input type="radio" name="scribe_cleanup_provider" value="anthropic" data-needs-key="true" />
+                  <span class="provider-name">Anthropic API <small>(needs ANTHROPIC_API_KEY)</small></span>
+                </label>
+                ${ollamaCleanupBlock}
+                <label class="scribe-provider-option">
+                  <input type="radio" name="scribe_cleanup_provider" value="openai" data-needs-key="true" />
+                  <span class="provider-name">OpenAI <small>(needs OPENAI_API_KEY)</small></span>
+                </label>
+                <label class="scribe-provider-option">
+                  <input type="radio" name="scribe_cleanup_provider" value="groq" data-needs-key="true" />
+                  <span class="provider-name">Groq <small>(needs GROQ_API_KEY)</small></span>
+                </label>
+                <label class="scribe-provider-option">
+                  <input type="radio" name="scribe_cleanup_provider" value="gemini" data-needs-key="true" />
+                  <span class="provider-name">Google Gemini <small>(needs GOOGLE_API_KEY)</small></span>
+                </label>
+              </div>
+              <label class="field scribe-cleanup-api-key-field" style="display: none;">
+                <span class="field-label">Cleanup API key</span>
+                <input type="password" name="scribe_cleanup_api_key" autocomplete="off" placeholder="sk-ant-… or sk-… or gsk-…" />
+                <span class="field-hint">Pasted directly into <code>~/.parachute/scribe/config.json</code> on this hub (file mode 0o600). Leave blank to skip and paste later in the admin SPA.</span>
+              </label>
+            </fieldset>
+          </div>
+        </details>
+        <script>
+          (function () {
+            function toggle(radioName, keySelector) {
+              var radios = document.querySelectorAll('input[name="' + radioName + '"]');
+              var keyField = document.querySelector(keySelector);
+              function sync() {
+                var selected = document.querySelector('input[name="' + radioName + '"]:checked');
+                var needsKey = selected && selected.dataset.needsKey === "true";
+                if (keyField) keyField.style.display = needsKey ? "" : "none";
+              }
+              radios.forEach(function (r) { r.addEventListener("change", sync); });
+              sync();
+            }
+            toggle("scribe_provider", ".scribe-api-key-field");
+            toggle("scribe_cleanup_provider", ".scribe-cleanup-api-key-field");
+          })();
+        </script>
+  `;
+}
+
 function renderVaultOpStep(props: {
   operation: NonNullable<RenderVaultStepProps["operation"]>;
 }): string {
@@ -567,7 +948,7 @@ function renderVaultOpStep(props: {
       </section>
       ${
         operation.status === "succeeded"
-          ? '<meta http-equiv="refresh" content="1; url=/admin/setup?just_finished=1" />'
+          ? `<meta http-equiv="refresh" content="1; url=/admin/setup?just_finished=1${operation.scribeOpId ? `&op_scribe=${encodeURIComponent(operation.scribeOpId)}` : ""}" />`
           : ""
       }
     </div>`;
@@ -718,27 +1099,15 @@ export interface RenderDoneStepProps {
    * shape.
    */
   installTiles?: readonly ModuleInstallTileState[];
-  /**
-   * Whether parachute-app is installed alongside the vault. Drives the
-   * "Start using your vault" lead tile (hub#342): when true, the tile
-   * links to `/app/notes/` (the canonical user-facing surface — App
-   * auto-bootstraps Notes-as-UI per the 2026-05-21 migration). When
-   * false, it falls back to the vault's own admin UI at
-   * `/vault/<name>/admin/` so the operator still has a single obvious
-   * "start using parachute" target. Omitted = back-compat with tests
-   * that render the done step without dependency-checking; defaults to
-   * false (vault-admin fallback).
-   */
-  appInstalled?: boolean;
 }
 
 export function renderDoneStep(props: RenderDoneStepProps): string {
-  const { vaultName, hubOrigin, exposeMode, mintedToken, installTiles, appInstalled } = props;
+  const { vaultName, hubOrigin, exposeMode, mintedToken, installTiles } = props;
   const reachable = exposeMode ? renderReachableTile(exposeMode, hubOrigin) : "";
   const mcpTile = renderMcpTile(vaultName, hubOrigin, mintedToken);
   const tiles = installTiles && installTiles.length > 0 ? installTiles : [];
   const installSection = tiles.length > 0 ? renderInstallTiles(tiles) : "";
-  const startTile = renderStartUsingTile(vaultName, appInstalled === true);
+  const startTile = renderStartUsingTile(vaultName, hubOrigin);
   // The done-grid hosts the MCP-connect tile + the admin-UI fallback.
   // The install tiles sit above it as a "what's next?" surface (curated
   // catalog of modules an operator might want next). The "Start using
@@ -762,6 +1131,7 @@ export function renderDoneStep(props: RenderDoneStepProps): string {
       </div>
       ${reachable}
       ${startTile}
+      ${renderStarterPromptsSection()}
       ${installSection}
       <section class="done-grid">
         ${mcpTile}
@@ -925,14 +1295,18 @@ function renderMcpTile(
     <h2>Connect Claude Code (MCP)</h2>
     <p>Wire <code>vault:${safeVault}</code> into Claude Code as an MCP server:</p>
     <pre>${escapeHtml(bareCmd)}</pre>
-    <p class="fine">Mint an operator token at
-      <a href="/admin/tokens"><code>/admin/tokens</code></a> and append
-      <code>--header "Authorization: Bearer pvt_..."</code> on first use.</p>
+    <p class="fine">No token needed — the command triggers browser OAuth on
+      first use (you sign in to this hub and approve access). For headless
+      clients that can't do the browser flow, mint a hub token at
+      <a href="/admin/tokens"><code>/admin/tokens</code></a> (or with
+      <code>parachute auth mint-token</code>) and append
+      <code>--header "Authorization: Bearer &lt;token&gt;"</code>.</p>
   </div>`;
 }
 
 /**
- * The "Start using your vault" lead tile on the done step (hub#342).
+ * The "Start using your vault" lead tile on the done step (hub#342,
+ * Aaron 2026-05-27 simplification).
  *
  * Closes Aaron's "no clear way to go from setting up parachute to
  * actually using parachute" friction. Sits above the MCP / install
@@ -940,39 +1314,72 @@ function renderMcpTile(
  * everything else on the done screen is operator-flavored (MCP
  * command, admin UI, additional module installs).
  *
- * Two shapes:
- *   - **App installed** → primary tile targets `/app/notes/` (the
- *     Notes app reading the just-created vault). This is the
- *     canonical surface post-Notes-as-app migration (parachute-app §17).
- *   - **App NOT installed** → primary tile targets the vault's own
- *     admin UI at `/vault/<name>/admin/`. The copy explains that
- *     installing App + Notes is the recommended next step for a
- *     content-browsing surface, and points at the install tile below.
+ * Points at the canonical notes.parachute.computer hosted PWA as the
+ * primary CTA — with the operator's own hub URL pre-filled via
+ * `?url=` so the connect screen auto-populates + auto-focuses
+ * (notes-ui AddVault route, see
+ * parachute-surface/packages/notes-ui/src/app/routes/AddVault.tsx).
+ * Secondary CTA: "Open vault admin" (the vault's own admin UI on this
+ * hub) for operators who want to look at raw vault state.
  *
- * Either way, the operator has ONE obvious click target that says
- * "start using parachute" — not three competing tiles where the
- * "real" entry point is buried under the MCP command pre-hub#342.
+ * Previously varied by whether `parachute-surface` was installed
+ * locally — pointing at `/surface/notes/` in that case. Dropped
+ * 2026-05-27: hub+vault+scribe is the focus; notes.parachute.computer
+ * is canonical regardless of local surface install state.
  */
-function renderStartUsingTile(vaultName: string, appInstalled: boolean): string {
+function renderStartUsingTile(vaultName: string, hubOrigin: string): string {
   const safeVault = escapeHtml(vaultName);
   // Vault names pass `/^[a-z0-9][a-z0-9-]*$/i` so URL-encoding is mostly
   // a no-op today, but use encodeURIComponent defensively to match hub.ts:505.
   const urlVault = encodeURIComponent(vaultName);
-  if (appInstalled) {
-    return `<section class="start-using" data-testid="start-using-tile">
-      <h2>Start using your vault</h2>
-      <p>Notes is installed and ready. Capture your first note in the
-        Notes app — it reads from <code>${safeVault}</code> directly.</p>
-      <p><a class="btn btn-primary" href="/app/notes/">Open Notes</a></p>
-    </section>`;
-  }
+  // The `?url=` query param is consumed by notes-ui's AddVault route
+  // (packages/notes-ui/src/app/routes/AddVault.tsx) — it pre-fills the
+  // vault URL input + auto-focuses Submit.
+  const vaultUrlForAdd = encodeURIComponent(`${hubOrigin.replace(/\/+$/, "")}/vault/${vaultName}`);
   return `<section class="start-using" data-testid="start-using-tile">
     <h2>Start using your vault</h2>
-    <p>Your vault <code>${safeVault}</code> is provisioned. Install
-      <strong>App</strong> below (it bundles the Notes UI) to start
-      capturing — or open the vault's admin UI now to see what's
-      inside.</p>
-    <p><a class="btn btn-primary" href="/vault/${urlVault}/admin/">Open vault admin</a></p>
+    <p>Open Notes — the canonical browser UI for your vault <code>${safeVault}</code>.
+      It connects to your hub over HTTPS and remembers your URL after the first OAuth.</p>
+    <p><a class="btn btn-primary" href="https://notes.parachute.computer/add?url=${vaultUrlForAdd}" target="_blank" rel="noopener">Open Notes ↗</a></p>
+    <p class="start-using-secondary">
+      <a href="/vault/${urlVault}/admin/">Or browse the vault's admin UI →</a>
+    </p>
+  </section>`;
+}
+
+/**
+ * Starter-prompts tile on the done screen. Surfaces the two
+ * interview-style prompts hosted at parachute.computer:
+ *
+ *   1. "Help me set up my vault" — AI interviews the operator about
+ *      where their data lives + proposes a tag/path structure
+ *      (parachute.computer/onboarding/vault-setup/).
+ *   2. "Build a custom UI" — AI builds a static SPA against the vault's
+ *      HTTP API, hosted on the operator's own GitHub Pages
+ *      (parachute.computer/onboarding/surface-build/).
+ *
+ * Aaron 2026-05-27 directive: ship these as the "first AI assist"
+ * surface so freshly-onboarded operators have a clear next thing to
+ * do beyond clicking around the admin UI. The prompts live on
+ * parachute.computer rather than embedded in the wizard so they can
+ * be iterated without a hub release; the wizard just links.
+ */
+function renderStarterPromptsSection(): string {
+  return `<section class="starter-prompts" data-testid="starter-prompts">
+    <h2>Get help from your AI</h2>
+    <p class="starter-prompts-subtitle">Two interview-style prompts to paste into Claude Code or Codex once your vault's MCP is wired up.</p>
+    <div class="starter-prompts-grid">
+      <a class="starter-prompt-tile" href="https://parachute.computer/onboarding/vault-setup/" target="_blank" rel="noopener">
+        <h3>Set up your vault</h3>
+        <p>Interview-style. AI asks where your notes live now + proposes a tag &amp; path structure that fits how you actually think.</p>
+        <p class="starter-prompt-cta">Open prompt ↗</p>
+      </a>
+      <a class="starter-prompt-tile" href="https://parachute.computer/onboarding/surface-build/" target="_blank" rel="noopener">
+        <h3>Build a custom UI</h3>
+        <p>AI generates a static SPA hosted on your own GitHub Pages — talks to your vault over HTTP. Notes UI works as a reference.</p>
+        <p class="starter-prompt-cta">Open prompt ↗</p>
+      </a>
+    </div>
   </section>`;
 }
 
@@ -1079,13 +1486,12 @@ function renderInstallTile(tile: ModuleInstallTileState): string {
  * surface decision.
  */
 const USE_IT_NOW_URLS: Partial<Record<CuratedModuleShort, string>> = {
-  app: "/app/notes/",
-  notes: "/notes/",
-  // Omitted: scribe + runner. They don't ship an admin SPA yet
-  // (scribe#53, runner#8 track). Pointing "Use it now" at /scribe/admin
-  // or /runner/admin today would 404 — better to fall through to the
-  // "Manage modules" link than to send the operator into a dead end.
-  // Add the entry here once those modules ship their admin UI.
+  // Empty: vault has its own lead "Start using" tile (the
+  // notes.parachute.computer CTA), so it doesn't appear here. Scribe
+  // doesn't ship an admin SPA at /scribe/admin/ that's useful for
+  // first-time operators (the page exists but it's config-management;
+  // not "use it"). Re-add per-module entries here if/when a module
+  // ships a user-facing landing surface worth pointing at.
 };
 
 /**
@@ -1162,6 +1568,29 @@ export function handleSetupGet(req: Request, deps: SetupWizardDeps): Response {
   const url = new URL(req.url);
   const state = deriveWizardState(deps);
   const csrf = ensureCsrfToken(req);
+  const wantsJson = wantsJsonResponse(req);
+  // CLI wizard surface (hub#168 Cut 3): the GET endpoint doubles as a
+  // state-probe API. Same state-derivation, same DB read; only the
+  // response shape forks on Accept. Returning the JSON envelope before
+  // the HTML rendering branches means the CLI gets the answer it needs
+  // without the wizard having to render a 30KB HTML page per poll.
+  if (wantsJson) {
+    const requireToken = getBootstrapToken() !== undefined;
+    const envelope = {
+      step: state.step,
+      hasAdmin: state.hasAdmin,
+      hasVault: state.hasVault,
+      hasExposeMode: state.hasExposeMode,
+      requireBootstrapToken: requireToken,
+      csrfToken: csrf.token,
+    };
+    const jsonHeaders: Record<string, string> = {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    };
+    if (csrf.setCookie) jsonHeaders["set-cookie"] = csrf.setCookie;
+    return new Response(JSON.stringify(envelope), { status: 200, headers: jsonHeaders });
+  }
   const extraHeaders: Record<string, string> = {
     "content-type": "text/html; charset=utf-8",
   };
@@ -1215,28 +1644,41 @@ export function handleSetupGet(req: Request, deps: SetupWizardDeps): Response {
       // /admin/tokens.
       const mintedToken = getSetting(deps.db, "setup_minted_token");
       if (mintedToken) deleteSetting(deps.db, "setup_minted_token");
-      // hub#267: the operator-typed vault name lives in hub_settings
-      // (persisted by handleSetupVaultPost). Fall back to scanning
-      // services.json — covers wizard runs from before this PR where
-      // setup_vault_name wasn't written. The services.json read
-      // returns the path-tail; vault's own first-boot write produces
-      // the canonical name so the two should agree once the vault
-      // boots authoritatively.
+      // Prefer the LIVE vault name from services.json over the
+      // operator-typed value cached in hub_settings (smoke
+      // 2026-05-27, finding 2). The cached value is what the
+      // operator typed into the wizard form — fine on the happy
+      // path, but stale if the vault install failed and the
+      // operator worked around it (e.g. installed vault under a
+      // different name via the CLI). The "static-write + stale-
+      // read" pattern Aaron's flagged repeatedly:
+      // `feedback_static_vs_dynamic_state.md`. Read state
+      // dynamically when it can change.
+      //
+      // Fall back to the DB setting only if services.json has no
+      // vault entry — covers a transient "wizard hit done but
+      // vault is still pending" race where the operator-typed
+      // value is the only signal we have. Final fallback is
+      // "default" so the rendered name is always something the
+      // operator can act on.
+      const liveName = firstVaultNameOrNull(deps.manifestPath);
       const storedName = getSetting(deps.db, "setup_vault_name");
-      const vaultName = storedName ?? firstVaultName(deps.manifestPath);
+      const vaultName = liveName ?? storedName ?? "default";
       // Module install tiles (hub#272 Item B). One per curated module
       // other than vault (which the wizard already provisioned).
       const installTiles = buildInstallTiles(url, deps);
-      // hub#342: drive the lead "Start using your vault" tile's target.
-      // When parachute-app is installed alongside vault, the tile links
-      // to `/app/notes/` (auto-bootstrapped Notes-as-UI per parachute-app
-      // §17). Otherwise it falls back to the vault's own admin UI.
-      const appInstalled = isModuleInstalled("app", deps.manifestPath);
+      // The lead "Start using your vault" tile points at
+      // notes.parachute.computer/add — always, regardless of any
+      // local module install state. Prior versions of this code
+      // checked `isModuleInstalled("surface", ...)` to switch to a
+      // local `/surface/notes/` link, but the launch focus is
+      // hub+vault+scribe and notes.parachute.computer is the
+      // canonical Notes UI (Aaron-directed 2026-05-27). Dropped the
+      // local-fallback branch.
       const doneProps: RenderDoneStepProps = {
         vaultName,
         hubOrigin: deps.issuer,
         installTiles,
-        appInstalled,
       };
       if (exposeMode !== undefined) doneProps.exposeMode = exposeMode;
       if (mintedToken) doneProps.mintedToken = mintedToken;
@@ -1270,25 +1712,33 @@ export function handleSetupGet(req: Request, deps: SetupWizardDeps): Response {
   // Step 3 (vault) with an op in flight — render the poll page.
   if (state.hasAdmin && !state.hasVault) {
     const opId = url.searchParams.get("op");
+    const cloudHost = detectAutoExposeMode(deps.env ?? process.env) === "public";
     if (opId) {
       const registry = deps.registry;
       const op = registry?.get(opId);
       if (op) {
+        // Carry the scribe op_id forward via the query param so the
+        // op-poll page's success-redirect threads it into the done
+        // step's URL (where buildInstallTiles picks it up via the
+        // existing per-tile `op_scribe` mechanism).
+        const scribeOpIdParam = url.searchParams.get("op_scribe") ?? undefined;
         return new Response(
           renderVaultStep({
             csrfToken: csrf.token,
+            cloudHost,
             operation: {
               id: op.id,
               status: op.status,
               log: op.log,
               ...(op.error !== undefined ? { error: op.error } : {}),
+              ...(scribeOpIdParam !== undefined ? { scribeOpId: scribeOpIdParam } : {}),
             },
           }),
           { status: 200, headers: extraHeaders },
         );
       }
     }
-    return new Response(renderVaultStep({ csrfToken: csrf.token }), {
+    return new Response(renderVaultStep({ csrfToken: csrf.token, cloudHost }), {
       status: 200,
       headers: extraHeaders,
     });
@@ -1327,9 +1777,19 @@ export async function handleSetupAccountPost(
   req: Request,
   deps: SetupWizardDeps,
 ): Promise<Response> {
-  const form = await req.formData();
+  const form = await readBodyFields(req);
+  // JSON callers (CLI wizard, hub#168 Cut 3) generally don't have a
+  // pre-existing CSRF cookie because the GET that returned the JSON
+  // envelope just set one — the CLI's fetch is the first request and
+  // the verifyCsrfToken's double-submit check needs the cookie + body
+  // value to match. The wizard's GET surface sets the cookie; the CLI
+  // reads it back from `Set-Cookie` and threads it on subsequent POSTs,
+  // matching the browser behavior. CSRF verification is shared.
   const formCsrf = form.get(CSRF_FIELD_NAME);
   if (!verifyCsrfToken(req, typeof formCsrf === "string" ? formCsrf : null)) {
+    if (form.isJson) {
+      return jsonErrorResponse(400, "Invalid form submission", "Reload and try again.");
+    }
     return badRequestPage("Invalid form submission", "Reload and try again.");
   }
   // Already-bootstrapped: bounce. The wizard's GET state will resolve to
@@ -1342,10 +1802,16 @@ export async function handleSetupAccountPost(
   const requireToken = getBootstrapToken() !== undefined;
   if (userCount(deps.db) > 0) {
     if (!requireToken) {
+      if (form.isJson) {
+        return jsonOkResponse({ step: "vault", message: "admin already exists" });
+      }
       return redirect("/admin/setup");
     }
     // Defense in depth: a token was active but an admin already exists.
     // Treat as consumed.
+    if (form.isJson) {
+      return jsonErrorResponse(410, "Admin already claimed", "Bootstrap token was already used.");
+    }
     return new Response(renderClaimAlreadyHappenedPage(), {
       status: 410,
       headers: { "content-type": "text/html; charset=utf-8" },
@@ -1359,6 +1825,13 @@ export async function handleSetupAccountPost(
   if (requireToken) {
     const suppliedToken = String(form.get("bootstrap_token") ?? "").trim();
     if (!verifyBootstrapToken(suppliedToken)) {
+      if (form.isJson) {
+        return jsonErrorResponse(
+          401,
+          "Bootstrap token rejected",
+          "Re-check the `parachute-bootstrap-…` line in your hub's startup logs.",
+        );
+      }
       const username = String(form.get("username") ?? "").trim();
       return htmlResponse(
         renderAccountStep({
@@ -1380,6 +1853,9 @@ export async function handleSetupAccountPost(
   const confirm = String(form.get("password_confirm") ?? "");
   const fieldErr = validateAccountFields({ username, password, confirm });
   if (fieldErr) {
+    if (form.isJson) {
+      return jsonErrorResponse(400, "Invalid account fields", fieldErr);
+    }
     return htmlResponse(
       renderAccountStep({
         csrfToken,
@@ -1412,6 +1888,9 @@ export async function handleSetupAccountPost(
     const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
       secure: isHttpsRequest(req),
     });
+    if (form.isJson) {
+      return jsonOkResponse({ step: "vault", message: "admin created" }, { "set-cookie": cookie });
+    }
     return redirect("/admin/setup", { "set-cookie": cookie });
   } catch (err) {
     // Log the raw error server-side for the operator's debugging, but
@@ -1425,6 +1904,13 @@ export async function handleSetupAccountPost(
     // shell.
     const msg = err instanceof Error ? err.message : String(err);
     console.warn(`[setup-wizard] createUser failed for "${username}": ${msg}`);
+    if (form.isJson) {
+      return jsonErrorResponse(
+        400,
+        "Account creation failed",
+        "Failed to create account. The username may already be taken.",
+      );
+    }
     return htmlResponse(
       renderAccountStep({
         csrfToken,
@@ -1466,7 +1952,26 @@ function renderClaimAlreadyHappenedPage(): string {
 }
 
 /**
- * POST `/admin/setup/vault`. Form-encoded.
+ * POST `/admin/setup/vault`. Accepts `application/x-www-form-urlencoded`
+ * (browser) and `application/json` (CLI wizard).
+ *
+ * Three modes (hub#168 Cut 2 — Aaron's 2026-05-28 directive): `mode`
+ * field is the discriminant.
+ *   * `create` (default if absent — back-compat with the pre-hub#168
+ *     browser flow that didn't send `mode`): provision a new vault under
+ *     the typed name.
+ *   * `import`: provision an empty vault under the typed name, then
+ *     POST to vault's `/vault/<name>/.parachute/mirror/import` endpoint
+ *     with the supplied remote URL + optional PAT. Surfaces import
+ *     progress through the same op-poll machinery used by the create
+ *     path.
+ *   * `skip`: don't create or import anything. The wizard advances to
+ *     the expose step. The "vault module installed" signal is still
+ *     true (init.ts pre-installed it under hub#168 Cut 1), but no
+ *     instance exists — `deriveWizardState`'s `hasVault` reflects the
+ *     services.json shape, which `skip` leaves untouched. To make the
+ *     wizard *advance past* the vault step on skip we persist a
+ *     `setup_vault_skipped` flag that `deriveWizardState` consults.
  *
  * Gated by the admin session cookie set at step 2 — a stale tab without
  * the cookie won't accidentally try to provision a vault. The session is
@@ -1474,31 +1979,33 @@ function renderClaimAlreadyHappenedPage(): string {
  * same one driving step 3 (they're necessarily the only user in
  * single-user mode).
  *
- * Drives `runInstall` directly (not the bearer-gated `handleInstall`).
- * The bearer check exists to keep narrow `:auth`-scope automation
- * tokens from hitting destructive endpoints; the wizard is already
- * gated on session + on "no vault exists yet," so a separate
- * bearer-mint dance would be pure ceremony.
- *
- * Returns a 303-redirect to `/admin/setup?op=<id>` so the wizard's
- * polling GET shape kicks in. The actual `bun add` runs in the
- * background; failures surface in the op log.
+ * Browser shape: returns 303 to `/admin/setup?op=<id>` (create/import) or
+ * `/admin/setup` (skip).
+ * CLI shape: returns 200 JSON `{ op_id?, step }`.
  */
 export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps): Promise<Response> {
-  if (!deps.supervisor) {
-    return badRequestPage(
-      "Module supervisor unavailable",
-      "The first-boot wizard needs container-mode `parachute serve` to install modules. " +
-        "On the on-box CLI surface, run `parachute install vault` directly.",
-    );
-  }
-  const form = await req.formData();
+  // Note: supervisor gate moved BELOW the mode check (hub#168 Cut 2) so
+  // that `mode=skip` doesn't fail on the CLI hub surface (which doesn't
+  // wire a supervisor — operators install vault via `parachute install
+  // vault` on the on-box CLI path; the wizard's role there is the
+  // account + skip + expose decisions only).
+  const form = await readBodyFields(req);
   const formCsrf = form.get(CSRF_FIELD_NAME);
   if (!verifyCsrfToken(req, typeof formCsrf === "string" ? formCsrf : null)) {
+    if (form.isJson) {
+      return jsonErrorResponse(400, "Invalid form submission", "Reload and try again.");
+    }
     return badRequestPage("Invalid form submission", "Reload and try again.");
   }
   const session = findActiveSession(deps.db, req);
   if (!session) {
+    if (form.isJson) {
+      return jsonErrorResponse(
+        401,
+        "No admin session",
+        "Sign in to continue setup. The session cookie was set on step 2.",
+      );
+    }
     return badRequestPage(
       "No admin session",
       "Sign in to continue setup. (The wizard sets a session cookie on step 2; clearing cookies between steps will land you here.)",
@@ -1506,7 +2013,66 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
   }
   // Already done — short-circuit to the done step.
   const state = deriveWizardState(deps);
-  if (state.hasVault) return redirect("/admin/setup?just_finished=1");
+  if (state.hasVault) {
+    if (form.isJson) {
+      return jsonOkResponse({ step: "expose", message: "vault already provisioned" });
+    }
+    return redirect("/admin/setup?just_finished=1");
+  }
+
+  // Mode discriminant (hub#168 Cut 2). Default is "create" for back-
+  // compat with the existing browser form — it doesn't send `mode`.
+  const rawMode = String(form.get("mode") ?? "create").trim();
+  if (rawMode !== "create" && rawMode !== "import" && rawMode !== "skip") {
+    if (form.isJson) {
+      return jsonErrorResponse(
+        400,
+        "Invalid vault mode",
+        `mode must be one of create, import, skip (got "${rawMode}")`,
+      );
+    }
+    return badRequestPage("Invalid vault mode", "mode must be one of create, import, skip.");
+  }
+
+  // Skip path (hub#168 Cut 2): module is already installed (init.ts
+  // ran `install vault --no-create`); we just persist a flag that
+  // `deriveWizardState` consults to skip the vault step on subsequent
+  // GETs. No supervisor work, no op_id — runs without the supervisor.
+  if (rawMode === "skip") {
+    setSetting(deps.db, "setup_vault_skipped", "true");
+    if (form.isJson) {
+      return jsonOkResponse({ step: "expose", message: "vault step skipped" });
+    }
+    return redirect("/admin/setup");
+  }
+
+  // Operator picked create or import — if they previously skipped (in
+  // another tab / via back button), the skip flag would still claim
+  // "vault step done" even after the vault row appears. Clear it
+  // defensively so `deriveWizardState` consults the real vault entry
+  // going forward.
+  deleteSetting(deps.db, "setup_vault_skipped");
+
+  // Create / import paths need the supervisor — they spawn vault and
+  // (for import) call vault's mirror endpoint. The CLI hub surface
+  // doesn't wire a supervisor; operators are expected to use
+  // `parachute install vault` directly there. Container/serve-mode
+  // hub has one.
+  if (!deps.supervisor) {
+    if (form.isJson) {
+      return jsonErrorResponse(
+        503,
+        "Module supervisor unavailable",
+        "The wizard's create/import paths need container-mode `parachute serve` to spawn vault. " +
+          "On the on-box CLI surface, run `parachute install vault` first, then re-run the wizard with --vault-mode skip.",
+      );
+    }
+    return badRequestPage(
+      "Module supervisor unavailable",
+      "The first-boot wizard needs container-mode `parachute serve` to install modules. " +
+        "On the on-box CLI surface, run `parachute install vault` directly.",
+    );
+  }
 
   // hub#267: the operator-typed vault name is now threaded all the way
   // through to vault's first-boot via `PARACHUTE_VAULT_NAME` (vault#342
@@ -1521,6 +2087,9 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
   } else {
     const v = validateVaultName(rawName);
     if (!v.ok) {
+      if (form.isJson) {
+        return jsonErrorResponse(400, "Invalid vault name", v.error);
+      }
       return htmlResponse(
         renderVaultStep({
           csrfToken: csrfTokenStr,
@@ -1532,6 +2101,51 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
     }
     vaultName = v.name;
   }
+
+  // Import path (hub#168 Cut 2): collect the remote URL + optional PAT
+  // + replace flag up front so a malformed input fails fast before we
+  // spawn the vault. The actual import POST to vault's
+  // `/vault/<name>/.parachute/mirror/import` happens AFTER vault has
+  // come up under the supervisor; the params are captured by closure
+  // into the post-install `.then()` (see `importToRun` below).
+  let importParams: { remoteUrl: string; pat?: string; mode: "merge" | "replace" } | undefined;
+  if (rawMode === "import") {
+    const remoteUrl = String(form.get("remote_url") ?? "").trim();
+    if (remoteUrl === "") {
+      if (form.isJson) {
+        return jsonErrorResponse(
+          400,
+          "Remote URL required",
+          'remote_url must be a non-empty HTTPS or SSH clone URL when mode="import".',
+        );
+      }
+      return htmlResponse(
+        renderVaultStep({
+          csrfToken: csrfTokenStr,
+          vaultName: rawName,
+          errorMessage: "Remote URL is required to import a vault. Paste a git clone URL.",
+        }),
+        400,
+      );
+    }
+    const importMode = String(form.get("import_mode") ?? "merge").trim();
+    if (importMode !== "merge" && importMode !== "replace") {
+      const err = `import_mode must be "merge" or "replace" (got "${importMode}").`;
+      if (form.isJson) {
+        return jsonErrorResponse(400, "Invalid import_mode", err);
+      }
+      return htmlResponse(
+        renderVaultStep({ csrfToken: csrfTokenStr, vaultName: rawName, errorMessage: err }),
+        400,
+      );
+    }
+    const pat = String(form.get("pat") ?? "").trim();
+    importParams = {
+      remoteUrl,
+      mode: importMode,
+      ...(pat ? { pat } : {}),
+    };
+  }
   // Persist for the done-step renderer. Vault overwrites services.json
   // on its first authoritative boot, but until that completes the wizard
   // needs a stable source of truth for the typed name — both for the
@@ -1564,8 +2178,14 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
         { status: "succeeded" },
         `${FIRST_VAULT_SHORT} already supervised (status=${supervisorState.status})`,
       );
+      if (form.isJson) {
+        return jsonOkResponse({ op_id: op.id, step: "vault", message: "vault already supervised" });
+      }
       return redirect(`/admin/setup?op=${encodeURIComponent(op.id)}`);
     }
+    if (form.isJson) {
+      return jsonOkResponse({ step: "vault", message: "vault already supervised" });
+    }
     return redirect("/admin/setup");
   }
 
@@ -1588,6 +2208,17 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
     if (vaultName !== DEFAULT_VAULT_NAME) {
       spawnEnv.PARACHUTE_VAULT_NAME = vaultName;
     }
+    // Capture importParams + deps in the runInstall promise chain — when
+    // mode === "import", run the vault-side `/.parachute/mirror/import`
+    // POST as a follow-up step once the supervised vault has come up
+    // and confirmed healthy. The hub-side op_id stays the same so the
+    // CLI / browser sees a single progress stream; we just append more
+    // log lines while the import runs. On import error, the op is
+    // marked failed so the caller surfaces a usable message.
+    const importToRun = importParams;
+    const vaultIssuer = deps.issuer;
+    const importerUserId = session.userId;
+    const vaultPort = vaultSpec.seedEntry?.().port ?? 1940;
     void runInstall(op.id, FIRST_VAULT_SHORT, vaultSpec, {
       db: deps.db,
       issuer: deps.issuer,
@@ -1596,11 +2227,63 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
       supervisor: deps.supervisor,
       registry,
       ...(deps.run ? { run: deps.run } : {}),
+      ...(deps.isLinked ? { isLinked: deps.isLinked } : {}),
       ...(Object.keys(spawnEnv).length > 0 ? { spawnEnv } : {}),
-    }).catch((err) => {
-      const msg = err instanceof Error ? err.message : String(err);
-      registry.update(op.id, { status: "failed", error: msg }, `install failed: ${msg}`);
-    });
+    })
+      .then(async () => {
+        if (!importToRun) return;
+        const opState = registry.get(op.id);
+        if (!opState || opState.status !== "succeeded") return;
+        // Import is a follow-up step: mark op back to running, POST to
+        // vault, surface the result in the op log.
+        registry.update(
+          op.id,
+          { status: "running" },
+          `vault up — starting import from ${importToRun.remoteUrl} (mode=${importToRun.mode})`,
+        );
+        try {
+          // Mint a short-lived per-vault admin Bearer for the import POST.
+          // Vault validates audience `vault.<name>` + scope `vault:<name>:admin`
+          // (see admin-vault-admin-token.ts for the canonical shape — same
+          // contract the SPA Manage link uses). The token only needs to
+          // live until vault accepts the HTTP request (the clone itself
+          // happens inside vault after the auth check passes); 5 min is
+          // a generous safety net covering the supervisor's boot-grace
+          // retries on a sluggish host. Deliberate divergence from the
+          // SPA's 10-min TTL because this token is one-shot, not refreshed.
+          const minted = await signAccessToken(deps.db, {
+            sub: importerUserId,
+            scopes: [`vault:${vaultName}:admin`],
+            audience: `vault.${vaultName}`,
+            clientId: "parachute-hub-setup-wizard",
+            issuer: vaultIssuer,
+            ttlSeconds: 5 * 60,
+            vaultScope: [vaultName],
+          });
+          const result = await postVaultImportImpl({
+            vaultName,
+            vaultPort,
+            bearerToken: minted.token,
+            remoteUrl: importToRun.remoteUrl,
+            mode: importToRun.mode,
+            ...(importToRun.pat ? { pat: importToRun.pat } : {}),
+          });
+          registry.update(
+            op.id,
+            { status: "succeeded" },
+            `import succeeded — notes_imported=${result.notes_imported ?? 0}, tags_imported=${
+              result.tags_imported ?? 0
+            }, attachments_imported=${result.attachments_imported ?? 0}`,
+          );
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          registry.update(op.id, { status: "failed", error: msg }, `import failed: ${msg}`);
+        }
+      })
+      .catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        registry.update(op.id, { status: "failed", error: msg }, `install failed: ${msg}`);
+      });
   } else {
     // No registry wired (test-only path; production always passes one).
     // Log a visible warning so future mis-wirings are debuggable —
@@ -1609,7 +2292,281 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
       "[setup-wizard] handleSetupVaultPost called with no operations registry — install will NOT run. Wire deps.registry in the dispatcher.",
     );
   }
-  return redirect(`/admin/setup?op=${encodeURIComponent(op.id)}`);
+  // Scribe sub-form fold (2026-05-27). The vault step's form lets
+  // the operator answer "do you also want voice transcription?" +
+  // "do you also want LLM cleanup?" in the same submission. If they
+  // asked for either, we (a) write the chosen provider(s) + API
+  // key(s) to `~/.parachute/scribe/config.json` so scribe finds
+  // them on first boot, and (b) kick a scribe install op in
+  // parallel with vault install. The vault op-poll page threads the
+  // scribe op_id through its success-redirect so the done step can
+  // poll scribe progress via the existing per-tile mechanism.
+  //
+  // 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();
+  const scribeCleanupProvider = String(form.get("scribe_cleanup_provider") ?? "").trim();
+  const wantsTranscribe = scribeProvider !== "" && scribeProvider !== "none";
+  const wantsCleanup = scribeCleanupProvider !== "" && scribeCleanupProvider !== "none";
+  let scribeOpId: string | undefined;
+  if (wantsTranscribe || wantsCleanup) {
+    const scribeApiKey = String(form.get("scribe_api_key") ?? "").trim();
+    const scribeCleanupApiKey = String(form.get("scribe_cleanup_api_key") ?? "").trim();
+    // Write scribe config FIRST so scribe's first boot picks up the
+    // provider(s) + key(s) without a second config edit. We don't
+    // fail the wizard on a config-write error — log it + carry on;
+    // scribe will boot with defaults + the operator can fix via
+    // /scribe/admin.
+    try {
+      writeScribeConfigForWizard(deps.configDir, {
+        ...(wantsTranscribe
+          ? { transcribe: { provider: scribeProvider, apiKey: scribeApiKey } }
+          : {}),
+        ...(wantsCleanup
+          ? { cleanup: { provider: scribeCleanupProvider, apiKey: scribeCleanupApiKey } }
+          : {}),
+      });
+    } catch (err) {
+      console.warn(
+        `[setup-wizard] failed to write scribe config: ${err instanceof Error ? err.message : String(err)} — kicking install anyway, operator can configure later.`,
+      );
+    }
+    // Kick scribe install in parallel. Don't block on it; the done
+    // step's per-tile op-poll surfaces progress.
+    if (registry) {
+      const scribeSpec = specFor("scribe");
+      const scribeOp = registry.create("install", "scribe");
+      scribeOpId = scribeOp.id;
+      void runInstall(scribeOp.id, "scribe", scribeSpec, {
+        db: deps.db,
+        issuer: deps.issuer,
+        manifestPath: deps.manifestPath,
+        configDir: deps.configDir,
+        supervisor: deps.supervisor,
+        registry,
+        ...(deps.run ? { run: deps.run } : {}),
+        ...(deps.isLinked ? { isLinked: deps.isLinked } : {}),
+      }).catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        registry.update(
+          scribeOp.id,
+          { status: "failed", error: msg },
+          `scribe install failed: ${msg}`,
+        );
+      });
+    }
+  }
+  const redirectUrl = scribeOpId
+    ? `/admin/setup?op=${encodeURIComponent(op.id)}&op_scribe=${encodeURIComponent(scribeOpId)}`
+    : `/admin/setup?op=${encodeURIComponent(op.id)}`;
+  if (form.isJson) {
+    return jsonOkResponse({
+      op_id: op.id,
+      ...(scribeOpId ? { scribe_op_id: scribeOpId } : {}),
+      step: "vault",
+      mode: rawMode,
+    });
+  }
+  return redirect(redirectUrl);
+}
+
+/**
+ * POST the wizard-collected import params to vault's
+ * `/vault/<name>/.parachute/mirror/import` endpoint. The caller mints
+ * the per-vault admin Bearer (see `signAccessToken` use in the
+ * `runInstall().then(...)` block above) and passes it in; vault gates
+ * the endpoint on `vault:<name>:admin` upstream. Returns vault's
+ * structured response or throws with a usable message.
+ *
+ * Lives in setup-wizard.ts (not as a vault-internal helper) because
+ * vault doesn't import hub-internal code; the import POST is naturally
+ * the wizard's job — it's the only caller until vault ships its own
+ * admin SPA flow. Shape mirrors vault#390's contract:
+ *   POST /vault/<name>/.parachute/mirror/import
+ *   { remote_url, mode: "merge"|"replace", credentials: {kind, token}|null }
+ *   200 { notes_imported, tags_imported, attachments_imported, warnings }
+ *
+ * Exported (with the `Impl` suffix) so tests can inject a stub fetcher
+ * and assert the Authorization header without standing up a real vault.
+ */
+export async function postVaultImportImpl(args: {
+  vaultName: string;
+  vaultPort: number;
+  bearerToken: string;
+  remoteUrl: string;
+  mode: "merge" | "replace";
+  pat?: string;
+  fetcher?: typeof fetch;
+}): Promise<{
+  notes_imported?: number;
+  tags_imported?: number;
+  attachments_imported?: number;
+  warnings?: readonly string[];
+}> {
+  const fetcher = args.fetcher ?? fetch;
+  // Vault listens on its supervised port — talk directly to 127.0.0.1
+  // rather than going through hub's path-routing proxy. Cuts one
+  // network hop and avoids the operator-session/CSRF dance.
+  const url = `http://127.0.0.1:${args.vaultPort}/vault/${encodeURIComponent(args.vaultName)}/.parachute/mirror/import`;
+  const body: Record<string, unknown> = {
+    remote_url: args.remoteUrl,
+    mode: args.mode,
+  };
+  if (args.pat) {
+    body.credentials = { kind: "pat", token: args.pat };
+  } else {
+    body.credentials = null;
+  }
+  // Best-effort retry — the supervisor's `start` returns before vault
+  // accepts traffic; a tiny grace window covers the boot lag without
+  // a tight poll loop. Three attempts spaced 1s apart.
+  let lastErr: Error | undefined;
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      const res = await fetcher(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          // Vault's `authenticateVaultRequest` rejects 401 before scope
+          // check when no Bearer is present. The token must carry
+          // `vault:<name>:admin` + audience `vault.<name>` — minted at
+          // the call site via `signAccessToken` so this function stays
+          // pure (no db / userId capture).
+          authorization: `Bearer ${args.bearerToken}`,
+        },
+        body: JSON.stringify(body),
+      });
+      if (res.status === 200) {
+        return (await res.json()) as Awaited<ReturnType<typeof postVaultImportImpl>>;
+      }
+      // Vault returns structured JSON errors per mirror-routes.ts:
+      // 400 (validation), 409 (concurrent), 502 (clone failed), 500.
+      const errBody = (await res.json().catch(() => ({}))) as { message?: string; error?: string };
+      throw new Error(
+        `vault import returned ${res.status}: ${errBody.message ?? errBody.error ?? "unknown"}`,
+      );
+    } catch (err) {
+      lastErr = err instanceof Error ? err : new Error(String(err));
+      // ECONNREFUSED / fetch failure → vault hasn't bound yet. Retry.
+      if (lastErr.message.includes("ECONNREFUSED") || lastErr.message.includes("Failed to fetch")) {
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        continue;
+      }
+      throw lastErr;
+    }
+  }
+  throw lastErr ?? new Error("vault import: exhausted retries");
+}
+
+/**
+ * Write a minimal scribe config that selects the operator's chosen
+ * transcribe + cleanup providers + API keys (when applicable).
+ * Idempotent: reads any existing config, merges, writes back. File
+ * mode 0o600 — the config holds API keys, owner-only.
+ *
+ * Lives in setup-wizard.ts (not scribe's own config-write.ts) because
+ * (a) it's a one-time wizard write — the SPA's PUT /.parachute/config
+ * surface is the canonical post-setup path, and (b) hub doesn't
+ * import scribe-internal modules. The shape of `scribe-config.json`
+ * is documented in parachute-scribe/src/config.ts; the fields we set
+ * (`transcribe.provider`, `transcribeProviders.<name>.apiKey`,
+ * `cleanup.provider`, `cleanup.default`, `cleanupProviders.<name>.apiKey`)
+ * are stable. Cleanup block extended 2026-05-27 — scribe boots with
+ * `cleanup: none` otherwise, so first-install operators got "raw
+ * transcript only" until they hand-edited the config.
+ *
+ * Signature changed 2026-05-27 from `(configDir, provider, apiKey)` to
+ * the options-object shape so the caller can express "cleanup only,
+ * no transcribe" without smuggling sentinel strings.
+ */
+interface WizardScribeConfig {
+  /** Set when the operator chose a transcription provider (anything other than "none"). */
+  transcribe?: { provider: string; apiKey: string };
+  /** Set when the operator chose a cleanup provider (anything other than "none"). */
+  cleanup?: { provider: string; apiKey: string };
+}
+function writeScribeConfigForWizard(configDir: string, config: WizardScribeConfig): void {
+  const update: Record<string, unknown> = {};
+
+  if (config.transcribe) {
+    const { provider, apiKey } = config.transcribe;
+    // For `local` (Mac MLX / cross-platform ONNX), just set the
+    // provider name — no key needed.
+    if (provider === "local") {
+      update.transcribe = { provider: "parakeet-mlx" };
+    } else {
+      // Cloud providers need a key. Empty key → just set provider;
+      // the operator can paste the key later via /scribe/admin
+      // without a restart (per provider-config.ts's per-request
+      // precedence).
+      update.transcribe = { provider };
+      if (apiKey !== "") {
+        update.transcribeProviders = { [provider]: { apiKey } };
+      }
+    }
+  }
+
+  if (config.cleanup) {
+    const { provider, apiKey } = config.cleanup;
+    // Always set `cleanup.default: true` when the operator opted in to
+    // cleanup — they want polished output as the default; the per-
+    // request `cleanup` flag on each transcribe request can still
+    // opt out individually.
+    update.cleanup = { provider, default: true };
+    // `claude-code` (host CLI auth) and `ollama` (local server)
+    // don't need an API key. Everything else (anthropic, openai,
+    // groq, gemini) takes a key. Empty key → just set the provider;
+    // the operator can paste the key later via the admin SPA without
+    // a restart.
+    const needsKey = provider !== "claude-code" && provider !== "ollama";
+    if (needsKey && apiKey !== "") {
+      update.cleanupProviders = { [provider]: { apiKey } };
+    }
+  }
+
+  if (Object.keys(update).length === 0) return;
+  persistScribeConfig(configDir, update);
+}
+
+/**
+ * Merge-write to scribe's config file at `<configDir>/scribe/config.json`.
+ * Reads existing JSON when present, deep-merges `update`, writes back at
+ * mode 0o600. Creates the parent dir if missing.
+ */
+function persistScribeConfig(configDir: string, update: Record<string, unknown>): void {
+  const scribeDir = join(configDir, "scribe");
+  const configPath = join(scribeDir, "config.json");
+  mkdirSync(scribeDir, { recursive: true });
+  let existing: Record<string, unknown> = {};
+  if (existsSync(configPath)) {
+    try {
+      existing = JSON.parse(readFileSync(configPath, "utf8")) as Record<string, unknown>;
+    } catch {
+      // Malformed existing config — treat as empty + overwrite.
+      existing = {};
+    }
+  }
+  // Shallow merge at top level, deep merge for the sub-blocks we touch
+  // (transcribe + transcribeProviders + cleanup + cleanupProviders). The
+  // merge logic is generic and handles any nested object — it doesn't
+  // hard-code the block names.
+  const merged: Record<string, unknown> = { ...existing };
+  for (const [key, value] of Object.entries(update)) {
+    if (
+      typeof value === "object" &&
+      value !== null &&
+      !Array.isArray(value) &&
+      typeof merged[key] === "object" &&
+      merged[key] !== null &&
+      !Array.isArray(merged[key])
+    ) {
+      merged[key] = { ...(merged[key] as Record<string, unknown>), ...value };
+    } else {
+      merged[key] = value;
+    }
+  }
+  writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`, { mode: 0o600 });
 }
 
 /**
@@ -1633,13 +2590,19 @@ export async function handleSetupExposePost(
   req: Request,
   deps: SetupWizardDeps,
 ): Promise<Response> {
-  const form = await req.formData();
+  const form = await readBodyFields(req);
   const formCsrf = form.get(CSRF_FIELD_NAME);
   if (!verifyCsrfToken(req, typeof formCsrf === "string" ? formCsrf : null)) {
+    if (form.isJson) {
+      return jsonErrorResponse(400, "Invalid form submission", "Reload and try again.");
+    }
     return badRequestPage("Invalid form submission", "Reload and try again.");
   }
   const session = findActiveSession(deps.db, req);
   if (!session) {
+    if (form.isJson) {
+      return jsonErrorResponse(401, "No admin session", "Sign in to continue setup.");
+    }
     return badRequestPage(
       "No admin session",
       "Sign in to continue setup. (The wizard sets a session cookie on step 2; clearing cookies between steps will land you here.)",
@@ -1649,10 +2612,20 @@ export async function handleSetupExposePost(
   // the wizard's GET shape catches this case too, but a direct POST
   // (curl, tab race) shouldn't double-fire the auto-approve window.
   if (getSetting(deps.db, "setup_expose_mode") !== undefined) {
+    if (form.isJson) {
+      return jsonOkResponse({ step: "done", message: "expose mode already set" });
+    }
     return redirect("/admin/setup?just_finished=1");
   }
   const rawMode = form.get("expose_mode");
   if (!isSetupExposeMode(rawMode)) {
+    if (form.isJson) {
+      return jsonErrorResponse(
+        400,
+        "Invalid expose_mode",
+        `Pick one of: ${SETUP_EXPOSE_MODES.join(", ")}.`,
+      );
+    }
     return htmlResponse(
       renderExposeStep({
         csrfToken: typeof formCsrf === "string" ? formCsrf : "",
@@ -1678,12 +2651,14 @@ export async function handleSetupExposePost(
   // registry so revocation via the admin UI works as usual. Failures
   // are non-fatal: the done page falls back to the un-headered MCP
   // command + a "mint manually at /admin/tokens" hint.
+  let mintedTokenForJson: string | undefined;
   try {
     const minted = await mintOperatorToken(deps.db, session.userId, {
       issuer: deps.issuer,
       scopeSet: "admin",
     });
     setSetting(deps.db, "setup_minted_token", minted.token);
+    mintedTokenForJson = minted.token;
     console.log(
       `[setup-wizard] auto-minted operator token (jti=${minted.jti}, scope-set=admin) for done-screen MCP command`,
     );
@@ -1691,6 +2666,13 @@ export async function handleSetupExposePost(
     const msg = err instanceof Error ? err.message : String(err);
     console.warn(`[setup-wizard] failed to auto-mint operator token: ${msg}`);
   }
+  if (form.isJson) {
+    return jsonOkResponse({
+      step: "done",
+      message: "expose mode set",
+      ...(mintedTokenForJson ? { minted_token: mintedTokenForJson } : {}),
+    });
+  }
   return redirect("/admin/setup?just_finished=1");
 }
 
@@ -1710,11 +2692,6 @@ const INSTALL_TILE_PROPS: ReadonlyArray<{
   displayName: string;
   tagline: string;
 }> = [
-  {
-    short: "app",
-    displayName: "App",
-    tagline: "Host module for Parachute UIs — auto-installs Notes on first boot.",
-  },
   {
     short: "scribe",
     displayName: "Scribe",
@@ -1844,6 +2821,7 @@ export async function handleSetupInstallPost(
       supervisor: deps.supervisor,
       registry,
       ...(deps.run ? { run: deps.run } : {}),
+      ...(deps.isLinked ? { isLinked: deps.isLinked } : {}),
     }).catch((err) => {
       const msg = err instanceof Error ? err.message : String(err);
       registry.update(op.id, { status: "failed", error: msg }, `install failed: ${msg}`);
@@ -1880,11 +2858,10 @@ function validateAccountFields(input: {
 
 /**
  * Whether a given curated module is currently installed (has a row in
- * services.json keyed by its canonical `manifestName`). Used by the
- * done-step renderer (hub#342) to decide whether to point the "Start
- * using your vault" tile at `/app/notes/` (App installed → Notes UI
- * auto-bootstrapped) vs the vault's own admin UI. Cheap manifest read
- * shared with `buildInstallTiles`.
+ * services.json keyed by its canonical `manifestName`). Used by
+ * `buildInstallTiles` to decide whether an install-tile row renders
+ * the "install" form or the "already installed" state. Cheap manifest
+ * read (no network).
  */
 function isModuleInstalled(short: CuratedModuleShort, manifestPath: string): boolean {
   const manifest = readManifestLenient(manifestPath);
@@ -1893,17 +2870,21 @@ function isModuleInstalled(short: CuratedModuleShort, manifestPath: string): boo
 }
 
 /**
- * Read the first vault's display name from services.json for the
- * step-4 success page. Falls back to "default" if for any reason the
- * entry's metadata isn't present.
+ * Read the first vault's display name from services.json. Returns
+ * null when services.json has no vault entry or the entry has no
+ * `/vault/<name>` path — used by the done step to detect "no live
+ * vault, fall back to the operator-typed value." Distinguishing
+ * "no live vault" from "live vault named default" matters: the
+ * former should defer to the DB-cached name; the latter should
+ * win over a possibly-stale DB cache (smoke 2026-05-27 finding 2).
  */
-function firstVaultName(manifestPath: string): string {
+function firstVaultNameOrNull(manifestPath: string): string | null {
   const manifest = readManifestLenient(manifestPath);
   // Match on the canonical vault manifestName from the curated spec.
   // (`CURATED_MODULES.includes("vault")` was a dead guard — vault is a
   // tuple-literal member, so the conjunct is always true.)
   const entry = manifest.services.find((s) => s.name === specFor("vault").manifestName);
-  if (!entry) return "default";
+  if (!entry) return null;
   // services.json entries store the mount path (e.g. `/vault/default`).
   // Strip the canonical prefix to surface the display name.
   for (const p of entry.paths ?? []) {
@@ -1912,7 +2893,7 @@ function firstVaultName(manifestPath: string): string {
       if (tail.length > 0) return tail;
     }
   }
-  return "default";
+  return null;
 }
 
 function htmlResponse(body: string, status = 200, extra: Record<string, string> = {}): Response {
@@ -1926,6 +2907,32 @@ function redirect(location: string, extra: Record<string, string> = {}): Respons
   return new Response(null, { status: 303, headers: { location, ...extra } });
 }
 
+/**
+ * Structured JSON-200 helper for the CLI wizard surface (hub#168 Cut 3).
+ * Mirrors the browser-redirect responses' header shape (extra cookies
+ * pass through) without the 303 status that would force the CLI's
+ * `fetch` to chase a non-existent location.
+ */
+function jsonOkResponse(body: unknown, extra: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json; charset=utf-8", ...extra },
+  });
+}
+
+/**
+ * Structured JSON-error helper for the CLI wizard surface (hub#168 Cut 3).
+ * The browser path renders a full HTML error page; the CLI wants a
+ * machine-parseable envelope with the same fields the rendered page
+ * shows. Status code is the same as the HTML branch (400/401/410/etc).
+ */
+function jsonErrorResponse(status: number, title: string, message: string): Response {
+  return new Response(JSON.stringify({ error: title, message, status }), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" },
+  });
+}
+
 function badRequestPage(title: string, message: string): Response {
   return htmlResponse(renderBadRequestPage(title, message), 400);
 }
@@ -2416,6 +3423,55 @@ const STYLES = `
   }
   .done-tile .fine { font-size: 0.85rem; color: ${PALETTE.fgMuted}; }
 
+  /* Vault-mode picker (hub#168 Cut 2). Three-option radio block at the
+     top of the vault step, plus a collapsible import-only sub-form
+     below. Shape mirrors .expose-option for visual consistency. */
+  .vault-mode-block, .vault-import-block {
+    border: 1px solid ${PALETTE.border};
+    border-radius: 8px;
+    padding: 0.75rem 0.9rem;
+    margin: 0.4rem 0;
+    background: ${PALETTE.cardBg};
+    display: flex;
+    flex-direction: column;
+    gap: 0.6rem;
+  }
+  .vault-mode-block legend, .vault-import-block legend {
+    padding: 0 0.4rem;
+    font-size: 0.85rem;
+    color: ${PALETTE.fgMuted};
+    font-family: ${FONT_MONO};
+  }
+  .vault-mode-option {
+    display: flex;
+    align-items: flex-start;
+    gap: 0.6rem;
+    padding: 0.6rem 0.8rem;
+    border: 1px solid ${PALETTE.borderLight};
+    border-radius: 6px;
+    cursor: pointer;
+    transition: border-color 0.15s ease, background 0.15s ease;
+  }
+  .vault-mode-option:hover { border-color: ${PALETTE.accent}; }
+  .vault-mode-option input[type=radio] {
+    margin-top: 0.25rem;
+    accent-color: ${PALETTE.accent};
+    flex-shrink: 0;
+  }
+  .vault-mode-title {
+    font-weight: 600;
+    color: ${PALETTE.fg};
+    font-size: 0.95rem;
+    margin-left: 0.3rem;
+  }
+  .vault-mode-desc {
+    color: ${PALETTE.fgMuted};
+    font-size: 0.85rem;
+    line-height: 1.45;
+    flex-basis: 100%;
+    margin-left: 1.7rem;
+  }
+
   /* expose step (hub#268 Item 2). Vertical stack of radio cards;
      each label is the full clickable hit target. */
   .expose-form { gap: 0.65rem; }