@agent-native/toolkit 0.221.0-same-host-mcp-20261027-20261027081850 → 0.221.0

package/src/app/onboarding/FirstRunOnboarding.tsx

@@ -18,6 +18,7 @@ import {
   useOnboardingPreviewMode,
   useOnboardingPreviewStep,
 } from "@agent-native/core/client/onboarding/use-preview-mode";
+import { useActionMutation } from "@agent-native/core/client/use-action";
 import { SETTINGS_REDESIGN_FLAG } from "@agent-native/core/feature-flags/registry";
 import {
   buildSettingsRoute,
@@ -27,6 +28,10 @@ import type {
   OnboardingAppProfile,
   OnboardingCapability,
 } from "@agent-native/core/onboarding/types";
+import {
+  FIRST_RUN_BUILDER_CREDITS_V2_EXPERIMENT_ID,
+  FIRST_RUN_BUILDER_CREDITS_V2_FLAG_KEY,
+} from "@agent-native/core/shared";
 import { Badge } from "@agent-native/toolkit/ui/badge";
 import { Button } from "@agent-native/toolkit/ui/button";
 import {
@@ -43,6 +48,7 @@ import {
 } from "@agent-native/toolkit/ui/tooltip";
 import { cn } from "@agent-native/toolkit/utils";
 import {
+  IconAlertCircle,
   IconArrowRight,
   IconChevronDown,
   IconChevronUp,
@@ -77,6 +83,7 @@ import {
 
 type FirstRunScreen = "choice" | "role" | "connecting" | "extension";
 type FirstRunExtensionPlacement = "before-setup" | "after-setup";
+const FIRST_RUN_CREDITS_V2_APP_IDS = new Set(["clips", "design", "slides"]);
 type FirstRunSetupMethodId =
   | "builder_create_account"
   | "builder_sign_in"
@@ -118,6 +125,7 @@ function firstRunStepProperties(
   extensionIndex: number,
   extensionStepIndex: number,
   setupSkippable: boolean,
+  setupRecoverySkippable = false,
 ): Record<string, unknown> {
   // `optional` must match whether the screen offers a skip: Analytics funnels
   // read it to keep a skip from counting as drop-off.
@@ -156,7 +164,10 @@ function firstRunStepProperties(
     flow: "first_run",
     step_id: screen,
     step_index: stepIndex,
-    optional: screen === "role" || (screen === "choice" && setupSkippable),
+    optional:
+      screen === "role" ||
+      (screen === "choice" && setupSkippable) ||
+      (screen === "connecting" && setupRecoverySkippable),
   };
 }
 
@@ -222,17 +233,68 @@ export function FirstRunOnboarding({
   const [setupExperimentDecision, setSetupExperimentDecision] = useState<
     boolean | null
   >(null);
-  const setupVariant = useMemo(
-    () =>
-      (previewMode && getPreviewFirstRunSetupVariant(window.location.search)) ||
-      assignFirstRunSetupVariant(),
-    [previewMode],
+  const [creditsV2Assignment, setCreditsV2Assignment] = useState<{
+    experiment_id: typeof FIRST_RUN_BUILDER_CREDITS_V2_EXPERIMENT_ID;
+    experiment_variant: "control" | "credits";
+  } | null>(null);
+  const [creditsV2ExposureTracked, setCreditsV2ExposureTracked] =
+    useState(false);
+  const creditsV2Flag = useFeatureFlagState(
+    FIRST_RUN_BUILDER_CREDITS_V2_FLAG_KEY,
   );
+  const creditsV2FlagAppliesToApp = FIRST_RUN_CREDITS_V2_APP_IDS.has(
+    profile?.appId ?? "",
+  );
+  const creditsV2Exposure = useActionMutation<
+    {
+      assignment: {
+        experiment_id: string;
+        experiment_variant: string;
+      } | null;
+    },
+    { confirmedVariant?: "control" | "credits" }
+  >("record-first-run-builder-credits-v2-exposure" as never, {
+    uiOnly: true,
+    skipActionQueryInvalidation: true,
+  });
+  const previewCreditsV2 =
+    previewMode &&
+    typeof window !== "undefined" &&
+    new URLSearchParams(window.location.search).get("experiment") === "v2";
+  const creditsV2Enabled =
+    creditsV2FlagAppliesToApp &&
+    creditsV2Flag.status === "ready" &&
+    creditsV2Flag.enabled;
+  const creditsV2FlowEnabled = creditsV2Enabled || previewCreditsV2;
+  const creditsV2FlagPending =
+    !previewMode &&
+    creditsV2FlagAppliesToApp &&
+    creditsV2Flag.status === "loading";
+  const setupVariant = useMemo(() => {
+    const previewVariant =
+      previewMode && getPreviewFirstRunSetupVariant(window.location.search);
+    if (previewCreditsV2) return previewVariant;
+    if (previewVariant) return previewVariant;
+    if (creditsV2FlowEnabled) {
+      return creditsV2Assignment?.experiment_variant ?? null;
+    }
+    return assignFirstRunSetupVariant();
+  }, [
+    creditsV2FlowEnabled,
+    creditsV2Assignment,
+    previewCreditsV2,
+    previewMode,
+    profile?.appId,
+  ]);
+  const setupExperimentId = creditsV2FlowEnabled
+    ? FIRST_RUN_BUILDER_CREDITS_V2_EXPERIMENT_ID
+    : FIRST_RUN_SETUP_EXPERIMENT_ID;
   // The credits arm offers Skip in every app, so analytics must mark the choice step optional there too.
   const choiceSkippable =
     setupSkippable ||
     (setupVariant === "credits" &&
-      (previewMode || setupExperimentDecision === true));
+      (previewMode || setupExperimentDecision === true) &&
+      (!creditsV2Enabled || creditsV2ExposureTracked));
   const [extensionPlacement, setExtensionPlacement] =
     useState<FirstRunExtensionPlacement>("after-setup");
   const [extensionIndex, setExtensionIndex] = useState(0);
@@ -332,6 +394,7 @@ export function FirstRunOnboarding({
       reason = "user_action",
       stepExtensionIndex = extensionIndex,
       stepIndex = extensionStepIndex,
+      optionalOverride?: boolean,
     ) => {
       if (previewMode) return;
       trackOnboardingEvent("onboarding_step_skipped", {
@@ -344,6 +407,9 @@ export function FirstRunOnboarding({
           stepIndex,
           choiceSkippable,
         ),
+        ...(optionalOverride !== undefined
+          ? { optional: optionalOverride }
+          : {}),
         reason,
       });
     },
@@ -365,6 +431,12 @@ export function FirstRunOnboarding({
   const completionInFlightRef = useRef(false);
   const completionRedirectRef = useRef<string | null>(null);
   const setupSkipStartedRef = useRef(false);
+  const creditsV2ExposureStartedRef = useRef(false);
+  const creditsV2ExposureFailedRef = useRef(false);
+  const creditsV2ExposureSettledRef = useRef(false);
+  const creditsV2ExposureTrackedRef = useRef(false);
+  const creditsV2ExposureConfirmationStartedRef = useRef(false);
+  const setupExperimentTimedOutRef = useRef(false);
   const onboardingTerminalRef = useRef(false);
   const abandonmentTrackedRef = useRef(false);
   const onboardingStartedRef = useRef(false);
@@ -437,14 +509,150 @@ export function FirstRunOnboarding({
       trackOnboardingEvent("onboarding_started", { flow: "first_run" });
     }
   }, [canTrackOnboardingScreen, firstRun, previewMode]);
-  // Both arms render a skeleton until the experiment decision is known, and the
-  // credits arm's skip depends on it, so the choice view waits for the decision
-  // and is sent once with its resolved optional flag. Without an assigned arm
-  // no decision is ever made, and the choice UI renders as is.
+  // The v2 choice event waits until the rendered arm has been attributed.
   const choiceStepKnown =
     screen !== "choice" ||
-    setupVariant === null ||
-    setupExperimentDecision !== null;
+    (!creditsV2FlagPending &&
+      (!creditsV2FlowEnabled || setupExperimentDecision !== null) &&
+      (setupVariant === null || setupExperimentDecision !== null) &&
+      (!creditsV2Enabled ||
+        setupExperimentDecision !== true ||
+        creditsV2ExposureTracked));
+  const beginBeforeSetup = useCallback(() => {
+    if (beforeSetupExtensions.length === 0) {
+      setScreen("choice");
+      return;
+    }
+    setExtensionPlacement("before-setup");
+    setExtensionIndex(0);
+    setExtensionStepIndex(0);
+    setScreen("extension");
+  }, [beforeSetupExtensions.length]);
+  const handleFinish = useCallback(
+    (completedScreen: FirstRunScreen | null, track = true) => {
+      if (afterSetupExtensions.length === 0) {
+        void finishOnboarding(completedScreen);
+        return;
+      }
+      if (completedScreen && track) trackFirstRunStepCompleted(completedScreen);
+      setExtensionPlacement("after-setup");
+      setExtensionIndex(0);
+      setExtensionStepIndex(0);
+      setScreen("extension");
+    },
+    [afterSetupExtensions.length, finishOnboarding, trackFirstRunStepCompleted],
+  );
+  const skipFailedBuilderSetup = useCallback(() => {
+    if (setupSkipStartedRef.current || completionInFlightRef.current) return;
+    setupSkipStartedRef.current = true;
+    trackFirstRunStepSkipped(
+      "connecting",
+      "builder_provision_failed",
+      extensionIndex,
+      extensionStepIndex,
+      true,
+    );
+    if (setupSkippable) completionRedirectRef.current = "/record";
+    handleFinish(null);
+  }, [
+    extensionIndex,
+    extensionStepIndex,
+    handleFinish,
+    setupSkippable,
+    trackFirstRunStepSkipped,
+  ]);
+  const handleBuilderConnected = useCallback(() => {
+    trackFirstRunSetupOutcome(builderSetupAttemptRef.current, "connected");
+    builderSetupAttemptRef.current = null;
+    setupAttemptRef.current = null;
+    trackFirstRunStepCompleted("choice");
+    trackFirstRunStepCompleted("connecting");
+    handleFinish(null);
+  }, [handleFinish, trackFirstRunStepCompleted]);
+  const connectFlow = useBuilderConnectFlow({
+    enabled: firstRun && !previewMode,
+    provisionAccount: true,
+    trackingSource: "first_run_onboarding",
+    trackingFlow: "connect_llm",
+    onConnected: handleBuilderConnected,
+  });
+  const accountExists = connectFlow.accountExists && !connectFlow.connecting;
+  const provisioning = builderConnectionMode === "provision" && !accountExists;
+  const provisioningFailed =
+    provisioning &&
+    !connectFlow.connecting &&
+    Boolean(connectFlow.terminalError);
+  const connectionFailed = provisioningFailed;
+  useEffect(() => {
+    if (
+      previewMode ||
+      !firstRun ||
+      !canTrackOnboardingScreen ||
+      screen !== "choice" ||
+      !creditsV2Enabled ||
+      setupExperimentDecision !== true ||
+      creditsV2ExposureTrackedRef.current ||
+      !creditsV2Assignment
+    ) {
+      return;
+    }
+    creditsV2ExposureTrackedRef.current = true;
+    setOnboardingExperiment({
+      id: creditsV2Assignment.experiment_id,
+      variant: creditsV2Assignment.experiment_variant,
+    });
+    setCreditsV2ExposureTracked(true);
+    trackOnboardingEvent("onboarding_experiment_exposed", {
+      flow: "first_run",
+      step_id: "choice",
+      experiment_id: creditsV2Assignment.experiment_id,
+      experiment_variant: creditsV2Assignment.experiment_variant,
+    });
+    if (creditsV2ExposureConfirmationStartedRef.current) return;
+    creditsV2ExposureConfirmationStartedRef.current = true;
+    const persistExposure = async () => {
+      let lastError: unknown;
+      // A write can commit even when its response is lost, so retry the idempotent assignment to reconcile it.
+      for (const delayMs of [0, 0, 1_000, 5_000, 30_000]) {
+        if (delayMs > 0) {
+          await new Promise<void>((resolve) =>
+            window.setTimeout(resolve, delayMs),
+          );
+        }
+        try {
+          const { assignment } = await creditsV2Exposure.mutateAsync({
+            confirmedVariant: creditsV2Assignment.experiment_variant,
+          });
+          if (
+            assignment?.experiment_id !== creditsV2Assignment.experiment_id ||
+            assignment.experiment_variant !==
+              creditsV2Assignment.experiment_variant
+          ) {
+            throw new Error(
+              "The server did not persist the displayed first-run Builder credits v2 assignment.",
+            );
+          }
+          return;
+        } catch (error: unknown) {
+          lastError = error;
+        }
+      }
+      console.error(
+        "Failed to persist first-run Builder credits v2 exposure:",
+        lastError,
+      );
+    };
+    void persistExposure();
+  }, [
+    canTrackOnboardingScreen,
+    creditsV2Assignment,
+    creditsV2Enabled,
+    creditsV2Exposure.mutateAsync,
+    firstRun,
+    previewMode,
+    setupExperimentDecision,
+    screen,
+  ]);
   useEffect(() => {
     if (
       previewMode ||
@@ -463,8 +671,14 @@ export function FirstRunOnboarding({
       extensionIndex,
       extensionStepIndex,
       choiceSkippable,
+      provisioningFailed,
     );
-    const key = [step.step_id, step.extension_id, step.step_index].join(":");
+    const key = [
+      step.step_id,
+      step.extension_id,
+      step.step_index,
+      step.optional,
+    ].join(":");
     if (stepViewRef.current?.key !== key) {
       stepViewRef.current = { key, id: createOnboardingCorrelationId() };
     }
@@ -485,6 +699,7 @@ export function FirstRunOnboarding({
     previewMode,
     canTrackOnboardingScreen,
     choiceStepKnown,
+    provisioningFailed,
     screen,
   ]);
   useEffect(() => {
@@ -507,6 +722,7 @@ export function FirstRunOnboarding({
           extensionIndex,
           extensionStepIndex,
           choiceSkippable,
+          provisioningFailed,
         ),
         reason: "page_exit",
       });
@@ -524,46 +740,8 @@ export function FirstRunOnboarding({
     canTrackOnboardingScreen,
     screen,
     choiceSkippable,
+    provisioningFailed,
   ]);
-  const beginBeforeSetup = useCallback(() => {
-    if (beforeSetupExtensions.length === 0) {
-      setScreen("choice");
-      return;
-    }
-    setExtensionPlacement("before-setup");
-    setExtensionIndex(0);
-    setExtensionStepIndex(0);
-    setScreen("extension");
-  }, [beforeSetupExtensions.length]);
-  const handleFinish = useCallback(
-    (completedScreen: FirstRunScreen | null, track = true) => {
-      if (afterSetupExtensions.length === 0) {
-        void finishOnboarding(completedScreen);
-        return;
-      }
-      if (completedScreen && track) trackFirstRunStepCompleted(completedScreen);
-      setExtensionPlacement("after-setup");
-      setExtensionIndex(0);
-      setExtensionStepIndex(0);
-      setScreen("extension");
-    },
-    [afterSetupExtensions.length, finishOnboarding, trackFirstRunStepCompleted],
-  );
-  const handleBuilderConnected = useCallback(() => {
-    trackFirstRunSetupOutcome(builderSetupAttemptRef.current, "connected");
-    builderSetupAttemptRef.current = null;
-    setupAttemptRef.current = null;
-    trackFirstRunStepCompleted("choice");
-    trackFirstRunStepCompleted("connecting");
-    handleFinish(null);
-  }, [handleFinish, trackFirstRunStepCompleted]);
-  const connectFlow = useBuilderConnectFlow({
-    enabled: firstRun && !previewMode,
-    provisionAccount: true,
-    trackingSource: "first_run_onboarding",
-    trackingFlow: "connect_llm",
-    onConnected: handleBuilderConnected,
-  });
   const builderStatusReadCount = connectFlow.statusReadSettledCount ?? 0;
   useEffect(() => {
     const startedAt = retryingBuilderStatusAtCountRef.current;
@@ -587,12 +765,13 @@ export function FirstRunOnboarding({
       trackFirstRunSetupOutcome(attempt, "failed", "account_exists");
       return;
     }
-    if (connectFlow.terminalError) {
+    if (connectFlow.terminalError || connectFlow.statusUnavailable) {
       trackFirstRunSetupOutcome(attempt, "failed", "connection_error");
     }
   }, [
     connectFlow.accountExists,
     connectFlow.connecting,
+    connectFlow.statusUnavailable,
     connectFlow.terminalError,
   ]);
   // Preview never fetches status, so show the activation path it would offer.
@@ -608,12 +787,15 @@ export function FirstRunOnboarding({
   const setupExperimentEligible =
     setupStatusSettled &&
     canActivateBuilderFreeCredits &&
-    !connectFlow.configured;
+    !connectFlow.configured &&
+    !connectFlow.statusUnavailable;
   useEffect(() => {
     if (
       previewMode ||
       !firstRun ||
       screen !== "choice" ||
+      creditsV2FlagPending ||
+      creditsV2FlowEnabled ||
       !setupVariant ||
       !setupStatusSettled ||
       setupExperimentDecision !== null
@@ -622,12 +804,14 @@ export function FirstRunOnboarding({
     }
     if (setupExperimentEligible) {
       setOnboardingExperiment({
-        id: FIRST_RUN_SETUP_EXPERIMENT_ID,
+        id: setupExperimentId,
         variant: setupVariant,
       });
       trackOnboardingEvent("onboarding_experiment_exposed", {
         flow: "first_run",
         step_id: "choice",
+        experiment_id: setupExperimentId,
+        experiment_variant: setupVariant,
       });
     }
     setSetupExperimentDecision(setupExperimentEligible);
@@ -635,11 +819,73 @@ export function FirstRunOnboarding({
     firstRun,
     previewMode,
     screen,
+    creditsV2FlagPending,
+    creditsV2FlowEnabled,
     setupExperimentEligible,
     setupExperimentDecision,
     setupStatusSettled,
+    setupExperimentId,
     setupVariant,
   ]);
+  useEffect(() => {
+    if (
+      previewMode ||
+      !firstRun ||
+      screen !== "choice" ||
+      !creditsV2Enabled ||
+      !setupStatusSettled ||
+      setupExperimentTimedOutRef.current ||
+      setupExperimentDecision === true
+    ) {
+      return;
+    }
+    if (!setupExperimentEligible) {
+      creditsV2ExposureFailedRef.current = false;
+      setSetupExperimentDecision(false);
+      return;
+    }
+    if (creditsV2ExposureFailedRef.current) return;
+    if (creditsV2ExposureStartedRef.current) return;
+    creditsV2ExposureStartedRef.current = true;
+    creditsV2ExposureSettledRef.current = false;
+    setSetupExperimentDecision(null);
+    void creditsV2Exposure
+      .mutateAsync({})
+      .then(({ assignment }) => {
+        creditsV2ExposureSettledRef.current = true;
+        if (setupExperimentTimedOutRef.current) return;
+        if (
+          assignment?.experiment_id !==
+            FIRST_RUN_BUILDER_CREDITS_V2_EXPERIMENT_ID ||
+          (assignment.experiment_variant !== "control" &&
+            assignment.experiment_variant !== "credits")
+        ) {
+          setSetupExperimentDecision(false);
+          return;
+        }
+        setCreditsV2Assignment({
+          experiment_id: FIRST_RUN_BUILDER_CREDITS_V2_EXPERIMENT_ID,
+          experiment_variant: assignment.experiment_variant,
+        });
+        setSetupExperimentDecision(true);
+      })
+      .catch(() => {
+        creditsV2ExposureSettledRef.current = true;
+        if (setupExperimentTimedOutRef.current) return;
+        creditsV2ExposureStartedRef.current = false;
+        creditsV2ExposureFailedRef.current = true;
+        setSetupExperimentDecision(false);
+      });
+  }, [
+    creditsV2Enabled,
+    creditsV2Exposure.mutateAsync,
+    firstRun,
+    previewMode,
+    screen,
+    setupExperimentDecision,
+    setupExperimentEligible,
+    setupStatusSettled,
+  ]);
   // A stalled Builder status read must not leave the setup screen blank. Past
   // the limit the person gets the existing page and stays out of the
   // experiment, identically in both arms, so exposure counts stay honest.
@@ -648,17 +894,28 @@ export function FirstRunOnboarding({
       previewMode ||
       !firstRun ||
       screen !== "choice" ||
-      !setupVariant ||
+      creditsV2FlagPending ||
+      (!setupVariant && !creditsV2FlowEnabled) ||
       setupExperimentDecision !== null
     ) {
       return;
     }
-    const timer = window.setTimeout(
-      () => setSetupExperimentDecision((decision) => decision ?? false),
-      SETUP_EXPERIMENT_DECISION_TIMEOUT_MS,
-    );
+    const timer = window.setTimeout(() => {
+      if (creditsV2ExposureSettledRef.current) return;
+      setupExperimentTimedOutRef.current = true;
+      setSetupExperimentDecision((decision) => decision ?? false);
+    }, SETUP_EXPERIMENT_DECISION_TIMEOUT_MS);
     return () => window.clearTimeout(timer);
-  }, [firstRun, previewMode, screen, setupExperimentDecision, setupVariant]);
+  }, [
+    creditsV2FlowEnabled,
+    creditsV2FlagPending,
+    firstRun,
+    previewMode,
+    screen,
+    setupExperimentDecision,
+    setupStatusSettled,
+    setupVariant,
+  ]);
   const retryOnboardingCompletion = useCallback(() => {
     const attempt = completionAttemptRef.current;
     void finishOnboarding(
@@ -887,9 +1144,12 @@ export function FirstRunOnboarding({
     );
 
     const inCreditsArm = setupVariant === "credits";
-    // Both arms must wait: the control setup actions can be used as soon as
-    // they render, so exposure has to be recorded before either arm is usable.
-    if (!previewMode && setupVariant && setupExperimentDecision === null) {
+    if (
+      !previewMode &&
+      (creditsV2FlagPending ||
+        (creditsV2FlowEnabled && setupExperimentDecision === null) ||
+        (setupVariant && setupExperimentDecision === null))
+    ) {
       return <OnboardingSkeleton />;
     }
     const creditsEligible =
@@ -1093,6 +1353,17 @@ export function FirstRunOnboarding({
               >
                 {t("agentChat.onboarding.builderExistingAccount")}
               </button>
+              {creditsV2FlowEnabled && (
+                <button
+                  type="button"
+                  data-testid="first-run-credits-own-api-keys"
+                  className="min-h-7 text-xs font-medium text-muted-foreground underline underline-offset-4 transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  onClick={() => void handleOpenSettings()}
+                  disabled={connectFlow.connecting}
+                >
+                  {t("agentChat.onboarding.creditsUseOwnApiKeys")}
+                </button>
+              )}
               <p className="text-xs leading-5 text-muted-foreground">
                 {t("agentChat.onboarding.creditsFinePrint")}{" "}
                 <a
@@ -1141,74 +1412,88 @@ export function FirstRunOnboarding({
               </div>
             )}
             <div className="fixed bottom-6 right-6 z-10">
-              <Popover open={skipConfirmOpen} onOpenChange={setSkipConfirmOpen}>
-                <PopoverTrigger asChild>
-                  <button
-                    type="button"
-                    data-testid="first-run-credits-skip"
-                    className="inline-flex min-h-6 items-center px-2 rounded-sm text-xs font-medium text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-                  >
-                    {t("agentChat.onboarding.creditsSkip")}
-                  </button>
-                </PopoverTrigger>
-                <PopoverContent
-                  side="top"
-                  align="end"
-                  portalled={false}
-                  aria-labelledby="first-run-credits-skip-title"
-                  aria-describedby="first-run-credits-skip-body"
-                  className="w-96 max-w-[calc(100vw-2rem)] space-y-3 p-4 text-left"
-                  onOpenAutoFocus={(event) => {
-                    event.preventDefault();
-                    skipGoBackRef.current?.focus();
-                  }}
+              {creditsV2FlowEnabled ? (
+                <button
+                  type="button"
+                  data-testid="first-run-credits-skip"
+                  className="inline-flex min-h-6 items-center px-2 rounded-sm text-xs font-medium text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  onClick={skipSetup}
                 >
-                  <div className="space-y-1">
-                    <p
-                      id="first-run-credits-skip-title"
-                      className="text-sm font-semibold text-foreground"
-                    >
-                      {t("agentChat.onboarding.creditsSkipConfirmTitle")}
-                    </p>
-                    <p
-                      id="first-run-credits-skip-body"
-                      className="text-xs leading-5 text-muted-foreground"
-                    >
-                      {t("agentChat.onboarding.creditsSkipConfirmBody")}
-                    </p>
-                  </div>
-                  <div className="flex flex-wrap items-center justify-between gap-2">
-                    <Button
+                  {t("agentChat.onboarding.creditsSkip")}
+                </button>
+              ) : (
+                <Popover
+                  open={skipConfirmOpen}
+                  onOpenChange={setSkipConfirmOpen}
+                >
+                  <PopoverTrigger asChild>
+                    <button
                       type="button"
-                      variant="ghost"
-                      size="sm"
-                      className="px-0 text-muted-foreground hover:bg-transparent hover:text-foreground"
-                      onClick={() => void handleOpenSettings()}
+                      data-testid="first-run-credits-skip"
+                      className="inline-flex min-h-6 items-center px-2 rounded-sm text-xs font-medium text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
                     >
-                      {t("agentChat.onboarding.creditsUseCustomKeys")}
-                    </Button>
-                    <div className="flex flex-wrap justify-end gap-2">
-                      <Button
-                        type="button"
-                        variant="secondary"
-                        size="sm"
-                        data-testid="first-run-credits-skip-confirm"
-                        onClick={skipSetup}
+                      {t("agentChat.onboarding.creditsSkip")}
+                    </button>
+                  </PopoverTrigger>
+                  <PopoverContent
+                    side="top"
+                    align="end"
+                    portalled={false}
+                    aria-labelledby="first-run-credits-skip-title"
+                    aria-describedby="first-run-credits-skip-body"
+                    className="w-96 max-w-[calc(100vw-2rem)] space-y-3 p-4 text-left"
+                    onOpenAutoFocus={(event) => {
+                      event.preventDefault();
+                      skipGoBackRef.current?.focus();
+                    }}
+                  >
+                    <div className="space-y-1">
+                      <p
+                        id="first-run-credits-skip-title"
+                        className="text-sm font-semibold text-foreground"
                       >
-                        {t("agentChat.onboarding.creditsSkipAnyway")}
-                      </Button>
+                        {t("agentChat.onboarding.creditsSkipConfirmTitle")}
+                      </p>
+                      <p
+                        id="first-run-credits-skip-body"
+                        className="text-xs leading-5 text-muted-foreground"
+                      >
+                        {t("agentChat.onboarding.creditsSkipConfirmBody")}
+                      </p>
+                    </div>
+                    <div className="flex flex-wrap items-center justify-between gap-2">
                       <Button
                         type="button"
+                        variant="ghost"
                         size="sm"
-                        ref={skipGoBackRef}
-                        onClick={() => setSkipConfirmOpen(false)}
+                        className="px-0 text-muted-foreground hover:bg-transparent hover:text-foreground"
+                        onClick={() => void handleOpenSettings()}
                       >
-                        {t("agentChat.onboarding.creditsSkipGoBack")}
+                        {t("agentChat.onboarding.creditsUseCustomKeys")}
                       </Button>
+                      <div className="flex flex-wrap justify-end gap-2">
+                        <Button
+                          type="button"
+                          variant="secondary"
+                          size="sm"
+                          data-testid="first-run-credits-skip-confirm"
+                          onClick={skipSetup}
+                        >
+                          {t("agentChat.onboarding.creditsSkipAnyway")}
+                        </Button>
+                        <Button
+                          type="button"
+                          size="sm"
+                          ref={skipGoBackRef}
+                          onClick={() => setSkipConfirmOpen(false)}
+                        >
+                          {t("agentChat.onboarding.creditsSkipGoBack")}
+                        </Button>
+                      </div>
                     </div>
-                  </div>
-                </PopoverContent>
-              </Popover>
+                  </PopoverContent>
+                </Popover>
+              )}
             </div>
           </div>
         </OnboardingShell>
@@ -1375,8 +1660,6 @@ export function FirstRunOnboarding({
     );
   }
 
-  const accountExists = connectFlow.accountExists && !connectFlow.connecting;
-  const provisioning = builderConnectionMode === "provision" && !accountExists;
   const returnToSetupChoice = () => setScreen("choice");
   return (
     <OnboardingShell
@@ -1391,23 +1674,37 @@ export function FirstRunOnboarding({
         aria-live="polite"
         aria-busy={connectFlow.connecting}
       >
-        <div className="flex size-10 items-center justify-center rounded-full bg-primary/10 text-primary">
-          {accountExists ? (
-            <IconKey size={19} />
-          ) : (
-            <IconLoader2 className="animate-spin" size={19} />
+        <div
+          className={cn(
+            "flex size-10 items-center justify-center rounded-full",
+            connectionFailed
+              ? "bg-destructive/10 text-destructive"
+              : "bg-primary/10 text-primary",
           )}
+        >
+          {accountExists ? <IconKey size={19} /> : null}
+          {connectionFailed ? <IconAlertCircle size={19} /> : null}
+          {!accountExists && !connectionFailed ? (
+            <IconLoader2 className="animate-spin" size={19} />
+          ) : null}
         </div>
         <h1 className="mt-5 text-xl font-semibold tracking-[-0.04em]">
           {accountExists
             ? t("agentChat.onboarding.builderAccountExistsTitle")
-            : provisioning
-              ? t("agentChat.onboarding.creditsActivating")
-              : t("agentChat.onboarding.builderConnecting")}
+            : provisioningFailed
+              ? t("agentChat.settingsShell.builder.setupFailed")
+              : provisioning
+                ? t("agentChat.onboarding.creditsActivating")
+                : t("agentChat.onboarding.builderConnecting")}
         </h1>
-        <p className="mt-2 text-sm text-muted-foreground">
+        <p
+          className="mt-2 text-sm text-muted-foreground"
+          role={connectionFailed ? "alert" : undefined}
+        >
           {accountExists ? (
             t("agentChat.onboarding.builderAccountExistsDescription")
+          ) : provisioningFailed ? (
+            t("agentChat.onboarding.builderProvisionFailedDetail")
           ) : provisioning ? (
             <>
               {t("agentChat.onboarding.builderProvisioningDescription")}
@@ -1444,18 +1741,20 @@ export function FirstRunOnboarding({
           </button>
         ) : (
           <>
-            <div className="mt-7 w-full rounded-xl bg-muted/35 p-4 text-left">
-              <div className="flex items-center justify-between gap-3">
-                <Skeleton className="h-3 w-28" />
-                <Skeleton className="h-5 w-16 rounded-full" />
-              </div>
-              <Skeleton className="mt-4 h-8 w-full" />
-              <div className="mt-3 grid grid-cols-3 gap-2">
-                <Skeleton className="h-7 w-full" />
-                <Skeleton className="h-7 w-full" />
-                <Skeleton className="h-7 w-full" />
+            {connectFlow.connecting ? (
+              <div className="mt-7 w-full rounded-xl bg-muted/35 p-4 text-left">
+                <div className="flex items-center justify-between gap-3">
+                  <Skeleton className="h-3 w-28" />
+                  <Skeleton className="h-5 w-16 rounded-full" />
+                </div>
+                <Skeleton className="mt-4 h-8 w-full" />
+                <div className="mt-3 grid grid-cols-3 gap-2">
+                  <Skeleton className="h-7 w-full" />
+                  <Skeleton className="h-7 w-full" />
+                  <Skeleton className="h-7 w-full" />
+                </div>
               </div>
-            </div>
+            ) : null}
             {connectFlow.connecting &&
               (builderCancelRequested ? (
                 <div className="mt-4 flex flex-col items-center gap-2">
@@ -1502,6 +1801,7 @@ export function FirstRunOnboarding({
               </p>
             )}
             {!connectFlow.connecting &&
+              !provisioningFailed &&
               (connectFlow.statusUnavailable || connectFlow.terminalError) && (
                 <div className="mt-4 flex flex-col items-center gap-2">
                   <p className="text-xs text-destructive" role="alert">
@@ -1529,6 +1829,34 @@ export function FirstRunOnboarding({
                   </button>
                 </div>
               )}
+            {provisioningFailed ? (
+              <div className="mt-4 flex w-full flex-col items-center gap-2">
+                <button
+                  type="button"
+                  data-testid="first-run-retry-builder"
+                  className={cn(ONBOARDING_PRIMARY_BUTTON_CLASS, "w-full")}
+                  onClick={() => handleBuilder(true)}
+                >
+                  {t("agentChat.settingsShell.builder.retry")}
+                </button>
+                <button
+                  type="button"
+                  data-testid="first-run-open-key-settings-after-failure"
+                  className={cn(secondaryButtonClass, "w-full")}
+                  onClick={() => void handleOpenSettings()}
+                >
+                  {t("agentChat.onboarding.openAiKeySettings")}
+                </button>
+                <button
+                  type="button"
+                  data-testid="first-run-skip-builder-after-failure"
+                  className="inline-flex min-h-9 items-center justify-center rounded-lg px-2.5 text-xs font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  onClick={skipFailedBuilderSetup}
+                >
+                  {t("agentChat.onboarding.skipForNow")}
+                </button>
+              </div>
+            ) : null}
             {!connectFlow.connecting &&
               !connectFlow.statusUnavailable &&
               !connectFlow.terminalError && (