@openparachute/hub 0.5.13 → 0.5.14-rc.2

package/src/setup-wizard.ts

@@ -38,6 +38,8 @@
  */
 
 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";
@@ -221,6 +223,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`
@@ -449,6 +463,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,11 +480,18 @@ 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#267: the typed name now flows end-to-end via
@@ -523,12 +552,154 @@ 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>
+        ${renderScribeSubForm(cloudHost === true)}
         <button type="submit" class="btn btn-primary">Create vault & finish</button>
       </form>
     </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 +738,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>`;
@@ -721,7 +892,7 @@ export interface RenderDoneStepProps {
   /**
    * 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
+   * 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
@@ -738,7 +909,7 @@ export function renderDoneStep(props: RenderDoneStepProps): string {
   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, appInstalled === true, 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 +933,7 @@ export function renderDoneStep(props: RenderDoneStepProps): string {
       </div>
       ${reachable}
       ${startTile}
+      ${renderStarterPromptsSection()}
       ${installSection}
       <section class="done-grid">
         ${mcpTile}
@@ -941,7 +1113,7 @@ function renderMcpTile(
  * command, admin UI, additional module installs).
  *
  * Two shapes:
- *   - **App installed** → primary tile targets `/app/notes/` (the
+ *   - **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
@@ -953,26 +1125,98 @@ function renderMcpTile(
  * "start using parachute" — not three competing tiles where the
  * "real" entry point is buried under the MCP command pre-hub#342.
  */
-function renderStartUsingTile(vaultName: string, appInstalled: boolean): string {
+/**
+ * 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.
+ *
+ * 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.
+ */
+function renderStartUsingTile(
+  vaultName: string,
+  appInstalled: boolean,
+  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}`,
+  );
+  // 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>`
+    : "";
   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>
+    ${localNotesFallback}
+  </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,7 +1323,7 @@ function renderInstallTile(tile: ModuleInstallTileState): string {
  * surface decision.
  */
 const USE_IT_NOW_URLS: Partial<Record<CuratedModuleShort, string>> = {
-  app: "/app/notes/",
+  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
@@ -1215,23 +1459,34 @@ 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
+      // 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("app", deps.manifestPath);
+      const appInstalled = isModuleInstalled("surface", deps.manifestPath);
       const doneProps: RenderDoneStepProps = {
         vaultName,
         hubOrigin: deps.issuer,
@@ -1270,25 +1525,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,
     });
@@ -1596,6 +1859,7 @@ 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);
@@ -1609,7 +1873,185 @@ 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)}`;
+  return redirect(redirectUrl);
+}
+
+/**
+ * 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 });
 }
 
 /**
@@ -1711,9 +2153,9 @@ const INSTALL_TILE_PROPS: ReadonlyArray<{
   tagline: string;
 }> = [
   {
-    short: "app",
-    displayName: "App",
-    tagline: "Host module for Parachute UIs — auto-installs Notes on first boot.",
+    short: "surface",
+    displayName: "Surface",
+    tagline: "Host module for Parachute surfaces — auto-installs Notes on first boot.",
   },
   {
     short: "scribe",
@@ -1844,6 +2286,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}`);
@@ -1882,7 +2325,7 @@ 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
+ * 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`.
  */
@@ -1893,17 +2336,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 +2359,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 {