@openparachute/hub 0.5.14-rc.2 → 0.5.14-rc.21

package/src/setup-wizard.ts

@@ -42,19 +42,20 @@ 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,
@@ -64,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";
@@ -106,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 ----------------------------------------------------
 
 /**
@@ -141,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;
@@ -158,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
@@ -180,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 —
@@ -242,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;
 }
 
 /**
@@ -261,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
@@ -372,7 +509,11 @@ export interface RenderAccountStepProps {
 export function renderAccountStep(props: RenderAccountStepProps): string {
   const { csrfToken, errorMessage, username, requireBootstrapToken, bootstrapToken } = props;
   const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
-  const usernameAttr = username ? ` value="${escapeAttr(username)}"` : "";
+  // Pre-fill "owner" on a fresh render (no prior submission) so the web wizard's
+  // default matches the CLI paths (`set-password`, `setup-wizard`) + the
+  // operator.token convention. Operators can still type any name. On a
+  // validation-failure re-render we echo back what they typed instead.
+  const usernameAttr = ` value="${escapeAttr(username ?? "owner")}"`;
   const tokenAttr = bootstrapToken ? ` value="${escapeAttr(bootstrapToken)}"` : "";
   // Bootstrap-token field comes FIRST when required. An operator who
   // missed the log line is stopped here rather than after filling
@@ -494,6 +635,14 @@ export function renderVaultStep(props: RenderVaultStepProps): string {
   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
@@ -542,7 +691,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"
@@ -552,9 +719,56 @@ 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>
+        <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">Create vault & finish</button>
+        <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);
 }
@@ -889,27 +1103,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 `/surface/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, hubOrigin);
+  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
@@ -1097,14 +1299,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
@@ -1112,48 +1318,20 @@ 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 `/surface/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.
- *
- * 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.
- */
-/**
- * Lead "Start using your vault" tile. 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-app/packages/notes-ui/src/app/routes/AddVault.tsx).
- *
- * Aaron 2026-05-27 directive: "skipping the local surface install for
- * most operators is good ... showing notes.parachute.computer more
- * prominently is a good idea." The notes.parachute.computer PWA is the
- * canonical user-facing UI; operators no longer need to install the
- * Surface module locally to use Notes. They still can (local install
- * works the same way), but the wizard doesn't push them toward it as
- * the default.
- *
+ * 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.
  *
- * `appInstalled` is no longer load-bearing for the primary path —
- * notes.parachute.computer works regardless of whether Surface is
- * installed locally. Kept in the signature so the older test fixtures
- * + the boolean flag stay coherent; only the secondary fallback message
- * differs based on it.
+ * 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,
-  hubOrigin: string,
-): 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.
@@ -1161,17 +1339,7 @@ function renderStartUsingTile(
   // 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}`,
-  );
-  // For appInstalled=false case (Surface NOT installed locally),
-  // notes.parachute.computer is the recommended path. For appInstalled=true,
-  // we mention the local option as a secondary affordance.
-  const localNotesFallback = appInstalled
-    ? `<p class="start-using-secondary">
-        <a href="/surface/notes/">Or use Notes installed locally on this hub →</a>
-      </p>`
-    : "";
+  const vaultUrlForAdd = encodeURIComponent(`${hubOrigin.replace(/\/+$/, "")}/vault/${vaultName}`);
   return `<section class="start-using" data-testid="start-using-tile">
     <h2>Start using your vault</h2>
     <p>Open Notes — the canonical browser UI for your vault <code>${safeVault}</code>.
@@ -1180,7 +1348,6 @@ function renderStartUsingTile(
     <p class="start-using-secondary">
       <a href="/vault/${urlVault}/admin/">Or browse the vault's admin UI →</a>
     </p>
-    ${localNotesFallback}
   </section>`;
 }
 
@@ -1323,13 +1490,12 @@ function renderInstallTile(tile: ModuleInstallTileState): string {
  * surface decision.
  */
 const USE_IT_NOW_URLS: Partial<Record<CuratedModuleShort, string>> = {
-  surface: "/surface/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.
 };
 
 /**
@@ -1406,6 +1572,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",
   };
@@ -1482,16 +1671,18 @@ export function handleSetupGet(req: Request, deps: SetupWizardDeps): Response {
       // 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 `/surface/notes/` (auto-bootstrapped Notes-as-UI per parachute-app
-      // §17). Otherwise it falls back to the vault's own admin UI.
-      const appInstalled = isModuleInstalled("surface", 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;
@@ -1590,9 +1781,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
@@ -1605,10 +1806,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" },
@@ -1622,6 +1829,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({
@@ -1643,6 +1857,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,
@@ -1675,6 +1892,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
@@ -1688,6 +1908,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,
@@ -1729,7 +1956,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
@@ -1737,31 +1983,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.)",
@@ -1769,7 +2017,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
@@ -1784,6 +2091,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,
@@ -1795,6 +2105,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
@@ -1827,8 +2182,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");
   }
 
@@ -1851,6 +2212,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,
@@ -1861,10 +2233,61 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
       ...(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 —
@@ -1941,9 +2364,105 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
   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).
@@ -2075,13 +2594,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.)",
@@ -2091,10 +2616,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 : "",
@@ -2120,12 +2655,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`,
     );
@@ -2133,6 +2670,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");
 }
 
@@ -2152,11 +2696,6 @@ const INSTALL_TILE_PROPS: ReadonlyArray<{
   displayName: string;
   tagline: string;
 }> = [
-  {
-    short: "surface",
-    displayName: "Surface",
-    tagline: "Host module for Parachute surfaces — auto-installs Notes on first boot.",
-  },
   {
     short: "scribe",
     displayName: "Scribe",
@@ -2323,11 +2862,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 `/surface/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);
@@ -2373,6 +2911,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);
 }
@@ -2863,6 +3427,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; }