From 4c69fae3c11e215212c072fd47c21e1f49d509dc Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 18:27:11 -0800
Subject: [PATCH 01/22] feat(web): replace the setup wizard with a single
 Welcome page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First run was a three-step modal (Connect, Agents, Projects). It asked a
one-computer user to connect the computer they were already on, listed only
Codex and Claude, and put optional import behind a 46-row list.

The Welcome page shows the computer's agents, its Claude Code and Codex
projects, and the phone app on one page. Agents found on the computer come
first; everything else sits in an "Add more agents" fold with the ACP
Registry. Projects are one checkbox with a Review list. Phone setup is one
row that opens store QR codes and T3 Connect sign-in. Start waits for one
ready agent; Skip for now finishes without one. Settings → About reopens it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ...sx => WelcomePage.import.browser.test.tsx} |  123 +-
 .../{WelcomeWizard.tsx => WelcomePage.tsx}    | 1410 +++++++----------
 .../settings/MobileAppSettingsRow.tsx         |    4 +-
 .../components/settings/SettingsPanels.tsx    |    9 +
 .../src/components/settings/settingsSearch.ts |    6 +
 .../targetEnvironment.logic.test.ts           |   51 -
 .../src/onboarding/targetEnvironment.logic.ts |   37 -
 .../onboarding/welcomeAgents.logic.test.ts    |   54 +
 .../web/src/onboarding/welcomeAgents.logic.ts |   36 +
 apps/web/src/routes/welcome.tsx               |   42 +-
 docs/user/welcome-page.md                     |   89 ++
 docs/user/welcome-wizard.md                   |  101 --
 12 files changed, 823 insertions(+), 1139 deletions(-)
 rename apps/web/src/components/onboarding/{WelcomeWizard.import.browser.test.tsx => WelcomePage.import.browser.test.tsx} (78%)
 rename apps/web/src/components/onboarding/{WelcomeWizard.tsx => WelcomePage.tsx} (52%)
 delete mode 100644 apps/web/src/onboarding/targetEnvironment.logic.test.ts
 delete mode 100644 apps/web/src/onboarding/targetEnvironment.logic.ts
 create mode 100644 apps/web/src/onboarding/welcomeAgents.logic.test.ts
 create mode 100644 apps/web/src/onboarding/welcomeAgents.logic.ts
 create mode 100644 docs/user/welcome-page.md
 delete mode 100644 docs/user/welcome-wizard.md

diff --git a/apps/web/src/components/onboarding/WelcomeWizard.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
similarity index 78%
rename from apps/web/src/components/onboarding/WelcomeWizard.import.browser.test.tsx
rename to apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index c55691d9ca5cc..900edc1cda5bf 100644
--- a/apps/web/src/components/onboarding/WelcomeWizard.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -4,9 +4,12 @@ import {
   AuthOrchestrationReadScope,
   EnvironmentId,
   ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type AgentSessionProjectCandidate,
   type AuthEnvironmentScope,
   type AuthSessionState,
+  type ServerProvider,
 } from "@t3tools/contracts";
 import { AsyncResult, Atom } from "effect/reactivity";
 import { expect, it, vi } from "vite-plus/test";
@@ -21,8 +24,6 @@ type CreateProjectInput = {
   input: { projectId: ProjectId; workspaceRoot: string };
 };
 const state = vi.hoisted(() => ({
-  selectedEnvironment: "primary",
-  addedEnvironments: [] as string[],
   sessions: new Map<string, unknown>(),
   projects: null as unknown,
   providers: null as unknown,
@@ -31,7 +32,6 @@ const state = vi.hoisted(() => ({
   createProject: vi.fn(),
   importThreads: vi.fn(),
   refreshProviders: vi.fn(),
-  connectPairing: vi.fn(),
   completeOnboarding: vi.fn(),
   onDone: vi.fn(),
   scan: vi.fn(),
@@ -68,9 +68,7 @@ vi.mock(import("../../state/environments"), async (original) => {
   return {
     ...(await original()),
     usePrimaryEnvironment: (() => primary) as never,
-    useEnvironments: (() => ({
-      environments: [state.selectedEnvironment, ...state.addedEnvironments].map(environment),
-    })) as never,
+    useEnvironments: (() => ({ environments: [primary] })) as never,
   };
 });
 vi.mock(import("../../state/server"), async (original) => {
@@ -116,15 +114,10 @@ vi.mock(import("../../onboarding/useProjectScans"), async (original) => ({
       };
     }),
 }));
-vi.mock(import("../../connection/onboarding"), async (original) => ({
-  ...(await original()),
-  connectPairing: "connectPairing" as never,
-}));
 vi.mock(import("../../state/use-atom-command"), async (original) => ({
   ...(await original()),
-  useAtomCommand: ((
-    command: "createProject" | "importThreads" | "refreshProviders" | "connectPairing",
-  ) => state[command]) as never,
+  useAtomCommand: ((command: "createProject" | "importThreads" | "refreshProviders") =>
+    state[command]) as never,
 }));
 vi.mock(import("../settings/ChatGptWelcomeCoordinator"), async (original) => ({
   ...(await original()),
@@ -132,10 +125,22 @@ vi.mock(import("../settings/ChatGptWelcomeCoordinator"), async (original) => ({
 }));
 
 import { appAtomRegistry } from "../../rpc/atomRegistry";
-import { WelcomeWizard } from "./WelcomeWizard";
+import { WelcomePage } from "./WelcomePage";
 
 const primaryId = EnvironmentId.make("primary");
-const remoteId = EnvironmentId.make("remote");
+const readyClaude: ServerProvider = {
+  instanceId: ProviderInstanceId.make("claudeAgent"),
+  driver: ProviderDriverKind.make("claudeAgent"),
+  enabled: true,
+  installed: true,
+  version: "1.0.0",
+  status: "ready",
+  auth: { status: "authenticated" },
+  checkedAt: "2026-01-01T00:00:00.000Z",
+  models: [],
+  slashCommands: [],
+  skills: [],
+};
 const permissionMessage = "This connection cannot import projects or thread history.";
 
 function session(scopes: ReadonlyArray<AuthEnvironmentScope>): AuthSessionState {
@@ -235,36 +240,20 @@ async function click(label: string) {
   await act(async () => target.click());
 }
 
-async function clickStage(label: string) {
-  const stage = document.querySelector<HTMLButtonElement>(`button[aria-label="${label}"]`);
-  expect(stage?.disabled).toBe(false);
-  await act(async () => stage?.click());
-}
-
-async function mountImport(remote = false) {
-  state.selectedEnvironment = remote ? "remote" : "primary";
-  await using stack = new AsyncDisposableStack();
-  const screen = stack.use(
-    await render(
-      <RegistryContext.Provider value={appAtomRegistry}>
-        <WelcomeWizard localAvailable={!remote} onDone={state.onDone} />
-      </RegistryContext.Provider>,
-    ),
+async function mountWelcome() {
+  return render(
+    <RegistryContext.Provider value={appAtomRegistry}>
+      <WelcomePage environmentId={primaryId} onDone={state.onDone} />
+    </RegistryContext.Provider>,
   );
-  await click("Continue");
-  await click("Continue");
-  expect(pageText()).toContain("Import your projects");
-  stack.move();
-  return screen;
 }
 
 // The mocked modules read `state`, so every test starts by replacing all of it.
 // Returns the clock spy so each test can `using` it; the spy would otherwise outlive the test.
 function setup() {
   const now = vi.spyOn(Date, "now").mockReturnValue(NOW);
-  state.addedEnvironments = [];
   state.sessions.clear();
-  for (const id of [primaryId, remoteId]) {
+  for (const id of [primaryId]) {
     state.sessions.set(
       id,
       Atom.make<SessionResult>(AsyncResult.success(session([AuthOrchestrationOperateScope]))).pipe(
@@ -273,7 +262,7 @@ function setup() {
     );
   }
   state.projects = Atom.make<ReadonlyArray<Project>>([]).pipe(Atom.keepAlive);
-  state.providers = Atom.make<ReadonlyArray<never>>([]).pipe(Atom.keepAlive);
+  state.providers = Atom.make<ReadonlyArray<ServerProvider>>([readyClaude]).pipe(Atom.keepAlive);
   state.config = Atom.make(null).pipe(Atom.keepAlive);
   state.candidates = [candidate("/projects/first"), candidate("/projects/second")];
   state.createProject
@@ -283,7 +272,6 @@ function setup() {
     .mockReset()
     .mockResolvedValue(AsyncResult.success({ importedCount: 1, skippedCount: 0 }));
   state.refreshProviders.mockReset().mockResolvedValue(AsyncResult.success(undefined));
-  state.connectPairing.mockReset().mockResolvedValue(AsyncResult.success(remoteId));
   state.completeOnboarding.mockReset().mockResolvedValue(undefined);
   state.onDone.mockReset();
   state.scan.mockReset();
@@ -292,34 +280,6 @@ function setup() {
   return now;
 }
 
-it("keeps the project selection after going back a stage", async () => {
-  using _now = setup();
-  await using _screen = await mountImport();
-  await click("Select none");
-  expect(pageText()).toContain("0 of 2 selected");
-
-  await clickStage("Agents, step 2");
-  await click("Continue");
-  expect(pageText()).toContain("Import your projects");
-  expect(pageText()).toContain("0 of 2 selected");
-});
-
-it("ticks the recent projects of a computer added after the selection changed", async () => {
-  using _now = setup();
-  await using _screen = await mountImport();
-  await click("Select none");
-
-  state.addedEnvironments = ["remote"];
-  await clickStage("Connect, step 1");
-  await click("Continue");
-  await click("Continue");
-  expect(pageText()).toContain("2 of 4 selected");
-
-  await click("Import 2 projects");
-  const created = state.createProject.mock.calls as Array<[CreateProjectInput]>;
-  expect(created.map(([call]) => call.environmentId)).toEqual([remoteId, remoteId]);
-});
-
 it("rechecks after project creation and can retry its history without recreating the project", async () => {
   using _now = setup();
   const creation = deferred<void>();
@@ -327,8 +287,8 @@ it("rechecks after project creation and can retry its history without recreating
     await creation.promise;
     return recordProject(input);
   });
-  await using _screen = await mountImport();
-  await click("Import 2 projects");
+  await using _screen = await mountWelcome();
+  await click("Add 2 projects and start");
   expect(state.createProject).toHaveBeenCalledOnce();
   await act(async () => {
     setGrant(primaryId, false);
@@ -341,7 +301,7 @@ it("rechecks after project creation and can retry its history without recreating
   expect(pageText()).toContain(permissionMessage);
 
   await act(async () => setGrant(primaryId, true));
-  await click("Import 2 projects");
+  await click("Add 2 projects and start");
   expect(state.createProject).toHaveBeenCalledTimes(2);
   expect(state.importThreads).toHaveBeenCalledTimes(2);
   expect(state.onDone).toHaveBeenCalledOnce();
@@ -354,8 +314,8 @@ it("completes accepted imports when permission is revoked after the final server
   state.importThreads.mockImplementationOnce(async () =>
     AsyncResult.success(await imported.promise),
   );
-  await using _screen = await mountImport();
-  await click("Import 1 project");
+  await using _screen = await mountWelcome();
+  await click("Add 1 project and start");
   await act(async () => {
     setGrant(primaryId, false);
     imported.resolve({ importedCount: 1, skippedCount: 0 });
@@ -374,15 +334,26 @@ it("finishes setup without landing when the imported project never reaches the c
   state.createProject.mockResolvedValue(AsyncResult.success(undefined));
   state.waitForProject.mockRejectedValue(new Error("The project did not appear."));
   state.completeOnboarding.mockRejectedValueOnce(new Error("offline"));
-  await using _screen = await mountImport();
+  await using _screen = await mountWelcome();
 
-  await click("Import 1 project");
+  await click("Add 1 project and start");
   await vi.waitFor(() => expect(state.completeOnboarding).toHaveBeenCalledOnce());
   // A failed completion hands the step back instead of leaving it importing.
-  await vi.waitFor(() => expect(button("Import 1 project").disabled).toBe(false));
+  await vi.waitFor(() => expect(button("Add 1 project and start").disabled).toBe(false));
   expect(state.onDone).not.toHaveBeenCalled();
 
-  await click("Import 1 project");
+  await click("Add 1 project and start");
   await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
   expect(state.onDone).toHaveBeenCalledWith(undefined);
 });
+
+it("waits for a ready agent to start, and Skip for now still finishes setup", async () => {
+  using _now = setup();
+  appAtomRegistry.set(state.providers as Atom.Writable<ReadonlyArray<ServerProvider>>, []);
+  await using _screen = await mountWelcome();
+  expect(button("Add 2 projects and start").disabled).toBe(true);
+
+  await click("Skip for now");
+  await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
+  expect(state.createProject).toHaveBeenCalledTimes(2);
+});
diff --git a/apps/web/src/components/onboarding/WelcomeWizard.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
similarity index 52%
rename from apps/web/src/components/onboarding/WelcomeWizard.tsx
rename to apps/web/src/components/onboarding/WelcomePage.tsx
index c4647e7cf282a..0804da9c022d2 100644
--- a/apps/web/src/components/onboarding/WelcomeWizard.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -10,10 +10,7 @@ import type {
   ServerProvider,
 } from "@t3tools/contracts";
 import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime/environment";
-import {
-  isAtomCommandInterrupted,
-  squashAtomCommandFailure,
-} from "@t3tools/client-runtime/state/runtime";
+import { isAtomCommandInterrupted } from "@t3tools/client-runtime/state/runtime";
 import {
   AgentSessionSource,
   AuthTerminalOperateScope,
@@ -24,22 +21,23 @@ import {
   ProviderDriverKind,
   ThreadId,
 } from "@t3tools/contracts";
+import { Link } from "@tanstack/react-router";
 import * as Schema from "effect/Schema";
 import {
-  ArrowRightIcon,
   CheckIcon,
+  ChevronDownIcon,
   ChevronRightIcon,
-  CloudIcon,
-  LinkIcon,
-  MonitorIcon,
+  SmartphoneIcon,
   TerminalIcon,
 } from "lucide-react";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 
 import { TYPOGRAPHY_ADVANCED_STORAGE_KEY } from "../../appearanceFonts";
+import { isElectron } from "../../env";
 import { useLocalStorage } from "../../hooks/useLocalStorage";
 import { hasCloudPublicConfig } from "../../cloud/publicConfig";
 import { PRIVACY_POLICY_URL } from "../../legalLinks";
+import { workspaceAreaProps } from "../../lib/workspaceFocus";
 import { useT3ConnectAuthPrompt } from "../clerk/useT3ConnectAuthPrompt";
 import { completeOnboarding } from "../../onboarding/firstRun";
 import {
@@ -55,21 +53,13 @@ import {
   getOnboardingProviderState,
   resolveOnboardingProviderInstallCommand,
   resolveOnboardingProviderLoginCommand,
-  selectOnboardingProvidersByDriver,
 } from "../../onboarding/providerReadiness.logic";
+import { groupWelcomeAgents } from "../../onboarding/welcomeAgents.logic";
 import { newProjectId, randomUUID } from "../../lib/utils";
 import { agentSessionImport } from "../../state/agentSessions";
 import { readProjects, waitForProject } from "../../state/entities";
-import { useEnvironments, usePrimaryEnvironment } from "../../state/environments";
-import {
-  managedInstanceLocks,
-  managedTelemetryOffMessage,
-  usePrimaryManagedPolicy,
-} from "../../state/managedPolicy";
-import {
-  isOnboardingRelayEnvironment,
-  resolveOnboardingSetup,
-} from "../../onboarding/targetEnvironment.logic";
+import { useEnvironments } from "../../state/environments";
+import { managedTelemetryOffMessage, useManagedPolicy } from "../../state/managedPolicy";
 import { useProjectScans } from "../../onboarding/useProjectScans";
 import { projectEnvironment } from "../../state/projects";
 import { serverEnvironment } from "../../state/server";
@@ -80,96 +70,56 @@ import {
 } from "../../state/session";
 import { terminalEnvironment } from "../../state/terminal";
 import { useAtomCommand } from "../../state/use-atom-command";
-import { connectPairing } from "../../connection/onboarding";
 import { getProviderSummary } from "../settings/providerStatus";
 import { providerClients } from "../settings/providerDriverMeta";
+import { AddProviderInstanceDialog } from "../settings/AddProviderInstanceDialog";
 import { ChatGptWelcomeCoordinator } from "../settings/ChatGptWelcomeCoordinator";
 import { useDesktopCliCommand } from "../settings/CliCommandSettingsRow";
-import { AddManagedCodexAccountDialog, CodexSetupSection } from "../settings/CodexSetupSection";
+import { CodexSetupSection } from "../settings/CodexSetupSection";
 import { readCodexSetupMode } from "../settings/CodexSetupSection.logic";
+import { MOBILE_APP_STORES } from "../settings/MobileAppSettingsRow";
 import { buildProviderInstanceUpdatePatch } from "../settings/SettingsPanels.logic";
 import { TerminalViewport } from "../ThreadTerminalDrawer";
-import { CloudEnvironmentConnectRows } from "../cloud/CloudEnvironmentConnectList";
-import { presentSavedCloudEnvironmentConnection } from "../cloud/cloudEnvironmentConnectionPresentation";
 import { ProviderInstanceIcon } from "../chat/ProviderInstanceIcon";
-import { T3Wordmark } from "../T3Wordmark";
-import { Alert, AlertDescription } from "../ui/alert";
+import { ACPRegistryIcon } from "../Icons";
 import { Button } from "../ui/button";
-import { InstallT3Commands } from "../InstallT3Commands";
 import { Checkbox } from "../ui/checkbox";
 import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "../ui/collapsible";
-import { Input } from "../ui/input";
+import { QRCodeSvg } from "../ui/qr-code";
 import { Tooltip, TooltipTrigger, TooltipPopup } from "../ui/tooltip";
 import { ScrollArea } from "../ui/scroll-area";
-import { Spinner } from "../ui/spinner";
-import { WizardPanel, WizardSteps, WizardPopup, WizardHeader } from "../ui/wizard";
-import { Dialog } from "../ui/dialog";
+import { SidebarInset } from "../ui/sidebar";
 import { toastManager } from "../ui/toast";
+import { WorkspacePageHeader } from "../WorkspacePageHeader";
 import { cn } from "../../lib/utils";
 import { formatRelativeTime } from "../../timestampFormat";
 
-type WizardStep = "connection" | "agents" | "import";
-const NO_ENVIRONMENTS: readonly EnvironmentId[] = [];
-
 const AGENT_ONBOARDING_THREAD_ID = ThreadId.make("onboarding-agent-setup");
-const ONBOARDING_STAGES = ["Connect", "Agents", "Projects"] as const;
 const SCAN_LIMIT_MESSAGE = "Scan limit reached. Some projects or conversations may be missing.";
 
-export function WelcomeWizard({
-  localAvailable,
+/**
+ * First-run page for one computer: its agents, the projects found in Claude Code and Codex
+ * history, and the phone app. Every part is optional except one ready agent to start chatting.
+ */
+export function WelcomePage({
+  environmentId,
   onDone,
-  resumeEnvironmentId,
 }: {
-  readonly localAvailable: boolean;
-  readonly resumeEnvironmentId?: EnvironmentId | undefined;
+  readonly environmentId: EnvironmentId;
   readonly onDone: (projectRef?: ScopedProjectRef) => void | Promise<void>;
 }) {
-  const [step, setStep] = useState<WizardStep>(resumeEnvironmentId ? "agents" : "connection");
   const { environments } = useEnvironments();
-  const [selection, setSelection] = useState<ReadonlySet<EnvironmentId> | null>(null);
-  // Share the registry for the wizard's lifetime so unchecked computers are not auto-selected again.
-  const [autoSelectedComputers] = useState(() => new Set<EnvironmentId>());
-  const [setupIds, setSetupIds] = useState<readonly EnvironmentId[]>(
-    resumeEnvironmentId ? [resumeEnvironmentId] : [],
-  );
+  const label =
+    environments.find((environment) => environment.environmentId === environmentId)?.label ??
+    "this computer";
+  const providers = useAtomValue(serverEnvironment.providersValueAtom(environmentId));
+  const agentReady =
+    providers?.some((provider) => getOnboardingProviderState(provider) === "ready") ?? false;
+  const scans = useProjectScans([environmentId]);
   const [importSelection, setImportSelection] = useState<ImportSelection | null>(null);
   const [isImporting, setIsImporting] = useState(false);
   const finishingPromiseRef = useRef<Promise<boolean> | null>(null);
   const completionErrorToastIdRef = useRef<ReturnType<typeof toastManager.add> | null>(null);
-  const primaryEnvironment = usePrimaryEnvironment();
-  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- marks newly listed computers in the shared auto-select registry once and selects the enabled ones
-  useEffect(() => {
-    const newComputers = environments.filter(
-      (environment) => !autoSelectedComputers.has(environment.environmentId),
-    );
-    if (newComputers.length === 0) return;
-    for (const environment of newComputers) {
-      autoSelectedComputers.add(environment.environmentId);
-    }
-    const enabledComputers = newComputers.filter((environment) => environment.entry.enabled);
-    if (enabledComputers.length === 0) return;
-    // oxlint-disable-next-line react/set-state-in-effect -- The registry marks each computer once, and only after commit; render must not mutate it.
-    setSelection(
-      (current) =>
-        new Set([
-          ...(current ?? []),
-          ...enabledComputers.map((environment) => environment.environmentId),
-        ]),
-    );
-  }, [autoSelectedComputers, environments]);
-  const selectedIds =
-    selection ?? new Set(primaryEnvironment ? [primaryEnvironment.environmentId] : []);
-  const scans = useProjectScans(step === "import" ? setupIds : NO_ENVIRONMENTS);
-  const isLoadingProjects =
-    step === "import" &&
-    scans.every((scan) => scan.data === null) &&
-    scans.some((scan) => scan.isPending);
-  const startSetup = (ids: readonly EnvironmentId[]) => {
-    if (ids.length === 0) return;
-    setSetupIds(ids);
-    setStep("agents");
-  };
-  const stageIndex = step === "agents" ? 1 : step === "import" ? 2 : 0;
   const finish = (
     projectRef?: ScopedProjectRef,
     importWarning?: string,
@@ -224,447 +174,118 @@ export function WelcomeWizard({
     finishingPromiseRef.current = completion;
     return completion;
   };
+  const projectImport = useProjectImport({
+    scans,
+    importSelection,
+    onImportSelectionChange: setImportSelection,
+    isImporting,
+    setIsImporting,
+    onDone: finish,
+  });
+  const selectedCount = projectImport.selected.length;
+  const start = () => {
+    if (selectedCount > 0) void projectImport.runImport(projectImport.selected);
+    else projectImport.finishAfterImport();
+  };
 
   return (
-    <Dialog
-      open
-      disablePointerDismissal
-      onOpenChange={(_, event) => {
-        event.cancel();
-        if (event.reason === "close-press" && !isImporting) void finish();
-      }}
+    <SidebarInset
+      {...workspaceAreaProps("home", 1, "Welcome")}
+      role="main"
+      className="h-dvh min-h-0 overflow-hidden overscroll-y-none"
     >
-      <WizardPopup
-        size="wide"
-        bottomStickOnMobile={false}
-        initialFocus={() => document.getElementById("onboarding-pairing-url") ?? true}
-      >
-        <WizardHeader
-          title="Set up T3 Code"
-          identity={
-            <div className="flex items-baseline gap-1.5" role="img" aria-label="T3 Code">
-              <T3Wordmark className="h-4 w-auto shrink-0" aria-hidden />
-              <span className="text-2xl font-medium tracking-tight text-muted-foreground">
-                Code
-              </span>
-            </div>
-          }
-        >
-          <WizardSteps
-            steps={ONBOARDING_STAGES}
-            currentStep={stageIndex}
-            isStepDisabled={(index) => isImporting || index >= stageIndex}
-            onStepChange={(index) => {
-              if (isImporting || index > stageIndex) return;
-              setStep(index === 0 ? "connection" : "agents");
-            }}
-          />
-        </WizardHeader>
-
-        <WizardPanel holdHeight={isLoadingProjects}>
-          {step === "connection" ? (
-            <ConnectionStep
-              expandPairingInitially={!localAvailable && !hasCloudPublicConfig()}
-              selectedIds={selectedIds}
-              autoSelectedComputers={autoSelectedComputers}
-              onSelectionChange={setSelection}
-              onToggleEnvironment={(environmentId, checked) =>
-                setSelection((current) => {
-                  const next = new Set(current ?? selectedIds);
-                  if (checked) next.add(environmentId);
-                  else next.delete(environmentId);
-                  return next;
-                })
-              }
-              onContinue={() =>
-                startSetup(resolveOnboardingSetup(environments, selectedIds).environmentIds)
-              }
-              onPaired={(environmentId) => {
-                setSelection(new Set([...selectedIds, environmentId]));
-              }}
-            />
-          ) : step === "agents" ? (
-            <AgentsStep environmentIds={setupIds} onContinue={() => setStep("import")} />
-          ) : (
-            <ImportStep
-              scans={scans}
-              importSelection={importSelection}
-              onImportSelectionChange={setImportSelection}
+      <div className="flex min-h-0 min-w-0 flex-1 flex-col bg-background">
+        {/* The desktop window only moves where CSS opts in, so keep a titlebar strip. */}
+        {isElectron ? <WorkspacePageHeader electron /> : null}
+        <div className="min-h-0 flex-1 overflow-y-auto scrollbar-gutter-both">
+          <div className="mx-auto w-full max-w-2xl px-6 pt-12 pb-10 sm:pt-16">
+            <h1 className="text-2xl font-semibold tracking-tight text-foreground">
+              Welcome to T3 Code
+            </h1>
+            <p className="mt-2 text-sm text-muted-foreground">
+              Setting up <span className="font-medium text-foreground">{label}</span>. You can
+              change any of this later in Settings.
+            </p>
+            <AgentsSection environmentId={environmentId} label={label} />
+            <ProjectsSection
+              scan={scans[0]}
+              projectImport={projectImport}
               isImporting={isImporting}
-              setIsImporting={setIsImporting}
-              onDone={finish}
             />
-          )}
-        </WizardPanel>
-      </WizardPopup>
-      <ChatGptWelcomeCoordinator />
-    </Dialog>
-  );
-}
-
-function ConnectionStep({
-  autoSelectedComputers,
-  expandPairingInitially,
-  selectedIds,
-  onSelectionChange,
-  onToggleEnvironment,
-  onContinue,
-  onPaired,
-}: {
-  readonly autoSelectedComputers: Set<EnvironmentId>;
-  readonly expandPairingInitially: boolean;
-  readonly selectedIds: ReadonlySet<EnvironmentId>;
-  readonly onSelectionChange: (ids: ReadonlySet<EnvironmentId>) => void;
-  readonly onToggleEnvironment: (environmentId: EnvironmentId, checked: boolean) => void;
-  readonly onContinue: () => void;
-  readonly onPaired: (environmentId: EnvironmentId) => void;
-}) {
-  const { environments } = useEnvironments();
-  const telemetryOff = managedTelemetryOffMessage(usePrimaryManagedPolicy());
-  const cloudEnabled = hasCloudPublicConfig();
-  const directEnvironments = environments.filter(
-    (environment) => !cloudEnabled || !isOnboardingRelayEnvironment(environment),
-  );
-  const [pairingOpen, setPairingOpen] = useState(expandPairingInitially);
-  const [isPairing, setIsPairing] = useState(false);
-  const { ready, skippedIds } = resolveOnboardingSetup(environments, selectedIds);
-  const skippedLabels = environments
-    .filter((environment) => skippedIds.includes(environment.environmentId))
-    .map((environment) => environment.label);
-  const continueRef = useRef<HTMLButtonElement>(null);
-  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- moves DOM focus to the Continue button once setup is ready and nothing else holds focus
-  useEffect(() => {
-    if (
-      ready &&
-      (document.activeElement === document.body ||
-        document.activeElement?.getAttribute("role") === "dialog")
-    ) {
-      continueRef.current?.focus();
-    }
-  }, [ready]);
-  return (
-    <>
-      <h1 className="text-2xl font-semibold tracking-tight text-foreground">
-        Connect your computers
-      </h1>
-      <p className="mt-2.5 text-sm leading-relaxed text-muted-foreground">
-        Choose one or more computers. We’ll set up agents and projects on each.
-      </p>
-      {directEnvironments.length > 0 ? (
-        <fieldset className="mt-5 space-y-2">
-          <legend className="sr-only">Computers to set up</legend>
-          {directEnvironments.map((environment) => (
-            <label
-              key={environment.environmentId}
-              className="flex cursor-pointer items-center gap-3 rounded-lg border border-border bg-background px-3 py-3"
-            >
-              <Checkbox
-                checked={selectedIds.has(environment.environmentId)}
-                onCheckedChange={(checked) => {
-                  const next = new Set(selectedIds);
-                  if (checked) next.add(environment.environmentId);
-                  else next.delete(environment.environmentId);
-                  onSelectionChange(next);
-                }}
-              />
-              <MonitorIcon className="size-4 shrink-0 text-muted-foreground" />
-              <span className="min-w-0 flex-1">
-                <span className="flex items-baseline justify-between gap-3">
-                  <span className="min-w-0 text-sm font-medium break-words">
-                    {environment.label}
-                  </span>
-                  <span className="shrink-0 text-xs text-muted-foreground">
-                    {!environment.entry.enabled && environment.connection.phase !== "unsupported"
-                      ? "Off"
-                      : presentSavedCloudEnvironmentConnection(environment.connection).buttonLabel}
-                  </span>
-                </span>
-                {environment.displayUrl ? (
-                  <span className="mt-0.5 block text-xs break-all text-muted-foreground">
-                    {environment.displayUrl}
-                  </span>
-                ) : null}
-                {environment.connection.phase === "unsupported" && environment.connection.error ? (
-                  <span className="mt-0.5 block text-xs text-muted-foreground">
-                    {environment.connection.error}
-                  </span>
-                ) : null}
-              </span>
-            </label>
-          ))}
-        </fieldset>
-      ) : null}
-      <div className="mt-4 space-y-2">
-        {cloudEnabled ? (
-          <ConnectAccountOption
-            autoSelectedComputers={autoSelectedComputers}
-            disabled={isPairing}
-            selectedIds={selectedIds}
-            onToggleEnvironment={onToggleEnvironment}
-          />
-        ) : null}
-        <div className="rounded-lg border border-border bg-background">
-          <Collapsible open={pairingOpen} onOpenChange={setPairingOpen}>
-            <CollapsibleTrigger
-              disabled={isPairing}
-              render={
-                <Button
-                  variant="ghost"
-                  size="sm-multiline"
-                  className="min-h-14 w-full justify-start"
-                />
-              }
-            >
-              <LinkIcon className="size-4 text-muted-foreground" />
-              <span className="flex-1 text-left">Add a computer</span>
-              <ChevronRightIcon
-                className={cn("size-4 text-muted-foreground", pairingOpen && "rotate-90")}
-              />
-            </CollapsibleTrigger>
-            <CollapsiblePanel>
-              <div className="px-3 pb-3">
-                <PairingForm
-                  isPairing={isPairing}
-                  setIsPairing={setIsPairing}
-                  onPaired={(environmentId) => {
-                    setPairingOpen(false);
-                    onPaired(environmentId);
-                    requestAnimationFrame(() => continueRef.current?.focus());
-                  }}
-                />
+            <PhoneSection />
+            <div className="mt-8 flex flex-wrap items-center justify-between gap-3 border-t border-border/70 pt-6">
+              {agentReady ? (
+                <span />
+              ) : (
+                <Button variant="ghost-muted" disabled={isImporting} onClick={start}>
+                  Skip for now
+                </Button>
+              )}
+              <div className="flex items-center gap-3">
+                {agentReady ? null : (
+                  <span className="text-xs text-muted-foreground">Set up one agent to start.</span>
+                )}
+                <Button disabled={!agentReady || isImporting} onClick={start}>
+                  {isImporting
+                    ? "Importing…"
+                    : selectedCount > 0
+                      ? `Add ${selectedCount} ${selectedCount === 1 ? "project" : "projects"} and start`
+                      : "Start"}
+                </Button>
               </div>
-            </CollapsiblePanel>
-          </Collapsible>
+            </div>
+            <TelemetryNotice environmentId={environmentId} />
+          </div>
         </div>
       </div>
-      {skippedLabels.length > 0 ? (
-        <p className="mt-4 text-xs text-muted-foreground">
-          Not connected, so setup skips {skippedLabels.join(", ")}. You can set{" "}
-          {skippedLabels.length === 1 ? "it" : "them"} up later from Settings.
-        </p>
-      ) : null}
-      <div className="mt-6 flex flex-col-reverse gap-4 sm:flex-row sm:items-center sm:justify-between sm:gap-6">
-        <p className="min-w-0 text-xs leading-relaxed text-muted-foreground">
-          {telemetryOff ?? "T3 Code collects anonymous usage data to help us improve it."} To read
-          more about how your data is used{telemetryOff === undefined ? " and how to opt out" : ""},
-          see our{" "}
-          <a
-            className="underline underline-offset-2 hover:text-foreground"
-            href={PRIVACY_POLICY_URL}
-            target="_blank"
-            rel="noreferrer noopener"
-          >
-            privacy policy
-          </a>
-          .
-        </p>
-        <Button
-          className="shrink-0 self-end"
-          ref={continueRef}
-          autoFocus={!expandPairingInitially}
-          disabled={!ready || isPairing}
-          onClick={onContinue}
-        >
-          Continue
-          <ArrowRightIcon className="size-3.5" />
-        </Button>
-      </div>
-    </>
+      <ChatGptWelcomeCoordinator />
+    </SidebarInset>
   );
 }
 
-function ConnectAccountOption({
-  autoSelectedComputers,
-  disabled,
-  selectedIds,
-  onToggleEnvironment,
-}: {
-  readonly autoSelectedComputers: Set<EnvironmentId>;
-  readonly disabled: boolean;
-  readonly selectedIds: ReadonlySet<EnvironmentId>;
-  readonly onToggleEnvironment: (environmentId: EnvironmentId, checked: boolean) => void;
-}) {
-  const { environments } = useEnvironments();
-  const { isLoaded, isSignedIn } = useAuth({ treatPendingAsSignedOut: false });
-  const { openAuthPrompt } = useT3ConnectAuthPrompt();
-  const [expanded, setExpanded] = useState(true);
-  const [discoveryReady, setDiscoveryReady] = useState(false);
-  const onDiscoveryReady = () => setDiscoveryReady(true);
-
+function TelemetryNotice({ environmentId }: { readonly environmentId: EnvironmentId }) {
+  const telemetryOff = managedTelemetryOffMessage(useManagedPolicy(environmentId));
   return (
-    <div className="rounded-lg border border-border bg-background">
-      <Collapsible open={expanded && !!isSignedIn && discoveryReady} onOpenChange={setExpanded}>
-        <CollapsibleTrigger
-          disabled={disabled || !isLoaded}
-          onClick={(event) => {
-            if (!isSignedIn) {
-              event.preventDefault();
-              setExpanded(true);
-              openAuthPrompt();
-            }
-          }}
-          render={
-            <Button variant="ghost" size="sm-multiline" className="min-h-14 w-full justify-start" />
-          }
-        >
-          <CloudIcon className="size-4 text-muted-foreground" />
-          <span className="flex-1 text-left">T3 Connect</span>
-          <span className="text-xs text-muted-foreground">
-            {!isLoaded
-              ? "Loading sign-in…"
-              : !isSignedIn
-                ? "Sign in"
-                : !discoveryReady
-                  ? "Loading computers…"
-                  : null}
-          </span>
-          <ChevronRightIcon
-            className={cn("size-4 text-muted-foreground", expanded && isSignedIn && "rotate-90")}
-          />
-        </CollapsibleTrigger>
-        <CollapsiblePanel keepMounted>
-          <div className="px-3 pb-3">
-            <div className="mb-3 space-y-1.5">
-              {isSignedIn ? (
-                <CloudEnvironmentConnectRows
-                  primaryEnvironmentId={null}
-                  savedEnvironments={environments}
-                  showSavedEnvironments
-                  onDiscoveryReady={onDiscoveryReady}
-                  selection={{ selectedIds, onChange: onToggleEnvironment, autoSelectedComputers }}
-                  refreshWhileEmpty
-                  empty={
-                    <p className="py-3 text-sm text-muted-foreground">No computers linked yet.</p>
-                  }
-                />
-              ) : null}
-            </div>
-            <p className="text-sm text-muted-foreground">
-              Run this on each computer you want to connect.
-            </p>
-            <InstallT3Commands command="t3 connect" className="mt-3" />
-            <p className="mt-3 text-xs text-muted-foreground">
-              Keep T3 Code running. Select the computers you want to set up above.
-            </p>
-          </div>
-        </CollapsiblePanel>
-      </Collapsible>
-    </div>
+    <p className="mt-6 text-xs leading-relaxed text-muted-foreground">
+      {telemetryOff ?? "T3 Code collects anonymous usage data to help us improve it."} To read more
+      about how your data is used{telemetryOff === undefined ? " and how to opt out" : ""}, see our{" "}
+      <a
+        className="underline underline-offset-2 hover:text-foreground"
+        href={PRIVACY_POLICY_URL}
+        target="_blank"
+        rel="noreferrer noopener"
+      >
+        privacy policy
+      </a>
+      .
+    </p>
   );
 }
 
-function PairingForm({
-  isPairing,
-  setIsPairing,
-  onPaired,
+function WelcomeSection({
+  title,
+  status,
+  children,
 }: {
-  readonly isPairing: boolean;
-  readonly setIsPairing: (value: boolean) => void;
-  readonly onPaired: (environmentId: EnvironmentId) => void;
+  readonly title: string;
+  readonly status?: ReactNode;
+  readonly children: ReactNode;
 }) {
-  const connectPairingEnvironment = useAtomCommand(connectPairing, { reportFailure: false });
-  const [pairingUrl, setPairingUrl] = useState("");
-  const [errorMessage, setErrorMessage] = useState("");
-  const mountedRef = useRef(true);
-
-  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- tracks mount so a pairing request that settles after unmount does not set state
-  useEffect(() => {
-    mountedRef.current = true;
-    return () => {
-      mountedRef.current = false;
-    };
-  }, []);
-
-  const submit = async () => {
-    if (isPairing || pairingUrl.trim().length === 0) return;
-    setIsPairing(true);
-    setErrorMessage("");
-    const result = await connectPairingEnvironment({ pairingUrl: pairingUrl.trim() });
-    if (!mountedRef.current) return;
-    setIsPairing(false);
-    if (result._tag === "Success") {
-      onPaired(result.value);
-      return;
-    }
-    if (isAtomCommandInterrupted(result)) return;
-    const cause = squashAtomCommandFailure(result);
-    setErrorMessage(cause instanceof Error ? cause.message : "Pairing failed.");
-  };
-
   return (
-    <>
-      <form
-        className="space-y-3"
-        onSubmit={(event) => {
-          event.preventDefault();
-          void submit();
-        }}
-      >
-        <div>
-          <label className="block text-sm text-muted-foreground" htmlFor="onboarding-pairing-url">
-            Pairing link
-          </label>
-          <Input
-            id="onboarding-pairing-url"
-            autoFocus
-            aria-invalid={errorMessage.length > 0}
-            aria-describedby={errorMessage ? "onboarding-pairing-error" : undefined}
-            className="mt-2"
-            size="lg"
-            autoCapitalize="none"
-            autoComplete="off"
-            autoCorrect="off"
-            spellCheck={false}
-            nativeInput
-            readOnly={isPairing}
-            placeholder="https://your-server:5230/pair#token=…"
-            value={pairingUrl}
-            onChange={(event) => setPairingUrl(event.currentTarget.value)}
-            onKeyDown={(event) => {
-              if (
-                event.key === "Enter" &&
-                (event.nativeEvent.isComposing || event.keyCode === 229)
-              ) {
-                event.preventDefault();
-              }
-            }}
-          />
-        </div>
-        {errorMessage ? (
-          <Alert id="onboarding-pairing-error" variant="error">
-            <AlertDescription>{errorMessage}</AlertDescription>
-          </Alert>
-        ) : null}
-        <Collapsible>
-          <div className="flex items-center justify-between gap-3">
-            <CollapsibleTrigger
-              type="button"
-              className="group flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground"
-            >
-              <ChevronRightIcon className="size-3.5 group-data-panel-open:rotate-90" />
-              Need a pairing link?
-            </CollapsibleTrigger>
-            <Button type="submit" disabled={isPairing || pairingUrl.trim().length === 0}>
-              {isPairing ? "Pairing..." : "Pair"}
-            </Button>
-          </div>
-          <CollapsiblePanel>
-            <p className="pt-3 text-sm text-muted-foreground">On the computer with your code:</p>
-            <InstallT3Commands command="t3 pair" className="mt-2" />
-            <p className="mt-2 text-xs leading-relaxed text-muted-foreground">
-              Start T3 Code or run <code className="font-mono">t3 serve</code> there before{" "}
-              <code className="font-mono">t3 pair</code>. On a tailnet, run{" "}
-              <code className="font-mono">t3 pair --tailscale</code> instead.
-            </p>
-          </CollapsiblePanel>
-        </Collapsible>
-      </form>
-    </>
+    <section className="mt-8">
+      <div className="mb-3 flex items-baseline justify-between gap-3">
+        <h2 className="text-sm font-semibold text-foreground">{title}</h2>
+        {status ? <span className="text-xs text-muted-foreground">{status}</span> : null}
+      </div>
+      {children}
+    </section>
   );
 }
 
-const PRIMARY_AGENT_DRIVERS = ["codex", "claudeAgent"] as const;
-type OnboardingAgentDriver = (typeof PRIMARY_AGENT_DRIVERS)[number];
+const INSTALLABLE_DRIVERS = ["codex", "claudeAgent"] as const;
+type OnboardingAgentDriver = (typeof INSTALLABLE_DRIVERS)[number];
+const isInstallableDriver = (driver: string): driver is OnboardingAgentDriver =>
+  (INSTALLABLE_DRIVERS as ReadonlyArray<string>).includes(driver);
 
 interface AgentTerminalSession {
   readonly environmentId: EnvironmentId;
@@ -675,202 +296,172 @@ interface AgentTerminalSession {
   readonly keybindings: ServerConfig["keybindings"];
 }
 
-function AgentsStep({
-  environmentIds,
-  onContinue,
-}: {
-  readonly environmentIds: readonly EnvironmentId[];
-  readonly onContinue: () => void;
-}) {
-  const { environments } = useEnvironments();
+function agentName(provider: ServerProvider) {
   return (
-    <StepShell
-      title="Connect your agents"
-      description="Choose an agent to start coding. You can add more later."
-    >
-      <ScrollArea scrollFade className="mt-5 h-auto max-h-[min(32rem,55dvh)]">
-        <div className="space-y-5 pr-3">
-          {environmentIds.map((environmentId) => (
-            <ConnectedAgentsStep
-              key={environmentId}
-              environmentId={environmentId}
-              machineLabel={
-                environments.find((environment) => environment.environmentId === environmentId)
-                  ?.label ?? "Computer"
-              }
-            />
-          ))}
-        </div>
-      </ScrollArea>
-      <CliPathSetup />
-      <div className="mt-6 flex justify-end">
-        <Button autoFocus onClick={onContinue}>
-          Continue
-          <ArrowRightIcon className="size-3.5" />
-        </Button>
-      </div>
-    </StepShell>
+    provider.displayName ||
+    (provider.driver === "claudeAgent"
+      ? "Claude Code"
+      : (providerClients.get(provider.driver)?.label ?? provider.driver))
   );
 }
 
-function ConnectedAgentsStep({
+function AgentsSection({
   environmentId,
-  machineLabel,
+  label,
 }: {
   readonly environmentId: EnvironmentId;
-  readonly machineLabel: string;
+  readonly label: string;
 }) {
   const providers = useAtomValue(serverEnvironment.providersValueAtom(environmentId));
   const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
     reportFailure: false,
   });
   const serverConfig = useAtomValue(serverEnvironment.configValueAtom(environmentId));
-  const [terminalSession, setTerminalSession] = useState<AgentTerminalSession | null>(null);
-  const [addingAccount, setAddingAccount] = useState(false);
-  const [createdAccount, setCreatedAccount] = useState<{
-    instanceId: ProviderInstanceId;
-    displayName: string;
-    autoStart: boolean;
-  } | null>(null);
   const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
+  const [terminalSession, setTerminalSession] = useState<AgentTerminalSession | null>(null);
+  const [moreOpen, setMoreOpen] = useState<boolean | null>(null);
+  const [addingProvider, setAddingProvider] = useState(false);
 
   // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- asks the environment to refresh its provider list when the environment changes
   useEffect(() => {
     void refreshProviders({ environmentId, input: {} });
   }, [environmentId, refreshProviders]);
 
-  const byDriver = selectOnboardingProvidersByDriver(providers);
   const managedPolicy = serverConfig?.managedPolicy;
-  // A policy that owns Codex's launch settings also rules out ChatGPT's own runtime.
-  const chatGptAllowed =
-    managedInstanceLocks(managedPolicy, ProviderDriverKind.make("codex"))?.configKeys.has(
-      "setupMode",
-    ) !== true;
+  const { checking, found, available } = groupWelcomeAgents(
+    providers?.filter((provider) => isManagedDriverAllowed(managedPolicy, provider.driver)),
+    agentName,
+  );
+  // With nothing on this computer yet, the list of agents to add is the main task.
+  const showMore = moreOpen ?? (!checking && found.length === 0);
+  const readyCount = found.filter(
+    (provider) => getOnboardingProviderState(provider) === "ready",
+  ).length;
 
-  const primaryAgents = PRIMARY_AGENT_DRIVERS.filter((driver) =>
-    isManagedDriverAllowed(managedPolicy, ProviderDriverKind.make(driver)),
-  ).flatMap((driver) => {
-    const instances =
-      driver === "codex" ? providers?.filter((provider) => provider.driver === driver) : undefined;
-    return instances?.length
-      ? instances.map((provider) => ({ driver, provider, instanceId: provider.instanceId }))
-      : [{ driver, provider: byDriver.get(driver), instanceId: byDriver.get(driver)?.instanceId }];
-  });
-  if (createdAccount) {
-    const index = primaryAgents.findIndex(
-      (agent) => agent.instanceId === createdAccount.instanceId,
-    );
-    const [existing] = index >= 0 ? primaryAgents.splice(index, 1) : [];
-    primaryAgents.unshift(
-      existing ?? {
-        driver: "codex",
-        provider: undefined,
-        instanceId: createdAccount.instanceId,
-      },
+  const openTerminal = (provider: ServerProvider) => {
+    if (
+      !isInstallableDriver(provider.driver) ||
+      serverConfig === null ||
+      !readEnvironmentScope(environmentId, AuthTerminalOperateScope)
+    )
+      return;
+    setTerminalSession({
+      environmentId,
+      driver: provider.driver,
+      providerInstanceId: provider.instanceId,
+      cwd: serverConfig.cwd,
+      command: provider.installed
+        ? resolveOnboardingProviderLoginCommand(
+            provider,
+            serverConfig.settings,
+            serverConfig.environment.platform.os,
+          )
+        : resolveOnboardingProviderInstallCommand(
+            provider.driver,
+            serverConfig.environment.platform.os,
+          ),
+      keybindings: serverConfig.keybindings,
+    });
+  };
+
+  const renderAgent = (provider: ServerProvider, compact = false) => {
+    const terminalOpen = terminalSession?.providerInstanceId === provider.instanceId;
+    const ready = getOnboardingProviderState(provider) === "ready";
+    if (ready) {
+      return <AgentCard key={provider.instanceId} driver={provider.driver} provider={provider} />;
+    }
+    if (provider.driver === "codex" && serverConfig !== null) {
+      return (
+        <OnboardingCodexSetup
+          key={provider.instanceId}
+          environmentId={environmentId}
+          provider={provider}
+          serverConfig={serverConfig}
+          terminalOpen={terminalOpen}
+          onOpenTerminal={() => openTerminal(provider)}
+        />
+      );
+    }
+    if (isInstallableDriver(provider.driver)) {
+      return (
+        <AgentCard
+          key={provider.instanceId}
+          driver={provider.driver}
+          provider={provider}
+          terminalOpen={terminalOpen}
+          terminalAvailable={serverConfig !== null && canOperateTerminal}
+          onOpenTerminal={() => openTerminal(provider)}
+        />
+      );
+    }
+    return (
+      <AgentCard
+        key={provider.instanceId}
+        driver={provider.driver}
+        provider={provider}
+        compact={compact}
+        settingsLink={{ environmentId, instanceId: provider.instanceId }}
+      />
     );
-  }
+  };
+
   return (
-    <section>
-      <h2 className="mb-2 text-sm font-medium">{machineLabel}</h2>
+    <WelcomeSection
+      title="Agents"
+      status={
+        checking && found.length === 0
+          ? `Checking ${label}…`
+          : readyCount > 0
+            ? `${readyCount} ready on ${label}`
+            : `None ready on ${label} yet`
+      }
+    >
+      {found.length > 0 ? (
+        <div className="space-y-1.5">{found.map((provider) => renderAgent(provider))}</div>
+      ) : null}
       {!canOperateTerminal ? (
-        <p className="mb-2 text-sm text-muted-foreground">
+        <p className="mt-2 text-sm text-muted-foreground">
           This connection cannot control terminals.
         </p>
       ) : null}
-      <div className="space-y-1.5">
-        {primaryAgents.map(({ driver, provider, instanceId }) =>
-          driver === "codex" && serverConfig !== null ? (
-            <OnboardingCodexSetup
-              key={instanceId ?? driver}
-              environmentId={environmentId}
-              provider={provider}
-              serverConfig={serverConfig}
-              createdAccount={instanceId === createdAccount?.instanceId ? createdAccount : null}
-              onAutoStartConsumed={() =>
-                setCreatedAccount((account) => (account ? { ...account, autoStart: false } : null))
-              }
-              terminalOpen={terminalSession?.driver === driver}
-              onOpenTerminal={() => {
-                if (
-                  provider === undefined ||
-                  !readEnvironmentScope(environmentId, AuthTerminalOperateScope)
-                )
-                  return;
-                setTerminalSession({
-                  environmentId,
-                  driver,
-                  providerInstanceId: provider.instanceId,
-                  cwd: serverConfig.cwd,
-                  command: provider.installed
-                    ? resolveOnboardingProviderLoginCommand(
-                        provider,
-                        serverConfig.settings,
-                        serverConfig.environment.platform.os,
-                      )
-                    : resolveOnboardingProviderInstallCommand(
-                        driver,
-                        serverConfig.environment.platform.os,
-                      ),
-                  keybindings: serverConfig.keybindings,
-                });
-              }}
-            />
-          ) : (
-            <AgentCard
-              key={driver}
-              driver={driver}
-              provider={provider}
-              terminalOpen={terminalSession?.driver === driver}
-              terminalAvailable={serverConfig !== null && canOperateTerminal}
-              onOpenTerminal={() => {
-                if (
-                  provider === undefined ||
-                  serverConfig === null ||
-                  !readEnvironmentScope(environmentId, AuthTerminalOperateScope)
-                )
-                  return;
-                setTerminalSession({
-                  environmentId,
-                  driver,
-                  providerInstanceId: provider.instanceId,
-                  cwd: serverConfig.cwd,
-                  command: provider.installed
-                    ? resolveOnboardingProviderLoginCommand(
-                        provider,
-                        serverConfig.settings,
-                        serverConfig.environment.platform.os,
-                      )
-                    : resolveOnboardingProviderInstallCommand(
-                        driver,
-                        serverConfig.environment.platform.os,
-                      ),
-                  keybindings: serverConfig.keybindings,
-                });
-              }}
-            />
-          ),
-        )}
-      </div>
-      {chatGptAllowed &&
-      providers?.some(
-        (provider) =>
-          provider.driver === "codex" && getOnboardingProviderState(provider) === "ready",
-      ) ? (
-        <div className="mt-3">
-          <Button size="xs" variant="ghost-muted" onClick={() => setAddingAccount(true)}>
-            Connect another ChatGPT account
-          </Button>
-        </div>
-      ) : null}
-      {addingAccount ? (
-        <AddManagedCodexAccountDialog
-          environmentId={environmentId}
-          onClose={() => setAddingAccount(false)}
-          onAccountCreated={(instanceId, displayName) =>
-            setCreatedAccount({ instanceId, displayName, autoStart: true })
-          }
-        />
-      ) : null}
+      <Collapsible
+        open={showMore}
+        onOpenChange={setMoreOpen}
+        className={found.length > 0 ? "mt-2" : undefined}
+      >
+        <CollapsibleTrigger className="group flex w-full items-center gap-3 rounded-lg px-1 py-2 text-left outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring">
+          <span className="text-sm font-medium text-foreground">
+            {found.length > 0 ? "Add more agents" : "Set up an agent"}
+          </span>
+          <AgentLogoStack providers={available} />
+          <span className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
+            <ACPRegistryIcon className="size-3.5" />
+            ACP Registry
+          </span>
+          <ChevronDownIcon className="ml-auto size-4 text-muted-foreground group-data-panel-open:rotate-180" />
+        </CollapsibleTrigger>
+        <CollapsiblePanel>
+          <div className="space-y-1.5 pt-1">
+            {available
+              .filter((provider) => isInstallableDriver(provider.driver))
+              .map((provider) => renderAgent(provider))}
+            <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-2">
+              {available
+                .filter((provider) => !isInstallableDriver(provider.driver))
+                .map((provider) => renderAgent(provider, true))}
+            </div>
+            <div className="flex items-center justify-between gap-3 rounded-lg border border-dashed border-border px-4 py-3">
+              <span className="inline-flex items-center gap-2 text-sm text-muted-foreground">
+                <ACPRegistryIcon className="size-4" />
+                More agents in the ACP Registry
+              </span>
+              <Button size="xs" variant="outline" onClick={() => setAddingProvider(true)}>
+                Browse
+              </Button>
+            </div>
+          </div>
+        </CollapsiblePanel>
+      </Collapsible>
       {terminalSession !== null ? (
         <AgentInstallTerminal
           key={`${terminalSession.environmentId}:${terminalSession.providerInstanceId}:${terminalSession.driver}`}
@@ -881,13 +472,248 @@ function ConnectedAgentsStep({
           }}
         />
       ) : null}
-    </section>
+      {addingProvider ? (
+        <AddProviderInstanceDialog
+          open
+          environmentId={environmentId}
+          environmentLabel={label}
+          onOpenChange={setAddingProvider}
+          onCreated={() => void refreshProviders({ environmentId, input: {} })}
+        />
+      ) : null}
+    </WelcomeSection>
+  );
+}
+
+function AgentLogoStack({ providers }: { readonly providers: ReadonlyArray<ServerProvider> }) {
+  if (providers.length === 0) return null;
+  return (
+    <span className="flex items-center" aria-hidden>
+      {providers.slice(0, 5).map((provider, index) => (
+        <span
+          key={provider.instanceId}
+          className={cn(
+            "grid size-7 place-items-center rounded-full border border-border bg-background",
+            index > 0 && "-ml-1.5",
+          )}
+        >
+          <ProviderInstanceIcon
+            driverKind={provider.driver}
+            displayName={agentName(provider)}
+            iconClassName="size-3.5"
+          />
+        </span>
+      ))}
+    </span>
+  );
+}
+
+function ProjectsSection({
+  scan,
+  projectImport,
+  isImporting,
+}: {
+  readonly scan: ReturnType<typeof useProjectScans>[number] | undefined;
+  readonly projectImport: ReturnType<typeof useProjectImport>;
+  readonly isImporting: boolean;
+}) {
+  const [reviewing, setReviewing] = useState(false);
+  const { candidates, recent, selected, selectedKeys, setSelectedKeys, visibleImportError } =
+    projectImport;
+  if (scan === undefined) return null;
+  if (scan.isPending && scan.data === null) {
+    return (
+      <WelcomeSection title="Projects">
+        <p className="text-sm text-muted-foreground">
+          Looking for projects in your Claude Code and Codex history…
+        </p>
+      </WelcomeSection>
+    );
+  }
+  if (scan.error !== null) {
+    return (
+      <WelcomeSection title="Projects">
+        <div
+          role="alert"
+          className="flex items-center justify-between gap-3 text-sm text-muted-foreground"
+        >
+          <span>Could not check projects. {scan.error}</span>
+          <Button variant="ghost" size="sm" onClick={scan.refresh}>
+            Retry
+          </Button>
+        </div>
+      </WelcomeSection>
+    );
+  }
+  if (candidates.length === 0) return null;
+
+  const allKeys = candidates.map((candidate) => candidate.key);
+  const defaultKeys = recent.length > 0 ? recent.map((candidate) => candidate.key) : allKeys;
+  return (
+    <WelcomeSection title="Projects" status="From your Claude Code and Codex history">
+      <div className="flex items-center gap-3 rounded-lg border border-border bg-background px-4 py-3">
+        <Checkbox
+          aria-label="Bring in projects"
+          checked={selected.length > 0}
+          disabled={isImporting}
+          onCheckedChange={(checked) => setSelectedKeys(new Set(checked ? defaultKeys : []))}
+        />
+        <span className="min-w-0 flex-1 text-sm text-foreground">
+          {selected.length > 0
+            ? `Bring in ${selected.length} ${selected.length === 1 ? "project" : "projects"} and their chats`
+            : "Bring in projects and their chats"}
+        </span>
+        <Button
+          variant="ghost-muted"
+          size="xs"
+          aria-expanded={reviewing}
+          onClick={() => setReviewing((open) => !open)}
+        >
+          {reviewing ? "Hide" : `Review ${candidates.length}`}
+          <ChevronDownIcon className={cn("size-3.5", reviewing && "rotate-180")} />
+        </Button>
+      </div>
+      {reviewing ? (
+        <fieldset className="mt-2 min-w-0" disabled={isImporting}>
+          <div className="flex items-center justify-between gap-3 px-1 text-xs text-muted-foreground">
+            <span role="status">
+              {selected.length} of {candidates.length} selected
+            </span>
+            <div className="flex items-center gap-1">
+              <Button
+                variant="ghost"
+                size="xs"
+                disabled={selected.length === candidates.length}
+                onClick={() => setSelectedKeys(new Set(allKeys))}
+              >
+                Select all
+              </Button>
+              <Button
+                variant="ghost"
+                size="xs"
+                disabled={selected.length === 0}
+                onClick={() => setSelectedKeys(new Set())}
+              >
+                Select none
+              </Button>
+            </div>
+          </div>
+          <ScrollArea scrollFade className="mt-1 h-auto max-h-80">
+            <div className="space-y-0.5 pr-3">
+              <ImportCandidateList
+                candidates={candidates}
+                selectedKeys={selectedKeys}
+                onSelectionChange={setSelectedKeys}
+              />
+            </div>
+          </ScrollArea>
+        </fieldset>
+      ) : null}
+      {scan.data?.truncated ? (
+        <p className="mt-2 text-xs text-muted-foreground" role="status">
+          {SCAN_LIMIT_MESSAGE}
+        </p>
+      ) : null}
+      {visibleImportError ? (
+        <p className="mt-2 text-sm text-destructive">{visibleImportError}</p>
+      ) : null}
+    </WelcomeSection>
+  );
+}
+
+function PhoneSection() {
+  const [open, setOpen] = useState(false);
+  return (
+    <WelcomeSection title="Phone" status="Optional">
+      <Collapsible open={open} onOpenChange={setOpen}>
+        <div className="flex items-center gap-3 rounded-lg border border-border bg-background px-4 py-3">
+          <SmartphoneIcon className="size-4 shrink-0 text-muted-foreground" />
+          <span className="min-w-0 flex-1 text-sm text-foreground">
+            Use T3 Code from your phone
+          </span>
+          <CollapsibleTrigger render={<Button variant="ghost-muted" size="xs" />}>
+            {open ? "Hide" : "Set up"}
+            <ChevronDownIcon className={cn("size-3.5", open && "rotate-180")} />
+          </CollapsibleTrigger>
+        </div>
+        <CollapsiblePanel>
+          <div className="mt-2 grid grid-cols-1 gap-2 sm:grid-cols-2">
+            <div className="flex items-center gap-4 rounded-lg border border-border bg-background p-3.5">
+              {MOBILE_APP_STORES.map(({ store, url, Icon }) => (
+                <div key={store} className="flex flex-col items-center gap-1.5">
+                  <div className="rounded-md bg-white p-1">
+                    <QRCodeSvg
+                      value={url}
+                      size={76}
+                      level="M"
+                      marginSize={1}
+                      title={`${store} link`}
+                    />
+                  </div>
+                  <span className="inline-flex items-center gap-1 text-2xs text-muted-foreground">
+                    <Icon className="size-3" />
+                    {store}
+                  </span>
+                </div>
+              ))}
+              <span className="text-sm text-muted-foreground">Scan to get the app.</span>
+            </div>
+            <div className="flex flex-col justify-center gap-2 rounded-lg border border-border bg-background p-3.5">
+              {hasCloudPublicConfig() ? (
+                <PhoneConnectLink />
+              ) : (
+                <>
+                  <span className="text-sm text-muted-foreground">
+                    Then pair the app with this computer.
+                  </span>
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    className="self-start"
+                    render={<Link to="/settings/access" />}
+                  >
+                    Show pairing code
+                  </Button>
+                </>
+              )}
+            </div>
+          </div>
+        </CollapsiblePanel>
+      </Collapsible>
+    </WelcomeSection>
+  );
+}
+
+function PhoneConnectLink() {
+  const { isLoaded, isSignedIn } = useAuth({ treatPendingAsSignedOut: false });
+  const { openAuthPrompt } = useT3ConnectAuthPrompt();
+  if (isSignedIn) {
+    return (
+      <span className="inline-flex items-center gap-1.5 text-sm text-foreground">
+        <CheckIcon className="size-4 text-success-foreground" />
+        Signed in to T3 Connect. Use the same account in the app.
+      </span>
+    );
+  }
+  return (
+    <>
+      <span className="text-sm text-muted-foreground">
+        Then sign in here and in the app with the same account.
+      </span>
+      <Button
+        variant="outline"
+        size="sm"
+        className="self-start"
+        disabled={!isLoaded}
+        onClick={openAuthPrompt}
+      >
+        Sign in to T3 Connect
+      </Button>
+    </>
   );
 }
 
 function OnboardingCodexSetup({
-  createdAccount,
-  onAutoStartConsumed,
   environmentId,
   provider,
   serverConfig,
@@ -899,23 +725,15 @@ function OnboardingCodexSetup({
   readonly serverConfig: ServerConfig;
   readonly terminalOpen: boolean;
   readonly onOpenTerminal: () => void;
-  readonly createdAccount: {
-    instanceId: ProviderInstanceId;
-    displayName: string;
-    autoStart: boolean;
-  } | null;
-  readonly onAutoStartConsumed: () => void;
 }) {
   const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
   const update = useAtomCommand(serverEnvironment.updateSettings, "Codex setup settings");
   const instanceId =
-    createdAccount?.instanceId ??
-    provider?.instanceId ??
-    defaultInstanceIdForDriver(ProviderDriverKind.make("codex"));
+    provider?.instanceId ?? defaultInstanceIdForDriver(ProviderDriverKind.make("codex"));
   const settings = serverConfig.settings;
   const instance = settings.providerInstances[instanceId] ?? {
     driver: ProviderDriverKind.make("codex"),
-    config: createdAccount ? { enabled: true, setupMode: "managed" } : {},
+    config: {},
   };
   const mode = readCodexSetupMode(instance.config);
   const existingChosen =
@@ -948,7 +766,7 @@ function OnboardingCodexSetup({
   };
   return existingChosen ? (
     <AgentCard
-      driver="codex"
+      driver={ProviderDriverKind.make("codex")}
       provider={provider}
       terminalOpen={terminalOpen}
       terminalAvailable={canOperateTerminal}
@@ -957,9 +775,6 @@ function OnboardingCodexSetup({
   ) : (
     <CodexSetupSection
       presentation="onboarding"
-      autoStart={createdAccount?.autoStart === true}
-      displayName={createdAccount?.displayName}
-      onAutoStartConsumed={onAutoStartConsumed}
       environmentId={environmentId}
       instanceId={instanceId}
       provider={provider}
@@ -973,35 +788,54 @@ function OnboardingCodexSetup({
 function AgentCard({
   driver,
   provider,
-  terminalOpen,
-  terminalAvailable,
+  terminalOpen = false,
+  terminalAvailable = false,
   onOpenTerminal,
+  settingsLink,
+  compact = false,
 }: {
-  readonly driver: OnboardingAgentDriver;
+  readonly driver: ProviderDriverKind;
   readonly provider: ServerProvider | undefined;
-  readonly terminalOpen: boolean;
-  readonly terminalAvailable: boolean;
-  readonly onOpenTerminal: () => void;
+  readonly terminalOpen?: boolean;
+  readonly terminalAvailable?: boolean;
+  readonly onOpenTerminal?: () => void;
+  // Agents without a one-command install are set up on their Settings page instead.
+  readonly settingsLink?: {
+    readonly environmentId: EnvironmentId;
+    readonly instanceId: ProviderInstanceId;
+  };
+  // A tile for the "Add more agents" grid: the button carries the state, so no detail line.
+  readonly compact?: boolean;
 }) {
-  const meta = providerClients.get(ProviderDriverKind.make(driver));
   const displayName =
-    provider?.displayName || (driver === "claudeAgent" ? "Claude Code" : (meta?.label ?? driver));
+    provider?.displayName ||
+    (driver === "claudeAgent" ? "Claude Code" : (providerClients.get(driver)?.label ?? driver));
   const summary = getProviderSummary(provider);
   const providerState = getOnboardingProviderState(provider);
+  const settingsAction =
+    providerState === "signIn"
+      ? "Sign in"
+      : providerState === "disabled"
+        ? "Turn on"
+        : providerState === "attention"
+          ? "Details"
+          : "Set up";
 
   return (
-    <div className="flex items-center gap-3 rounded-lg border border-border bg-background px-4 py-4">
-      <ProviderInstanceIcon
-        driverKind={ProviderDriverKind.make(driver)}
-        displayName={displayName}
-        iconClassName="size-5"
-      />
+    <div
+      className={cn(
+        "flex items-center gap-3 rounded-lg border border-border bg-background",
+        compact ? "px-3 py-2.5" : "px-4 py-4",
+      )}
+    >
+      <ProviderInstanceIcon driverKind={driver} displayName={displayName} iconClassName="size-5" />
       <div className="min-w-0 flex-1">
         <span className="block text-sm font-medium text-foreground">{displayName}</span>
-        <p className="mt-0.5 text-xs leading-relaxed break-words whitespace-pre-wrap text-muted-foreground">
-          {providerState === "ready" ? "Ready to code." : summary.headline}
-          {providerState !== "ready" && summary.detail ? ` · ${summary.detail}` : ""}
-        </p>
+        {providerState === "ready" || compact ? null : (
+          <p className="mt-0.5 text-xs leading-relaxed break-words whitespace-pre-wrap text-muted-foreground">
+            {providerState === "install" ? "Not installed" : summary.headline}
+          </p>
+        )}
       </div>
       <div className="shrink-0">
         {providerState === "ready" ? (
@@ -1011,9 +845,15 @@ function AgentCard({
           </span>
         ) : providerState === "checking" ? (
           <span className="text-xs text-muted-foreground">Checking...</span>
-        ) : providerState === "disabled" ? (
-          <span className="text-xs text-muted-foreground">Disabled</span>
-        ) : providerState === "attention" ? (
+        ) : settingsLink ? (
+          <Button
+            size="xs"
+            variant="outline"
+            render={<Link to="/settings/providers" search={settingsLink} />}
+          >
+            {settingsAction}
+          </Button>
+        ) : providerState === "disabled" || providerState === "attention" ? (
           <span className="text-xs text-muted-foreground">{summary.headline}</span>
         ) : (
           <Button
@@ -1200,7 +1040,9 @@ interface ImportSelection {
   readonly keys: ReadonlySet<string>;
 }
 
-function ImportStep({
+// Creates the selected projects, then imports each one's agent history. Owns retry state so a
+// second Start resumes instead of recreating projects.
+function useProjectImport({
   scans,
   importSelection,
   onImportSelectionChange,
@@ -1219,7 +1061,6 @@ function ImportStep({
     importedThreadCount?: number,
   ) => Promise<boolean>;
 }) {
-  const { environments } = useEnvironments();
   const writableEnvironments = useEnvironmentsWithScope(scans, AuthOrchestrationOperateScope);
   const createProject = useAtomCommand(projectEnvironment.create, { reportFailure: false });
   const importThreads = useAtomCommand(agentSessionImport, { reportFailure: false });
@@ -1439,127 +1280,16 @@ function ImportStep({
     finishAfterImport();
   };
 
-  if (scans.every((scan) => scan.data === null) && scans.some((scan) => scan.isPending)) {
-    return (
-      <div className="flex h-full min-h-40 flex-col">
-        <h1 className="text-2xl font-semibold tracking-tight text-foreground">Your projects</h1>
-        <div className="flex flex-1 flex-col items-center justify-center gap-3 py-6">
-          <Spinner size="lg" tone="muted" />
-          <p className="text-center text-sm text-muted-foreground">
-            Looking for projects from Claude Code and Codex…
-          </p>
-        </div>
-        <div className="flex justify-end">
-          <Button variant="ghost-muted" onClick={() => void onDone()}>
-            Do not import projects
-          </Button>
-        </div>
-      </div>
-    );
-  }
-
-  return (
-    <StepShell
-      title="Import your projects"
-      description="Import projects and conversations from Claude Code and Codex on your selected computers."
-    >
-      {candidates.length > 0 ? (
-        <div className="mt-5 flex items-center justify-between gap-3 text-xs text-muted-foreground">
-          <span role="status">
-            {selected.length} of {candidates.length} selected
-          </span>
-          <div className="flex items-center gap-1">
-            <Button
-              variant="ghost"
-              size="xs"
-              disabled={isImporting || selected.length === candidates.length}
-              onClick={() => setSelectedKeys(new Set(candidates.map((item) => item.key)))}
-            >
-              Select all
-            </Button>
-            <Button
-              variant="ghost"
-              size="xs"
-              disabled={isImporting || selected.length === 0}
-              onClick={() => setSelectedKeys(new Set())}
-            >
-              Select none
-            </Button>
-          </div>
-        </div>
-      ) : null}
-      <ScrollArea scrollFade className="mt-2 h-auto max-h-80">
-        <div className="space-y-5 pr-3">
-          {scans.map((scan) => {
-            const scanCandidates = candidates.filter(
-              (candidate) => candidate.environmentId === scan.environmentId,
-            );
-            const label =
-              environments.find((environment) => environment.environmentId === scan.environmentId)
-                ?.label ?? "Computer";
-            return (
-              <fieldset
-                key={scan.environmentId}
-                className="min-w-0 space-y-0.5"
-                disabled={isImporting}
-              >
-                {scans.length > 1 ? (
-                  <legend className="mb-2 text-sm font-medium">{label}</legend>
-                ) : null}
-                {scan.isPending && scan.data === null ? (
-                  <div className="flex items-center gap-2 py-3 text-sm text-muted-foreground">
-                    <Spinner size="md" />
-                    Looking for projects…
-                  </div>
-                ) : scan.error !== null ? (
-                  <div
-                    role="alert"
-                    className="flex items-center justify-between gap-3 text-sm text-muted-foreground"
-                  >
-                    <span>Could not check projects. {scan.error}</span>
-                    <Button variant="ghost" size="sm" onClick={scan.refresh}>
-                      Retry
-                    </Button>
-                  </div>
-                ) : scanCandidates.length === 0 ? (
-                  <p className="py-2 text-sm text-muted-foreground">
-                    No existing Claude Code or Codex projects found.
-                  </p>
-                ) : null}
-                {scan.data?.truncated ? (
-                  <p className="text-xs text-muted-foreground" role="status">
-                    {SCAN_LIMIT_MESSAGE}
-                  </p>
-                ) : null}
-                <ImportCandidateList
-                  candidates={scanCandidates}
-                  selectedKeys={selectedKeys}
-                  onSelectionChange={setSelectedKeys}
-                />
-              </fieldset>
-            );
-          })}
-        </div>
-      </ScrollArea>
-      {visibleImportError ? (
-        <p className="mt-3 text-sm text-destructive">{visibleImportError}</p>
-      ) : null}
-      <div className="mt-6 flex flex-wrap items-center justify-end gap-3">
-        <Button variant="ghost-muted" disabled={isImporting} onClick={finishAfterImport}>
-          Do not import projects
-        </Button>
-        <Button
-          autoFocus
-          disabled={!canImport || isImporting || selected.length === 0}
-          onClick={() => void runImport(selected)}
-        >
-          {isImporting
-            ? "Importing…"
-            : `Import ${selected.length} ${selected.length === 1 ? "project" : "projects"}`}
-        </Button>
-      </div>
-    </StepShell>
-  );
+  return {
+    candidates,
+    recent,
+    selected,
+    selectedKeys,
+    setSelectedKeys,
+    visibleImportError,
+    runImport,
+    finishAfterImport,
+  };
 }
 
 type ImportCandidate = AgentSessionProjectCandidate & {
@@ -1823,23 +1553,3 @@ function CliPathSetup() {
     </div>
   );
 }
-
-function StepShell({
-  title,
-  description,
-  children,
-}: {
-  readonly title: string;
-  readonly description?: string;
-  readonly children?: React.ReactNode;
-}) {
-  return (
-    <>
-      <h1 className="text-2xl font-semibold tracking-tight text-foreground">{title}</h1>
-      {description ? (
-        <p className="mt-2.5 text-sm leading-relaxed text-muted-foreground">{description}</p>
-      ) : null}
-      {children}
-    </>
-  );
-}
diff --git a/apps/web/src/components/settings/MobileAppSettingsRow.tsx b/apps/web/src/components/settings/MobileAppSettingsRow.tsx
index 62f4332a40cc8..61f84dfcd7acf 100644
--- a/apps/web/src/components/settings/MobileAppSettingsRow.tsx
+++ b/apps/web/src/components/settings/MobileAppSettingsRow.tsx
@@ -5,7 +5,7 @@ import { QRCodeSvg } from "../ui/qr-code";
 import { SettingsRow } from "./settingsLayout";
 import { searchableSetting } from "./settingsSearch";
 
-const stores = [
+export const MOBILE_APP_STORES = [
   {
     label: "iPhone and iPad",
     store: "App Store",
@@ -27,7 +27,7 @@ export function MobileAppSettingsRow() {
       description="Connect to your server from your phone or tablet."
       control={
         <div className="flex items-center gap-2">
-          {stores.map(({ label, store, url, Icon }) => (
+          {MOBILE_APP_STORES.map(({ label, store, url, Icon }) => (
             <Popover key={store}>
               <PopoverTrigger render={<Button size="sm" variant="outline" />}>
                 <Icon />
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 8df97a2ba0aaa..17b5349e02390 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -2085,6 +2085,15 @@ export function AboutSettingsPanel() {
           </>
         )}
         <MobileAppSettingsRow />
+        <SettingsRow
+          {...searchableSetting("welcome-page")}
+          description="See your agents, bring in projects, and set up your phone."
+          control={
+            <Button size="sm" variant="outline" render={<Link to="/welcome" />}>
+              Open
+            </Button>
+          }
+        />
       </SettingsSection>
 
       <SettingsSection id="legal" title="Legal">
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index 768ce76c2238b..400ef6ae54783 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -856,6 +856,12 @@ export const SETTINGS_SEARCH_ITEMS = [
     to: "/settings/about",
     searchTerms: ["phone tablet iPhone iPad iOS Android App Store Google Play QR"],
   },
+  {
+    id: "welcome-page",
+    title: "Welcome page",
+    to: "/settings/about",
+    searchTerms: ["onboarding setup first run getting started agents import projects"],
+  },
   {
     id: "privacy-policy",
     title: "Privacy policy",
diff --git a/apps/web/src/onboarding/targetEnvironment.logic.test.ts b/apps/web/src/onboarding/targetEnvironment.logic.test.ts
deleted file mode 100644
index 3a882ff92fb6d..0000000000000
--- a/apps/web/src/onboarding/targetEnvironment.logic.test.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import { EnvironmentId } from "@t3tools/contracts";
-import { describe, expect, it } from "vite-plus/test";
-
-import { resolveOnboardingSetup } from "./targetEnvironment.logic";
-
-describe("resolveOnboardingSetup", () => {
-  const computer = (id: string, phase: string) => ({
-    environmentId: EnvironmentId.make(id),
-    connection: { phase },
-  });
-  const local = computer("local", "connected");
-
-  it("skips selected computers that will not connect on their own", () => {
-    const environments = [
-      local,
-      computer("switched-off", "available"),
-      computer("offline", "offline"),
-      computer("failing", "reconnecting"),
-      computer("old-client", "unsupported"),
-    ];
-    expect(
-      resolveOnboardingSetup(
-        environments,
-        new Set(environments.map((environment) => environment.environmentId)),
-      ),
-    ).toEqual({
-      ready: true,
-      environmentIds: [local.environmentId],
-      skippedIds: environments.slice(1).map((environment) => environment.environmentId),
-    });
-  });
-
-  it("waits for a first connection attempt to settle", () => {
-    const connecting = computer("new", "connecting");
-    expect(
-      resolveOnboardingSetup(
-        [local, connecting],
-        new Set([local.environmentId, connecting.environmentId]),
-      ).ready,
-    ).toBe(false);
-  });
-
-  // regression: #16887 onboarding Continue locked up on computers that won't connect
-  it("is not ready without a connected selection", () => {
-    expect(resolveOnboardingSetup([local], new Set()).ready).toBe(false);
-    expect(
-      resolveOnboardingSetup([computer("off", "available")], new Set([EnvironmentId.make("off")]))
-        .ready,
-    ).toBe(false);
-  });
-});
diff --git a/apps/web/src/onboarding/targetEnvironment.logic.ts b/apps/web/src/onboarding/targetEnvironment.logic.ts
deleted file mode 100644
index a217018dbb600..0000000000000
--- a/apps/web/src/onboarding/targetEnvironment.logic.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { type ConnectionCatalogEntry, hasRelayRoute } from "@t3tools/client-runtime/connection";
-import type { EnvironmentId } from "@t3tools/contracts";
-
-interface OnboardingEnvironment {
-  readonly environmentId: EnvironmentId;
-  readonly connection: { readonly phase: string };
-  readonly entry: Pick<ConnectionCatalogEntry, "target" | "alternateRoutes">;
-}
-
-export function isOnboardingRelayEnvironment(
-  environment: Pick<OnboardingEnvironment, "entry">,
-): boolean {
-  return hasRelayRoute(environment.entry);
-}
-
-/** Waits only for first connection attempts; offline, failing, or unsupported computers cannot block setup. */
-export function resolveOnboardingSetup(
-  environments: ReadonlyArray<Pick<OnboardingEnvironment, "environmentId" | "connection">>,
-  selectedIds: ReadonlySet<EnvironmentId>,
-): {
-  readonly ready: boolean;
-  readonly environmentIds: ReadonlyArray<EnvironmentId>;
-  readonly skippedIds: ReadonlyArray<EnvironmentId>;
-} {
-  const selected = environments.filter((environment) => selectedIds.has(environment.environmentId));
-  const idsInPhase = (keep: (phase: string) => boolean) =>
-    selected
-      .filter((environment) => keep(environment.connection.phase))
-      .map((environment) => environment.environmentId);
-  const environmentIds = idsInPhase((phase) => phase === "connected");
-  const settling = selected.some((environment) => environment.connection.phase === "connecting");
-  return {
-    ready: environmentIds.length > 0 && !settling,
-    environmentIds,
-    skippedIds: idsInPhase((phase) => phase !== "connected" && phase !== "connecting"),
-  };
-}
diff --git a/apps/web/src/onboarding/welcomeAgents.logic.test.ts b/apps/web/src/onboarding/welcomeAgents.logic.test.ts
new file mode 100644
index 0000000000000..f07c619cae06b
--- /dev/null
+++ b/apps/web/src/onboarding/welcomeAgents.logic.test.ts
@@ -0,0 +1,54 @@
+import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { groupWelcomeAgents } from "./welcomeAgents.logic";
+
+function provider(name: string, overrides: Partial<ServerProvider> = {}): ServerProvider {
+  return {
+    instanceId: ProviderInstanceId.make(name.toLowerCase()),
+    driver: ProviderDriverKind.make(name.toLowerCase()),
+    displayName: name,
+    enabled: true,
+    installed: true,
+    version: "1.0.0",
+    status: "ready",
+    auth: { status: "authenticated" },
+    checkedAt: "2026-08-23T00:00:00.000Z",
+    models: [],
+    slashCommands: [],
+    skills: [],
+    ...overrides,
+  };
+}
+
+const nameOf = (entry: ServerProvider) => entry.displayName ?? entry.driver;
+const names = (entries: ReadonlyArray<ServerProvider>) => entries.map(nameOf);
+
+describe("groupWelcomeAgents", () => {
+  it("lists agents on the computer by state, then name, and everything else by name", () => {
+    const groups = groupWelcomeAgents(
+      [
+        provider("Zeta", { auth: { status: "unauthenticated" }, status: "error" }),
+        provider("Codex"),
+        provider("Pi", { enabled: false, status: "disabled" }),
+        provider("Grok", { installed: false, status: "error", auth: { status: "unknown" } }),
+        provider("Claude"),
+        provider("Cursor", { installed: false, status: "warning", auth: { status: "unknown" } }),
+      ],
+      nameOf,
+    );
+
+    expect(names(groups.found)).toEqual(["Claude", "Codex", "Zeta"]);
+    expect(names(groups.available)).toEqual(["Grok", "Pi"]);
+    // Cursor is still being checked, so it is in neither group yet.
+    expect(groups.checking).toBe(true);
+  });
+
+  it("reports checking before the computer has sent its providers", () => {
+    expect(groupWelcomeAgents(undefined, nameOf)).toEqual({
+      checking: true,
+      found: [],
+      available: [],
+    });
+  });
+});
diff --git a/apps/web/src/onboarding/welcomeAgents.logic.ts b/apps/web/src/onboarding/welcomeAgents.logic.ts
new file mode 100644
index 0000000000000..5bea1581f52b3
--- /dev/null
+++ b/apps/web/src/onboarding/welcomeAgents.logic.ts
@@ -0,0 +1,36 @@
+import type { ServerProvider } from "@t3tools/contracts";
+
+import { getOnboardingProviderState } from "./providerReadiness.logic";
+
+// Ready agents first, then ones that need a sign-in or a look. Never ranked by vendor.
+const FOUND_ORDER = { ready: 0, signIn: 1, attention: 2 } as const;
+type FoundState = keyof typeof FOUND_ORDER;
+
+const isFoundState = (state: string): state is FoundState => state in FOUND_ORDER;
+
+/**
+ * Splits a computer's providers into agents already on it and agents the user can add.
+ * Order inside each group is by state, then by the name the user sees.
+ */
+export function groupWelcomeAgents(
+  providers: ReadonlyArray<ServerProvider> | null | undefined,
+  nameOf: (provider: ServerProvider) => string,
+) {
+  const found: ServerProvider[] = [];
+  const available: ServerProvider[] = [];
+  let checking = providers == null;
+  for (const provider of providers ?? []) {
+    const state = getOnboardingProviderState(provider);
+    if (state === "checking") checking = true;
+    else if (isFoundState(state)) found.push(provider);
+    else available.push(provider);
+  }
+  const byName = (a: ServerProvider, b: ServerProvider) => nameOf(a).localeCompare(nameOf(b));
+  const foundRank = (provider: ServerProvider) => {
+    const state = getOnboardingProviderState(provider);
+    return isFoundState(state) ? FOUND_ORDER[state] : FOUND_ORDER.attention;
+  };
+  found.sort((a, b) => foundRank(a) - foundRank(b) || byName(a, b));
+  available.sort(byName);
+  return { checking, found, available };
+}
diff --git a/apps/web/src/routes/welcome.tsx b/apps/web/src/routes/welcome.tsx
index 5415f01e210f3..e01a918f4f901 100644
--- a/apps/web/src/routes/welcome.tsx
+++ b/apps/web/src/routes/welcome.tsx
@@ -5,8 +5,9 @@ import * as Schema from "effect/Schema";
 import * as Option from "effect/Option";
 
 import { NoProjectsHero } from "../components/NoProjectsHero";
-import { WelcomeWizard } from "../components/onboarding/WelcomeWizard";
+import { WelcomePage } from "../components/onboarding/WelcomePage";
 import { useNewThreadHandler } from "../hooks/useHandleNewThread";
+import { usePrimaryEnvironmentId } from "../state/environments";
 
 const decodeEnvironmentId = Schema.decodeOption(EnvironmentId);
 
@@ -21,36 +22,33 @@ export const Route = createFileRoute("/welcome")({
 });
 
 function WelcomeRouteView() {
-  const { authGateState } = Route.useRouteContext();
   const navigate = useNavigate();
   const hash = useLocation({ select: (location) => location.hash });
+  // A ChatGPT sign-in returns here with the computer it set up.
   const resumeEnvironmentId = hash.startsWith("agents:")
     ? Option.getOrUndefined(decodeEnvironmentId(hash.slice("agents:".length)))
     : undefined;
+  const primaryEnvironmentId = usePrimaryEnvironmentId();
+  const environmentId = resumeEnvironmentId ?? primaryEnvironmentId;
   // The root can remount this pending outlet after navigation; do not reopen setup.
   const isWelcomeRoute = useLocation({ select: (location) => location.pathname === "/welcome" });
   const [dismissed, setDismissed] = useState(false);
   const openNewThread = useNewThreadHandler();
-  const localAvailable = authGateState.status === "authenticated";
+  if (environmentId === null || !isWelcomeRoute || dismissed) return <NoProjectsHero />;
   return (
-    <>
-      <NoProjectsHero />
-      {isWelcomeRoute && !dismissed ? (
-        <WelcomeWizard
-          localAvailable={localAvailable}
-          resumeEnvironmentId={resumeEnvironmentId}
-          onDone={async (projectRef) => {
-            setDismissed(true);
-            if (projectRef !== undefined) {
-              await openNewThread(projectRef, { replace: true }).catch(() =>
-                navigate({ to: "/", replace: true }),
-              );
-              return;
-            }
-            await navigate({ to: "/", replace: true });
-          }}
-        />
-      ) : null}
-    </>
+    <WelcomePage
+      key={environmentId}
+      environmentId={environmentId}
+      onDone={async (projectRef) => {
+        setDismissed(true);
+        if (projectRef !== undefined) {
+          await openNewThread(projectRef, { replace: true }).catch(() =>
+            navigate({ to: "/", replace: true }),
+          );
+          return;
+        }
+        await navigate({ to: "/", replace: true });
+      }}
+    />
   );
 }
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
new file mode 100644
index 0000000000000..23b757b907746
--- /dev/null
+++ b/docs/user/welcome-page.md
@@ -0,0 +1,89 @@
+# Welcome page
+
+T3 Code shows a Welcome page when you open a new installation. Existing
+workspaces skip it. It shows what T3 Code found on the computer you are using,
+on one page: your agents, projects from your Claude Code and Codex history, and
+the phone app. Only an agent is needed to start chatting.
+
+To see the page again, go to **Settings → About → Welcome page** and select
+**Open**. Direct links, such as Settings, open normally before setup is done.
+
+The hosted app at app.t3.codes does not open the page. With no computer connected,
+it asks you to sign in to T3 Connect, then to install T3 Code and run
+`t3 connect` on your computer. From home, it adds compatible computers linked to your account and
+opens the app. To add more computers later, use **Settings → Environments**.
+
+If T3 Code cannot confirm the workspace during startup, it shows
+**Still connecting** instead of opening the app. Select **Reload** to try again.
+
+If T3 Code cannot read your saved settings, it shows **Could not read settings**.
+Select **Retry** after storage becomes available. Setup does not replace
+unreadable settings with defaults.
+
+## Agents
+
+T3 Code lists the agents it found on the computer first, ready ones on top. If
+Claude Code or Codex needs a sign-in or install, select its action to open a
+terminal with the correct command ready to run. Install uses the vendor's own
+installer, which keeps **Update now** working in Settings. Codex can also sign in
+with your ChatGPT account.
+
+**Add more agents** lists every other agent T3 Code supports. Agents without a
+one-command install open their page in **Settings → Providers**. **Browse**
+opens the ACP Registry for more agents. When no agent is found, this list opens
+by itself.
+
+The setup terminal uses the home directory and environment configured for the
+provider instance. Sensitive values remain redacted in Settings and
+terminal metadata while the terminal process can use them.
+
+**Start** waits for one ready agent. Select **Skip for now** to start without one.
+
+## Phone
+
+Select **Set up** to show QR codes for the App Store and Google Play. Then sign
+in to T3 Connect with the same account in the app, or pair the app from
+**Settings → Sharing & access** on builds without T3 Connect.
+
+## Projects
+
+T3 Code finds directories that Claude Code, Codex or Pi has used. Git repositories
+are listed first, newest activity on top. When the remote is on GitHub, the
+group shows the repository as `owner/name`. Clones with the same remote share
+one group. Directories that are not git repositories sit under "Other folders".
+
+The page offers git repositories active within the last 30 days with at least
+three conversations, already checked. Uncheck the row to start without them, or
+select **Review** to pick from everything found, with "Select all" and
+"Select none". Linked worktrees of bare repositories
+can be offered as separate projects. Other linked git worktrees, Codex scratch
+directories under `Documents/Codex`, and anything under `Downloads` are not
+offered.
+
+A large or malformed history can reach the scan limit. T3 Code keeps the
+projects it found and warns when projects or conversations may be missing.
+
+Imported projects include Claude, Codex and Pi conversations active within the last
+30 days. You can continue those conversations in T3 Code. Pi is off by default:
+enable it in Settings, then open the Welcome page again to import its sessions. Pi sessions
+are read from each enabled Pi provider's session directory, which follows
+`PI_CODING_AGENT_SESSION_DIR` and `PI_CODING_AGENT_DIR` in its environment. A
+Pi conversation imports its active branch, the one Pi reopens.
+
+Conversation import is best effort. T3 Code keeps the first user prompt and the
+newest remaining visible user and assistant messages, with 200 messages total.
+It omits tool activity and attachments. For Codex, it omits generated setup
+context only when a canonical user event and a valid shared turn ID identify the
+same user turn. Ambiguous legacy or response-only context stays in the imported
+conversation so T3 Code does not remove user text. It reads one conversation at
+a time and skips files larger than 4 GiB. It also skips a conversation when the
+message text and metadata it keeps need more than 32 MiB of memory. Tool output
+does not count toward that limit. It ignores malformed records and skips
+unreadable or unparseable conversations.
+
+Each import attempt reads up to 100 conversation files and 4 GiB per project,
+with up to 100,000 input records. Run import again to continue a large batch.
+Completed conversations are not imported again. You can continue without the
+remaining history.
+
+You can start without importing. Navigation pauses while an import is running.
diff --git a/docs/user/welcome-wizard.md b/docs/user/welcome-wizard.md
deleted file mode 100644
index 6e3a9dc12f562..0000000000000
--- a/docs/user/welcome-wizard.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Welcome wizard
-
-T3 Code shows a setup flow when you open a new installation. Existing
-workspaces skip this flow.
-
-The hosted app at app.t3.codes does not open setup. With no computer connected,
-it asks you to sign in to T3 Connect, then to install T3 Code and run
-`t3 connect` on your computer. From home, it adds compatible computers linked to your account and
-opens the app.
-
-Close setup while no import is running to go straight to the app. You can connect
-computers and agents later from Settings, or open `/welcome` to run setup again.
-Direct links, such as Settings, open normally before setup is done.
-
-## Connect your computers
-
-Select one or more computers to set up. If you opened T3 Code directly from a
-server or the desktop app, that computer is already connected and selected.
-It is identified by its name, which may differ from the device running your
-browser.
-
-You can add more computers before continuing:
-
-- **T3 Connect** connects computers that are signed in to your account.
-  [Install the CLI](./install.md#command-line) and run `t3 connect` on each
-  computer you want to add, then start T3 Code or run `t3 serve` so the
-  computer stays available.
-- **Add a computer** connects directly to a server on your network or tailnet.
-  Start the server with `t3 serve`, then run `t3 pair --tailscale` and paste
-  the pairing link. You can also run `t3 serve --host <address>` and use
-  `t3 pair` when the server is already reachable on your network.
-
-A computer marked **Client not supported** runs a T3 Code version that cannot
-talk to this app. The message under its name says which side to update.
-
-Saved computers and computers discovered through T3 Connect are selected by
-default. Uncheck any you do not want to set up; this does not disconnect them.
-Continue when your selected computers are connected. Setup checks
-agents across the selected computers, then offers project import grouped by computer.
-
-If T3 Code cannot confirm the workspace during startup, the setup flow shows
-**Still connecting** instead of opening the app. Select **Reload** to try again.
-
-If T3 Code cannot read your saved settings, it shows **Could not read settings**.
-Select **Retry** after storage becomes available. Setup does not replace
-unreadable settings with defaults.
-
-## Check your agents
-
-T3 Code checks each selected computer for Claude Code and Codex. If an agent is
-not installed or signed in, select its action to open a terminal with the
-correct command ready to run. Install uses the vendor's own installer, which
-keeps **Update now** working in Settings. Other providers can be enabled in
-Settings.
-
-The setup terminal uses the home directory and environment configured for the
-selected provider instance. Sensitive values remain redacted in Settings and
-terminal metadata while the terminal process can use them.
-
-## Import your projects
-
-T3 Code finds directories that Claude Code, Codex or Pi has used. Git repositories
-are listed first, newest activity on top. When the remote is on GitHub, the
-group shows the repository as `owner/name`. Clones with the same remote share
-one group. Directories that are not git repositories sit under "Other folders".
-
-The default selection includes git repositories active within the last 30 days
-with at least three conversations. Use the checkboxes, or "Select all" and
-"Select none", to change the selection. Linked worktrees of bare repositories
-can be offered as separate projects. Other linked git worktrees, Codex scratch
-directories under `Documents/Codex`, and anything under `Downloads` are not
-offered.
-
-A large or malformed history can reach the scan limit. T3 Code keeps the
-projects it found and warns when projects or conversations may be missing.
-
-Imported projects include Claude, Codex and Pi conversations active within the last
-30 days. You can continue those conversations in T3 Code. Pi is off by default:
-enable it in Settings, then open `/welcome` to import its sessions. Pi sessions
-are read from each enabled Pi provider's session directory, which follows
-`PI_CODING_AGENT_SESSION_DIR` and `PI_CODING_AGENT_DIR` in its environment. A
-Pi conversation imports its active branch, the one Pi reopens.
-
-Conversation import is best effort. T3 Code keeps the first user prompt and the
-newest remaining visible user and assistant messages, with 200 messages total.
-It omits tool activity and attachments. For Codex, it omits generated setup
-context only when a canonical user event and a valid shared turn ID identify the
-same user turn. Ambiguous legacy or response-only context stays in the imported
-conversation so T3 Code does not remove user text. It reads one conversation at
-a time and skips files larger than 4 GiB. It also skips a conversation when the
-message text and metadata it keeps need more than 32 MiB of memory. Tool output
-does not count toward that limit. It ignores malformed records and skips
-unreadable or unparseable conversations.
-
-Each import attempt reads up to 100 conversation files and 4 GiB per project,
-with up to 100,000 input records. Run import again to continue a large batch.
-Completed conversations are not imported again. You can continue without the
-remaining history.
-
-You can continue without configuring agents or importing projects, or return to an earlier step
-using the setup progress bar. Navigation pauses while an import is running.

From b10edffc2a6bd5109f86f0f396175e7d0c49400a Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 18:37:19 -0800
Subject: [PATCH 02/22] fix(web): Welcome page links the phone, keeps imports
 running, and lists agents A to Z

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       |  23 ++
 .../src/components/onboarding/WelcomePage.tsx | 237 ++++++++++++------
 apps/web/src/routes/__root.tsx                |   2 +
 3 files changed, 180 insertions(+), 82 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index 900edc1cda5bf..079f2dc0a9bf8 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -357,3 +357,26 @@ it("waits for a ready agent to start, and Skip for now still finishes setup", as
   await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
   expect(state.createProject).toHaveBeenCalledTimes(2);
 });
+
+it("stays on the page while projects import, then lands as usual", async () => {
+  using _now = setup();
+  const creation = deferred<void>();
+  state.createProject.mockImplementationOnce(async (input: CreateProjectInput) => {
+    await creation.promise;
+    return recordProject(input);
+  });
+  await using screen = await mountWelcome();
+  await click("Add 2 projects and start");
+
+  // A blocked navigation never settles, so it is not awaited.
+  await act(async () => {
+    void screen.router?.navigate({ to: "/settings" });
+  });
+  await act(async () => {
+    creation.resolve();
+    await creation.promise;
+  });
+  await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
+  expect(screen.router?.state.location.pathname).toBe("/");
+  expect(state.createProject).toHaveBeenCalledTimes(2);
+});
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index 0804da9c022d2..cac43e5a61615 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -21,7 +21,7 @@ import {
   ProviderDriverKind,
   ThreadId,
 } from "@t3tools/contracts";
-import { Link } from "@tanstack/react-router";
+import { Link, useBlocker } from "@tanstack/react-router";
 import * as Schema from "effect/Schema";
 import {
   CheckIcon,
@@ -321,6 +321,7 @@ function AgentsSection({
   const [terminalSession, setTerminalSession] = useState<AgentTerminalSession | null>(null);
   const [moreOpen, setMoreOpen] = useState<boolean | null>(null);
   const [addingProvider, setAddingProvider] = useState(false);
+  const [codexSetupId, setCodexSetupId] = useState<ProviderInstanceId | null>(null);
 
   // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- asks the environment to refresh its provider list when the environment changes
   useEffect(() => {
@@ -364,7 +365,7 @@ function AgentsSection({
     });
   };
 
-  const renderAgent = (provider: ServerProvider, compact = false) => {
+  const renderAgent = (provider: ServerProvider) => {
     const terminalOpen = terminalSession?.providerInstanceId === provider.instanceId;
     const ready = getOnboardingProviderState(provider) === "ready";
     if (ready) {
@@ -399,12 +400,61 @@ function AgentsSection({
         key={provider.instanceId}
         driver={provider.driver}
         provider={provider}
-        compact={compact}
         settingsLink={{ environmentId, instanceId: provider.instanceId }}
       />
     );
   };
 
+  // Same tile for every agent so the list stays in neutral A to Z order.
+  const renderTile = (provider: ServerProvider) => {
+    const state = getOnboardingProviderState(provider);
+    if (provider.driver === "codex" && serverConfig !== null) {
+      const open = codexSetupId === provider.instanceId;
+      return (
+        <AgentCard
+          key={provider.instanceId}
+          driver={provider.driver}
+          provider={provider}
+          compact
+          action={
+            <Button
+              size="xs"
+              variant="outline"
+              aria-expanded={open}
+              onClick={() => setCodexSetupId(open ? null : provider.instanceId)}
+            >
+              Set up
+            </Button>
+          }
+        />
+      );
+    }
+    if (isInstallableDriver(provider.driver) && (state === "install" || state === "signIn")) {
+      return (
+        <AgentCard
+          key={provider.instanceId}
+          driver={provider.driver}
+          provider={provider}
+          compact
+          terminalOpen={terminalSession?.providerInstanceId === provider.instanceId}
+          terminalAvailable={serverConfig !== null && canOperateTerminal}
+          onOpenTerminal={() => openTerminal(provider)}
+        />
+      );
+    }
+    return (
+      <AgentCard
+        key={provider.instanceId}
+        driver={provider.driver}
+        provider={provider}
+        compact
+        settingsLink={{ environmentId, instanceId: provider.instanceId }}
+      />
+    );
+  };
+  const codexSetupProvider =
+    available.find((provider) => provider.instanceId === codexSetupId) ?? null;
+
   return (
     <WelcomeSection
       title="Agents"
@@ -442,14 +492,18 @@ function AgentsSection({
         </CollapsibleTrigger>
         <CollapsiblePanel>
           <div className="space-y-1.5 pt-1">
-            {available
-              .filter((provider) => isInstallableDriver(provider.driver))
-              .map((provider) => renderAgent(provider))}
             <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-2">
-              {available
-                .filter((provider) => !isInstallableDriver(provider.driver))
-                .map((provider) => renderAgent(provider, true))}
+              {available.map(renderTile)}
             </div>
+            {codexSetupProvider !== null && serverConfig !== null ? (
+              <OnboardingCodexSetup
+                environmentId={environmentId}
+                provider={codexSetupProvider}
+                serverConfig={serverConfig}
+                terminalOpen={terminalSession?.providerInstanceId === codexSetupProvider.instanceId}
+                onOpenTerminal={() => openTerminal(codexSetupProvider)}
+              />
+            ) : null}
             <div className="flex items-center justify-between gap-3 rounded-lg border border-dashed border-border px-4 py-3">
               <span className="inline-flex items-center gap-2 text-sm text-muted-foreground">
                 <ACPRegistryIcon className="size-4" />
@@ -793,6 +847,7 @@ function AgentCard({
   onOpenTerminal,
   settingsLink,
   compact = false,
+  action,
 }: {
   readonly driver: ProviderDriverKind;
   readonly provider: ServerProvider | undefined;
@@ -806,6 +861,7 @@ function AgentCard({
   };
   // A tile for the "Add more agents" grid: the button carries the state, so no detail line.
   readonly compact?: boolean;
+  readonly action?: ReactNode;
 }) {
   const displayName =
     provider?.displayName ||
@@ -845,6 +901,8 @@ function AgentCard({
           </span>
         ) : providerState === "checking" ? (
           <span className="text-xs text-muted-foreground">Checking...</span>
+        ) : action ? (
+          action
         ) : settingsLink ? (
           <Button
             size="xs"
@@ -858,7 +916,7 @@ function AgentCard({
         ) : (
           <Button
             size="xs"
-            variant="ghost"
+            variant={compact ? "outline" : "ghost"}
             onClick={onOpenTerminal}
             disabled={terminalOpen || !terminalAvailable}
           >
@@ -1073,6 +1131,12 @@ function useProjectImport({
     new Map<string, { readonly projectId: ProjectId; readonly commandId: CommandId }>(),
   );
   const importGenerationRef = useRef(0);
+  const importLoopRef = useRef(false);
+  // Leaving mid-import would abandon the remaining projects and their retry state.
+  useBlocker({
+    shouldBlockFn: () => importLoopRef.current,
+    enableBeforeUnload: () => importLoopRef.current,
+  });
 
   // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- bumps the import generation on mount and unmount so in-flight imports drop stale results
   useEffect(() => {
@@ -1178,89 +1242,98 @@ function useProjectImport({
     let importedThreadCount = 0;
     let skippedThreadCount = 0;
     const refreshEnvironments = new Set<EnvironmentId>();
-    for (const candidate of selection) {
-      const { environmentId } = candidate;
-      if (
-        importGeneration !== importGenerationRef.current ||
-        importedProjects !== importedProjectsRef.current
-      ) {
-        return;
-      }
-      if (!hasAccess()) {
-        stopForDeniedAccess();
-        return;
-      }
-      if (importedProjects.has(candidate.key)) continue;
-      let projectId = resolveOnboardingProjectId(readProjects(), environmentId, candidate);
-      if (projectId === null) {
-        let attempt = projectAttempts.get(candidate.key);
-        if (attempt === undefined) {
-          const nextProjectId = newProjectId();
-          attempt = {
-            projectId: nextProjectId,
-            commandId: CommandId.make(`onboarding:project:create:${nextProjectId}`),
-          };
-          projectAttempts.set(candidate.key, attempt);
-        }
-        projectId = attempt.projectId;
-        const result = await createProject({
-          environmentId,
-          input: {
-            projectId,
-            commandId: attempt.commandId,
-            title: candidate.title,
-            workspaceRoot: candidate.path,
-            createWorkspaceRootIfMissing: false,
-            defaultModelSelection: null,
-          },
-        });
+    // Resolves false when the run stopped early: a newer run, an unmount, or lost access.
+    const importEach = async () => {
+      for (const candidate of selection) {
+        const { environmentId } = candidate;
         if (
           importGeneration !== importGenerationRef.current ||
           importedProjects !== importedProjectsRef.current
         ) {
-          return;
+          return false;
+        }
+        if (!hasAccess()) {
+          stopForDeniedAccess();
+          return false;
         }
-        if (result._tag !== "Success") {
-          if (!isAtomCommandInterrupted(result)) {
-            projectAttempts.delete(candidate.key);
-            refreshEnvironments.add(environmentId);
+        if (importedProjects.has(candidate.key)) continue;
+        let projectId = resolveOnboardingProjectId(readProjects(), environmentId, candidate);
+        if (projectId === null) {
+          let attempt = projectAttempts.get(candidate.key);
+          if (attempt === undefined) {
+            const nextProjectId = newProjectId();
+            attempt = {
+              projectId: nextProjectId,
+              commandId: CommandId.make(`onboarding:project:create:${nextProjectId}`),
+            };
+            projectAttempts.set(candidate.key, attempt);
+          }
+          projectId = attempt.projectId;
+          const result = await createProject({
+            environmentId,
+            input: {
+              projectId,
+              commandId: attempt.commandId,
+              title: candidate.title,
+              workspaceRoot: candidate.path,
+              createWorkspaceRootIfMissing: false,
+              defaultModelSelection: null,
+            },
+          });
+          if (
+            importGeneration !== importGenerationRef.current ||
+            importedProjects !== importedProjectsRef.current
+          ) {
+            return false;
+          }
+          if (result._tag !== "Success") {
+            if (!isAtomCommandInterrupted(result)) {
+              projectAttempts.delete(candidate.key);
+              refreshEnvironments.add(environmentId);
+            }
+            continue;
           }
-          continue;
         }
-      }
 
-      if (!hasAccess()) {
-        stopForDeniedAccess();
-        return;
-      }
-      const threadImportResult = await importThreads({
-        environmentId,
-        input: { projectId, expectedWorkspaceRoot: candidate.path },
-      });
-      if (
-        importGeneration !== importGenerationRef.current ||
-        importedProjects !== importedProjectsRef.current
-      ) {
-        return;
-      }
-      if (threadImportResult._tag === "Success") {
-        importedThreadCount += threadImportResult.value.importedCount;
-        skippedThreadCount += threadImportResult.value.skippedCount;
-        if (threadImportResult.value.importedCount > 0) {
-          projectsWithImportedHistoryRef.current.set(
-            candidate.key,
-            scopeProjectRef(environmentId, projectId),
-          );
+        if (!hasAccess()) {
+          stopForDeniedAccess();
+          return false;
         }
-        if (threadImportResult.value.skippedCount === 0) {
-          importedProjectsCount += 1;
-          importedProjects.set(candidate.key, scopeProjectRef(environmentId, projectId));
+        const threadImportResult = await importThreads({
+          environmentId,
+          input: { projectId, expectedWorkspaceRoot: candidate.path },
+        });
+        if (
+          importGeneration !== importGenerationRef.current ||
+          importedProjects !== importedProjectsRef.current
+        ) {
+          return false;
+        }
+        if (threadImportResult._tag === "Success") {
+          importedThreadCount += threadImportResult.value.importedCount;
+          skippedThreadCount += threadImportResult.value.skippedCount;
+          if (threadImportResult.value.importedCount > 0) {
+            projectsWithImportedHistoryRef.current.set(
+              candidate.key,
+              scopeProjectRef(environmentId, projectId),
+            );
+          }
+          if (threadImportResult.value.skippedCount === 0) {
+            importedProjectsCount += 1;
+            importedProjects.set(candidate.key, scopeProjectRef(environmentId, projectId));
+          }
+        } else if (!isAtomCommandInterrupted(threadImportResult)) {
+          projectAttempts.delete(candidate.key);
+          refreshEnvironments.add(environmentId);
         }
-      } else if (!isAtomCommandInterrupted(threadImportResult)) {
-        projectAttempts.delete(candidate.key);
-        refreshEnvironments.add(environmentId);
       }
-    }
+      return true;
+    };
+    importLoopRef.current = true;
+    const completed = await importEach().finally(() => {
+      importLoopRef.current = false;
+    });
+    if (!completed) return;
     for (const scan of scans) {
       if (refreshEnvironments.has(scan.environmentId)) scan.refresh();
     }
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 1207b5017100d..d4e40af9a4263 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -167,6 +167,8 @@ function RootRouteBranch() {
   if (pathname === "/welcome") {
     return (
       <>
+        {/* The Welcome page can sign in to T3 Connect; this links the computer for the phone. */}
+        <ConnectOnboardingDialog />
         <CustomSnoozeDialogHost />
         <GuestShareDialogHost />
         <CommandPalette>

From 0d68b1ee24b9aaf67ede120b2751b2b95eba9510 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 18:45:32 -0800
Subject: [PATCH 03/22] fix(web): Welcome page turns agents on in place and
 respects policy and access

- "Turn on" enables an off agent in place with a one-instance upsert, so an
  installed agent shows up without leaving the page.
- Codex setup stays mounted by instance while its status changes.
- Start counts only agents the managed policy allows.
- Without import access, starting skips the projects instead of stalling.
- "Start without an agent" says what the button does.
- ACP Registry follows policy and provider-manage access, and opens with the
  registry search in view.
- The Settings row and the agents: return link only use known computers.
- The Add to PATH row from the old wizard moves onto the page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       |  24 +-
 .../src/components/onboarding/WelcomePage.tsx | 443 +++++++++---------
 .../settings/AddProviderInstanceDialog.tsx    |   5 +-
 .../components/settings/SettingsPanels.tsx    |  28 +-
 .../src/components/settings/settingsSearch.ts |   2 +
 .../providerReadiness.logic.test.ts           |  44 --
 .../src/onboarding/providerReadiness.logic.ts |  28 --
 .../onboarding/welcomeAgents.logic.test.ts    |  21 +-
 .../web/src/onboarding/welcomeAgents.logic.ts |  13 +-
 apps/web/src/routes/welcome.tsx               |  10 +-
 docs/user/install.md                          |   2 +-
 docs/user/welcome-page.md                     |  36 +-
 12 files changed, 320 insertions(+), 336 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index 079f2dc0a9bf8..6e188150f0cf0 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -57,20 +57,12 @@ vi.mock(import("../../onboarding/firstRun"), async (original) => ({
   ...(await original()),
   completeOnboarding: state.completeOnboarding,
 }));
-vi.mock(import("../../state/environments"), async (original) => {
-  const environment = (environmentId: string) => ({
-    environmentId,
-    label: environmentId,
-    connection: { phase: "connected" },
-    entry: { enabled: true, target: { _tag: "DirectConnectionTarget" } },
-  });
-  const primary = environment("primary");
-  return {
-    ...(await original()),
-    usePrimaryEnvironment: (() => primary) as never,
-    useEnvironments: (() => ({ environments: [primary] })) as never,
-  };
-});
+vi.mock(import("../../state/environments"), async (original) => ({
+  ...(await original()),
+  useEnvironments: (() => ({
+    environments: [{ environmentId: "primary", label: "primary" }],
+  })) as never,
+}));
 vi.mock(import("../../state/server"), async (original) => {
   const actual = await original();
   return {
@@ -347,13 +339,13 @@ it("finishes setup without landing when the imported project never reaches the c
   expect(state.onDone).toHaveBeenCalledWith(undefined);
 });
 
-it("waits for a ready agent to start, and Skip for now still finishes setup", async () => {
+it("waits for a ready agent to start, and Start without an agent still finishes setup", async () => {
   using _now = setup();
   appAtomRegistry.set(state.providers as Atom.Writable<ReadonlyArray<ServerProvider>>, []);
   await using _screen = await mountWelcome();
   expect(button("Add 2 projects and start").disabled).toBe(true);
 
-  await click("Skip for now");
+  await click("Start without an agent");
   await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
   expect(state.createProject).toHaveBeenCalledTimes(2);
 });
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index cac43e5a61615..e075217025854 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -13,9 +13,9 @@ import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime/environ
 import { isAtomCommandInterrupted } from "@t3tools/client-runtime/state/runtime";
 import {
   AgentSessionSource,
+  AuthProvidersManageScope,
   AuthTerminalOperateScope,
   CommandId,
-  defaultInstanceIdForDriver,
   AuthOrchestrationOperateScope,
   isManagedDriverAllowed,
   ProviderDriverKind,
@@ -35,6 +35,7 @@ import { useEffect, useRef, useState, type ReactNode } from "react";
 import { TYPOGRAPHY_ADVANCED_STORAGE_KEY } from "../../appearanceFonts";
 import { isElectron } from "../../env";
 import { useLocalStorage } from "../../hooks/useLocalStorage";
+import { usePersistEnvironmentProviderInstanceMutation } from "../../hooks/useSettings";
 import { hasCloudPublicConfig } from "../../cloud/publicConfig";
 import { PRIVACY_POLICY_URL } from "../../legalLinks";
 import { workspaceAreaProps } from "../../lib/workspaceFocus";
@@ -78,7 +79,6 @@ import { useDesktopCliCommand } from "../settings/CliCommandSettingsRow";
 import { CodexSetupSection } from "../settings/CodexSetupSection";
 import { readCodexSetupMode } from "../settings/CodexSetupSection.logic";
 import { MOBILE_APP_STORES } from "../settings/MobileAppSettingsRow";
-import { buildProviderInstanceUpdatePatch } from "../settings/SettingsPanels.logic";
 import { TerminalViewport } from "../ThreadTerminalDrawer";
 import { ProviderInstanceIcon } from "../chat/ProviderInstanceIcon";
 import { ACPRegistryIcon } from "../Icons";
@@ -112,9 +112,7 @@ export function WelcomePage({
   const label =
     environments.find((environment) => environment.environmentId === environmentId)?.label ??
     "this computer";
-  const providers = useAtomValue(serverEnvironment.providersValueAtom(environmentId));
-  const agentReady =
-    providers?.some((provider) => getOnboardingProviderState(provider) === "ready") ?? false;
+  const agentReady = useWelcomeAgents(environmentId).readyCount > 0;
   const scans = useProjectScans([environmentId]);
   const [importSelection, setImportSelection] = useState<ImportSelection | null>(null);
   const [isImporting, setIsImporting] = useState(false);
@@ -182,7 +180,8 @@ export function WelcomePage({
     setIsImporting,
     onDone: finish,
   });
-  const selectedCount = projectImport.selected.length;
+  // Without import permission, starting simply skips the projects.
+  const selectedCount = projectImport.canWrite ? projectImport.selected.length : 0;
   const start = () => {
     if (selectedCount > 0) void projectImport.runImport(projectImport.selected);
     else projectImport.finishAfterImport();
@@ -218,7 +217,7 @@ export function WelcomePage({
                 <span />
               ) : (
                 <Button variant="ghost-muted" disabled={isImporting} onClick={start}>
-                  Skip for now
+                  Start without an agent
                 </Button>
               )}
               <div className="flex items-center gap-3">
@@ -305,6 +304,22 @@ function agentName(provider: ServerProvider) {
   );
 }
 
+// Shared by the page (to enable Start) and the agents section, so both agree on what is ready.
+function useWelcomeAgents(environmentId: EnvironmentId) {
+  const providers = useAtomValue(serverEnvironment.providersValueAtom(environmentId));
+  const serverConfig = useAtomValue(serverEnvironment.configValueAtom(environmentId));
+  const managedPolicy = serverConfig?.managedPolicy;
+  return {
+    providers,
+    serverConfig,
+    ...groupWelcomeAgents(providers, agentName, (provider) =>
+      isManagedDriverAllowed(managedPolicy, provider.driver),
+    ),
+  };
+}
+
+const ACP_REGISTRY_DRIVER_KIND = ProviderDriverKind.make("acpRegistry");
+
 function AgentsSection({
   environmentId,
   label,
@@ -312,12 +327,14 @@ function AgentsSection({
   readonly environmentId: EnvironmentId;
   readonly label: string;
 }) {
-  const providers = useAtomValue(serverEnvironment.providersValueAtom(environmentId));
+  const { providers, serverConfig, checking, readyCount, found, available } =
+    useWelcomeAgents(environmentId);
   const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
     reportFailure: false,
   });
-  const serverConfig = useAtomValue(serverEnvironment.configValueAtom(environmentId));
+  const persistProviderInstance = usePersistEnvironmentProviderInstanceMutation(environmentId);
   const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
+  const canManageProviders = useEnvironmentScope(environmentId, AuthProvidersManageScope);
   const [terminalSession, setTerminalSession] = useState<AgentTerminalSession | null>(null);
   const [moreOpen, setMoreOpen] = useState<boolean | null>(null);
   const [addingProvider, setAddingProvider] = useState(false);
@@ -328,16 +345,16 @@ function AgentsSection({
     void refreshProviders({ environmentId, input: {} });
   }, [environmentId, refreshProviders]);
 
-  const managedPolicy = serverConfig?.managedPolicy;
-  const { checking, found, available } = groupWelcomeAgents(
-    providers?.filter((provider) => isManagedDriverAllowed(managedPolicy, provider.driver)),
-    agentName,
-  );
   // With nothing on this computer yet, the list of agents to add is the main task.
-  const showMore = moreOpen ?? (!checking && found.length === 0);
-  const readyCount = found.filter(
-    (provider) => getOnboardingProviderState(provider) === "ready",
-  ).length;
+  const showMore = moreOpen ?? found.length === 0;
+  const acpAllowed = isManagedDriverAllowed(serverConfig?.managedPolicy, ACP_REGISTRY_DRIVER_KIND);
+  // Codex setup stays mounted by instance while its status changes, so a sign-in that
+  // starts after an install is not lost when the agent moves between groups.
+  const codexSetupProvider =
+    providers?.find(
+      (provider) =>
+        provider.instanceId === codexSetupId && getOnboardingProviderState(provider) !== "ready",
+    ) ?? null;
 
   const openTerminal = (provider: ServerProvider) => {
     if (
@@ -365,95 +382,79 @@ function AgentsSection({
     });
   };
 
-  const renderAgent = (provider: ServerProvider) => {
-    const terminalOpen = terminalSession?.providerInstanceId === provider.instanceId;
-    const ready = getOnboardingProviderState(provider) === "ready";
-    if (ready) {
-      return <AgentCard key={provider.instanceId} driver={provider.driver} provider={provider} />;
-    }
-    if (provider.driver === "codex" && serverConfig !== null) {
-      return (
-        <OnboardingCodexSetup
-          key={provider.instanceId}
-          environmentId={environmentId}
-          provider={provider}
-          serverConfig={serverConfig}
-          terminalOpen={terminalOpen}
-          onOpenTerminal={() => openTerminal(provider)}
-        />
-      );
-    }
-    if (isInstallableDriver(provider.driver)) {
-      return (
-        <AgentCard
-          key={provider.instanceId}
-          driver={provider.driver}
-          provider={provider}
-          terminalOpen={terminalOpen}
-          terminalAvailable={serverConfig !== null && canOperateTerminal}
-          onOpenTerminal={() => openTerminal(provider)}
-        />
-      );
+  const turnOn = async (provider: ServerProvider) => {
+    if (serverConfig === null) return;
+    const instance = serverConfig.settings.providerInstances[provider.instanceId] ?? {
+      driver: provider.driver,
+    };
+    const result = await persistProviderInstance({
+      operation: "upsert",
+      instanceId: provider.instanceId,
+      instance: { ...instance, enabled: true },
+    });
+    if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+      toastManager.add({ type: "error", title: `Could not turn on ${agentName(provider)}` });
+      return;
     }
-    return (
-      <AgentCard
-        key={provider.instanceId}
-        driver={provider.driver}
-        provider={provider}
-        settingsLink={{ environmentId, instanceId: provider.instanceId }}
-      />
-    );
+    void refreshProviders({ environmentId, input: {} });
   };
 
-  // Same tile for every agent so the list stays in neutral A to Z order.
-  const renderTile = (provider: ServerProvider) => {
+  // One action per agent, the same in the list and in the grid.
+  const actionFor = (provider: ServerProvider) => {
     const state = getOnboardingProviderState(provider);
+    if (state === "disabled") {
+      return (
+        <Button
+          size="xs"
+          variant="outline"
+          disabled={!canManageProviders || serverConfig === null}
+          onClick={() => void turnOn(provider)}
+        >
+          Turn on
+        </Button>
+      );
+    }
     if (provider.driver === "codex" && serverConfig !== null) {
       const open = codexSetupId === provider.instanceId;
       return (
-        <AgentCard
-          key={provider.instanceId}
-          driver={provider.driver}
-          provider={provider}
-          compact
-          action={
-            <Button
-              size="xs"
-              variant="outline"
-              aria-expanded={open}
-              onClick={() => setCodexSetupId(open ? null : provider.instanceId)}
-            >
-              Set up
-            </Button>
-          }
-        />
+        <Button
+          size="xs"
+          variant="outline"
+          aria-expanded={open}
+          onClick={() => setCodexSetupId(open ? null : provider.instanceId)}
+        >
+          Set up
+        </Button>
       );
     }
     if (isInstallableDriver(provider.driver) && (state === "install" || state === "signIn")) {
       return (
-        <AgentCard
-          key={provider.instanceId}
-          driver={provider.driver}
+        <TerminalAction
           provider={provider}
-          compact
-          terminalOpen={terminalSession?.providerInstanceId === provider.instanceId}
-          terminalAvailable={serverConfig !== null && canOperateTerminal}
-          onOpenTerminal={() => openTerminal(provider)}
+          disabled={
+            terminalSession?.providerInstanceId === provider.instanceId ||
+            serverConfig === null ||
+            !canOperateTerminal
+          }
+          onClick={() => openTerminal(provider)}
         />
       );
     }
     return (
-      <AgentCard
-        key={provider.instanceId}
-        driver={provider.driver}
-        provider={provider}
-        compact
-        settingsLink={{ environmentId, instanceId: provider.instanceId }}
-      />
+      <Button
+        size="xs"
+        variant="outline"
+        render={
+          <Link
+            to="/settings/providers"
+            search={{ environmentId, instanceId: provider.instanceId }}
+          />
+        }
+      >
+        {state === "signIn" ? "Sign in" : state === "attention" ? "Details" : "Set up"}
+      </Button>
     );
   };
-  const codexSetupProvider =
-    available.find((provider) => provider.instanceId === codexSetupId) ?? null;
 
   return (
     <WelcomeSection
@@ -467,7 +468,11 @@ function AgentsSection({
       }
     >
       {found.length > 0 ? (
-        <div className="space-y-1.5">{found.map((provider) => renderAgent(provider))}</div>
+        <div className="space-y-1.5">
+          {found.map((provider) => (
+            <AgentCard key={provider.instanceId} provider={provider} action={actionFor(provider)} />
+          ))}
+        </div>
       ) : null}
       {!canOperateTerminal ? (
         <p className="mt-2 text-sm text-muted-foreground">
@@ -484,38 +489,57 @@ function AgentsSection({
             {found.length > 0 ? "Add more agents" : "Set up an agent"}
           </span>
           <AgentLogoStack providers={available} />
-          <span className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
-            <ACPRegistryIcon className="size-3.5" />
-            ACP Registry
-          </span>
+          {acpAllowed ? (
+            <span className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
+              <ACPRegistryIcon className="size-3.5" />
+              ACP Registry
+            </span>
+          ) : null}
           <ChevronDownIcon className="ml-auto size-4 text-muted-foreground group-data-panel-open:rotate-180" />
         </CollapsibleTrigger>
         <CollapsiblePanel>
           <div className="space-y-1.5 pt-1">
             <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-2">
-              {available.map(renderTile)}
+              {available.map((provider) => (
+                <AgentCard
+                  key={provider.instanceId}
+                  provider={provider}
+                  compact
+                  action={actionFor(provider)}
+                />
+              ))}
             </div>
-            {codexSetupProvider !== null && serverConfig !== null ? (
-              <OnboardingCodexSetup
-                environmentId={environmentId}
-                provider={codexSetupProvider}
-                serverConfig={serverConfig}
-                terminalOpen={terminalSession?.providerInstanceId === codexSetupProvider.instanceId}
-                onOpenTerminal={() => openTerminal(codexSetupProvider)}
-              />
+            {acpAllowed ? (
+              <div className="flex items-center justify-between gap-3 rounded-lg border border-dashed border-border px-4 py-3">
+                <span className="inline-flex items-center gap-2 text-sm text-muted-foreground">
+                  <ACPRegistryIcon className="size-4" />
+                  More agents in the ACP Registry
+                </span>
+                <Button
+                  size="xs"
+                  variant="outline"
+                  disabled={!canManageProviders}
+                  onClick={() => setAddingProvider(true)}
+                >
+                  Browse
+                </Button>
+              </div>
             ) : null}
-            <div className="flex items-center justify-between gap-3 rounded-lg border border-dashed border-border px-4 py-3">
-              <span className="inline-flex items-center gap-2 text-sm text-muted-foreground">
-                <ACPRegistryIcon className="size-4" />
-                More agents in the ACP Registry
-              </span>
-              <Button size="xs" variant="outline" onClick={() => setAddingProvider(true)}>
-                Browse
-              </Button>
-            </div>
           </div>
         </CollapsiblePanel>
       </Collapsible>
+      {codexSetupProvider !== null && serverConfig !== null ? (
+        <div className="mt-2">
+          <OnboardingCodexSetup
+            environmentId={environmentId}
+            provider={codexSetupProvider}
+            serverConfig={serverConfig}
+            terminalOpen={terminalSession?.providerInstanceId === codexSetupProvider.instanceId}
+            onOpenTerminal={() => openTerminal(codexSetupProvider)}
+          />
+        </div>
+      ) : null}
+      <CliPathSetup />
       {terminalSession !== null ? (
         <AgentInstallTerminal
           key={`${terminalSession.environmentId}:${terminalSession.providerInstanceId}:${terminalSession.driver}`}
@@ -531,6 +555,7 @@ function AgentsSection({
           open
           environmentId={environmentId}
           environmentLabel={label}
+          showMoreProviders
           onOpenChange={setAddingProvider}
           onCreated={() => void refreshProviders({ environmentId, input: {} })}
         />
@@ -572,8 +597,15 @@ function ProjectsSection({
   readonly isImporting: boolean;
 }) {
   const [reviewing, setReviewing] = useState(false);
-  const { candidates, recent, selected, selectedKeys, setSelectedKeys, visibleImportError } =
-    projectImport;
+  const {
+    canWrite,
+    candidates,
+    recent,
+    selected,
+    selectedKeys,
+    setSelectedKeys,
+    visibleImportError,
+  } = projectImport;
   if (scan === undefined) return null;
   if (scan.isPending && scan.data === null) {
     return (
@@ -599,7 +631,15 @@ function ProjectsSection({
       </WelcomeSection>
     );
   }
-  if (candidates.length === 0) return null;
+  if (candidates.length === 0) {
+    return scan.data?.truncated ? (
+      <WelcomeSection title="Projects">
+        <p className="text-xs text-muted-foreground" role="status">
+          {SCAN_LIMIT_MESSAGE}
+        </p>
+      </WelcomeSection>
+    ) : null;
+  }
 
   const allKeys = candidates.map((candidate) => candidate.key);
   const defaultKeys = recent.length > 0 ? recent.map((candidate) => candidate.key) : allKeys;
@@ -608,14 +648,14 @@ function ProjectsSection({
       <div className="flex items-center gap-3 rounded-lg border border-border bg-background px-4 py-3">
         <Checkbox
           aria-label="Bring in projects"
-          checked={selected.length > 0}
-          disabled={isImporting}
+          checked={canWrite && selected.length > 0}
+          disabled={isImporting || !canWrite}
           onCheckedChange={(checked) => setSelectedKeys(new Set(checked ? defaultKeys : []))}
         />
         <span className="min-w-0 flex-1 text-sm text-foreground">
-          {selected.length > 0
-            ? `Bring in ${selected.length} ${selected.length === 1 ? "project" : "projects"} and their chats`
-            : "Bring in projects and their chats"}
+          {canWrite && selected.length > 0
+            ? `Bring in ${selected.length} ${selected.length === 1 ? "project" : "projects"} and their threads`
+            : "Bring in projects and their threads"}
         </span>
         <Button
           variant="ghost-muted"
@@ -623,7 +663,7 @@ function ProjectsSection({
           aria-expanded={reviewing}
           onClick={() => setReviewing((open) => !open)}
         >
-          {reviewing ? "Hide" : `Review ${candidates.length}`}
+          {reviewing ? "Hide" : `Review all ${candidates.length}`}
           <ChevronDownIcon className={cn("size-3.5", reviewing && "rotate-180")} />
         </Button>
       </div>
@@ -775,18 +815,16 @@ function OnboardingCodexSetup({
   onOpenTerminal,
 }: {
   readonly environmentId: EnvironmentId;
-  readonly provider: ServerProvider | undefined;
+  readonly provider: ServerProvider;
   readonly serverConfig: ServerConfig;
   readonly terminalOpen: boolean;
   readonly onOpenTerminal: () => void;
 }) {
   const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
-  const update = useAtomCommand(serverEnvironment.updateSettings, "Codex setup settings");
-  const instanceId =
-    provider?.instanceId ?? defaultInstanceIdForDriver(ProviderDriverKind.make("codex"));
-  const settings = serverConfig.settings;
-  const instance = settings.providerInstances[instanceId] ?? {
-    driver: ProviderDriverKind.make("codex"),
+  const persistProviderInstance = usePersistEnvironmentProviderInstanceMutation(environmentId);
+  const instanceId = provider.instanceId;
+  const instance = serverConfig.settings.providerInstances[instanceId] ?? {
+    driver: provider.driver,
     config: {},
   };
   const mode = readCodexSetupMode(instance.config);
@@ -797,34 +835,29 @@ function OnboardingCodexSetup({
     "setupMode" in instance.config &&
     instance.config.setupMode === "existing";
   const changeMode = (setupMode: "managed" | "existing") => {
-    void update({
-      environmentId,
-      input: {
-        patch: buildProviderInstanceUpdatePatch({
-          settings,
-          instanceId,
-          instance: {
-            ...instance,
-            enabled: true,
-            config: {
-              ...(instance.config !== null && typeof instance.config === "object"
-                ? instance.config
-                : {}),
-              enabled: true,
-              setupMode,
-            },
-          },
-        }),
-      },
+    const config =
+      instance.config !== null && typeof instance.config === "object" ? instance.config : {};
+    // One-instance upsert keeps a provider another client added in the meantime.
+    void persistProviderInstance({
+      operation: "upsert",
+      instanceId,
+      instance: { ...instance, enabled: true, config: { ...config, enabled: true, setupMode } },
+    }).then((result) => {
+      if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+        toastManager.add({ type: "error", title: "Could not save Codex setup" });
+      }
     });
   };
   return existingChosen ? (
     <AgentCard
-      driver={ProviderDriverKind.make("codex")}
       provider={provider}
-      terminalOpen={terminalOpen}
-      terminalAvailable={canOperateTerminal}
-      onOpenTerminal={onOpenTerminal}
+      action={
+        <TerminalAction
+          provider={provider}
+          disabled={terminalOpen || !canOperateTerminal}
+          onClick={onOpenTerminal}
+        />
+      }
     />
   ) : (
     <CodexSetupSection
@@ -833,50 +866,49 @@ function OnboardingCodexSetup({
       instanceId={instanceId}
       provider={provider}
       mode={mode}
-      enabled={provider?.enabled ?? true}
+      enabled={provider.enabled}
       onModeChange={changeMode}
     />
   );
 }
 
+function TerminalAction({
+  provider,
+  disabled,
+  onClick,
+}: {
+  readonly provider: ServerProvider;
+  readonly disabled: boolean;
+  readonly onClick: () => void;
+}) {
+  return (
+    <Button size="xs" variant="outline" disabled={disabled} onClick={onClick}>
+      <TerminalIcon className="size-3.5" />
+      {getOnboardingProviderState(provider) === "signIn" ? "Sign in" : "Install"}
+    </Button>
+  );
+}
+
 function AgentCard({
-  driver,
   provider,
-  terminalOpen = false,
-  terminalAvailable = false,
-  onOpenTerminal,
-  settingsLink,
-  compact = false,
   action,
+  compact = false,
 }: {
-  readonly driver: ProviderDriverKind;
-  readonly provider: ServerProvider | undefined;
-  readonly terminalOpen?: boolean;
-  readonly terminalAvailable?: boolean;
-  readonly onOpenTerminal?: () => void;
-  // Agents without a one-command install are set up on their Settings page instead.
-  readonly settingsLink?: {
-    readonly environmentId: EnvironmentId;
-    readonly instanceId: ProviderInstanceId;
-  };
+  readonly provider: ServerProvider;
+  readonly action?: ReactNode;
   // A tile for the "Add more agents" grid: the button carries the state, so no detail line.
   readonly compact?: boolean;
-  readonly action?: ReactNode;
 }) {
-  const displayName =
-    provider?.displayName ||
-    (driver === "claudeAgent" ? "Claude Code" : (providerClients.get(driver)?.label ?? driver));
-  const summary = getProviderSummary(provider);
-  const providerState = getOnboardingProviderState(provider);
-  const settingsAction =
-    providerState === "signIn"
-      ? "Sign in"
-      : providerState === "disabled"
-        ? "Turn on"
-        : providerState === "attention"
-          ? "Details"
-          : "Set up";
-
+  const state = getOnboardingProviderState(provider);
+  const name = agentName(provider);
+  const detail =
+    compact || state === "ready" || state === "checking"
+      ? null
+      : state === "install"
+        ? "Not installed"
+        : state === "disabled"
+          ? "Off"
+          : getProviderSummary(provider).headline;
   return (
     <div
       className={cn(
@@ -884,45 +916,29 @@ function AgentCard({
         compact ? "px-3 py-2.5" : "px-4 py-4",
       )}
     >
-      <ProviderInstanceIcon driverKind={driver} displayName={displayName} iconClassName="size-5" />
+      <ProviderInstanceIcon
+        driverKind={provider.driver}
+        displayName={name}
+        iconClassName="size-5"
+      />
       <div className="min-w-0 flex-1">
-        <span className="block text-sm font-medium text-foreground">{displayName}</span>
-        {providerState === "ready" || compact ? null : (
-          <p className="mt-0.5 text-xs leading-relaxed break-words whitespace-pre-wrap text-muted-foreground">
-            {providerState === "install" ? "Not installed" : summary.headline}
+        <span className="block truncate text-sm font-medium text-foreground">{name}</span>
+        {detail ? (
+          <p className="mt-0.5 text-xs leading-relaxed break-words text-muted-foreground">
+            {detail}
           </p>
-        )}
+        ) : null}
       </div>
       <div className="shrink-0">
-        {providerState === "ready" ? (
+        {state === "ready" ? (
           <span className="inline-flex items-center gap-1.5 text-xs font-medium text-success-foreground">
             <CheckIcon className="size-3.5" />
             Ready
           </span>
-        ) : providerState === "checking" ? (
-          <span className="text-xs text-muted-foreground">Checking...</span>
-        ) : action ? (
-          action
-        ) : settingsLink ? (
-          <Button
-            size="xs"
-            variant="outline"
-            render={<Link to="/settings/providers" search={settingsLink} />}
-          >
-            {settingsAction}
-          </Button>
-        ) : providerState === "disabled" || providerState === "attention" ? (
-          <span className="text-xs text-muted-foreground">{summary.headline}</span>
+        ) : state === "checking" ? (
+          <span className="text-xs text-muted-foreground">Checking…</span>
         ) : (
-          <Button
-            size="xs"
-            variant={compact ? "outline" : "ghost"}
-            onClick={onOpenTerminal}
-            disabled={terminalOpen || !terminalAvailable}
-          >
-            <TerminalIcon className="size-3.5" />
-            {providerState === "signIn" ? "Sign in" : "Install"}
-          </Button>
+          action
         )}
       </div>
     </div>
@@ -1354,6 +1370,7 @@ function useProjectImport({
   };
 
   return {
+    canWrite: scans.every((scan) => writableEnvironments.has(scan.environmentId)),
     candidates,
     recent,
     selected,
diff --git a/apps/web/src/components/settings/AddProviderInstanceDialog.tsx b/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
index 9b1829879405f..6a0cb5201cda9 100644
--- a/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
+++ b/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
@@ -141,6 +141,8 @@ interface AddProviderInstanceDialogProps {
   readonly environmentLabel: string;
   readonly onOpenChange: (open: boolean) => void;
   readonly onCreated?: (instanceId: ProviderInstanceId) => void;
+  /** Opens with "Show more" expanded, so the ACP Registry search is in view. */
+  readonly showMoreProviders?: boolean;
 }
 
 export function AddProviderInstanceDialog({
@@ -149,6 +151,7 @@ export function AddProviderInstanceDialog({
   environmentLabel,
   onOpenChange,
   onCreated,
+  showMoreProviders: initialShowMoreProviders = false,
 }: AddProviderInstanceDialogProps) {
   const settings = useEnvironmentSettings(environmentId);
   const secretSources = useSecretSources(environmentId);
@@ -179,7 +182,7 @@ export function AddProviderInstanceDialog({
     ReadonlyArray<ProviderInstanceEnvironmentVariable>
   >([]);
   const [isManualAcpConfiguration, setIsManualAcpConfiguration] = useState(false);
-  const [showMoreProviders, setShowMoreProviders] = useState(false);
+  const [showMoreProviders, setShowMoreProviders] = useState(initialShowMoreProviders);
   const [configByDriver, setConfigByDriver] = useState<Record<string, Record<string, unknown>>>({});
   const [hasAttemptedSubmit, setHasAttemptedSubmit] = useState(false);
   const [isSaving, setIsSaving] = useState(false);
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 17b5349e02390..9cceaa019dd1a 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -72,7 +72,11 @@ import {
 import { useTextGenerationTargets } from "../../textGenerators";
 import { ensureLocalApi, readLocalApi } from "../../localApi";
 import { isMacPlatform } from "../../lib/utils";
-import { useEnvironmentProviders, useEnvironments } from "../../state/environments";
+import {
+  useEnvironmentProviders,
+  useEnvironments,
+  usePrimaryEnvironmentId,
+} from "../../state/environments";
 import { EMPTY_SERVER_PROVIDERS } from "../../state/server";
 import { Button } from "../ui/button";
 import { DraftInput } from "../ui/draft-input";
@@ -2050,6 +2054,8 @@ export function MaintenanceSettingsPanel() {
 
 export function AboutSettingsPanel() {
   const primaryPolicy = usePrimaryManagedPolicy();
+  // The Welcome page sets up this computer, so it needs one.
+  const primaryEnvironmentId = usePrimaryEnvironmentId();
   const telemetryOff = managedTelemetryOffMessage(primaryPolicy);
   return (
     <SettingsPageContainer>
@@ -2085,15 +2091,17 @@ export function AboutSettingsPanel() {
           </>
         )}
         <MobileAppSettingsRow />
-        <SettingsRow
-          {...searchableSetting("welcome-page")}
-          description="See your agents, bring in projects, and set up your phone."
-          control={
-            <Button size="sm" variant="outline" render={<Link to="/welcome" />}>
-              Open
-            </Button>
-          }
-        />
+        {primaryEnvironmentId === null ? null : (
+          <SettingsRow
+            {...searchableSetting("welcome-page")}
+            description="See your agents, bring in projects, and set up your phone."
+            control={
+              <Button size="sm" variant="outline" render={<Link to="/welcome" />}>
+                Open
+              </Button>
+            }
+          />
+        )}
       </SettingsSection>
 
       <SettingsSection id="legal" title="Legal">
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index 400ef6ae54783..c00baade5f323 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -860,6 +860,8 @@ export const SETTINGS_SEARCH_ITEMS = [
     id: "welcome-page",
     title: "Welcome page",
     to: "/settings/about",
+    localEnvironmentOnly: true,
+    providerSettingsOnly: true,
     searchTerms: ["onboarding setup first run getting started agents import projects"],
   },
   {
diff --git a/apps/web/src/onboarding/providerReadiness.logic.test.ts b/apps/web/src/onboarding/providerReadiness.logic.test.ts
index 747b377c30228..1113768750588 100644
--- a/apps/web/src/onboarding/providerReadiness.logic.test.ts
+++ b/apps/web/src/onboarding/providerReadiness.logic.test.ts
@@ -9,7 +9,6 @@ import { describe, expect, it } from "vite-plus/test";
 import {
   getOnboardingProviderState,
   resolveOnboardingProviderLoginCommand,
-  selectOnboardingProvidersByDriver,
 } from "./providerReadiness.logic";
 
 const readyCodex: ServerProvider = {
@@ -73,49 +72,6 @@ describe("getOnboardingProviderState", () => {
   });
 });
 
-describe("selectOnboardingProvidersByDriver", () => {
-  it("prefers a ready instance with unknown authentication to an unauthenticated instance", () => {
-    const signedOutCodex: ServerProvider = {
-      ...readyCodex,
-      instanceId: ProviderInstanceId.make("codex_work"),
-      status: "error",
-      auth: { status: "unauthenticated" },
-    };
-
-    expect(selectOnboardingProvidersByDriver([signedOutCodex, readyCodex]).get("codex")).toBe(
-      readyCodex,
-    );
-  });
-
-  it("prefers a provider with an actionable sign-in over a failed provider", () => {
-    const failedCodex: ServerProvider = { ...readyCodex, status: "error" };
-    const signedOutCodex: ServerProvider = {
-      ...readyCodex,
-      instanceId: ProviderInstanceId.make("codex_work"),
-      status: "error",
-      auth: { status: "unauthenticated" },
-    };
-
-    expect(selectOnboardingProvidersByDriver([failedCodex, signedOutCodex]).get("codex")).toBe(
-      signedOutCodex,
-    );
-  });
-
-  it("prefers installed providers over missing or disabled instances", () => {
-    const disabledCodex: ServerProvider = { ...readyCodex, enabled: false };
-    const missingCodex: ServerProvider = {
-      ...readyCodex,
-      instanceId: ProviderInstanceId.make("codex_work"),
-      installed: false,
-      status: "error",
-    };
-
-    expect(
-      selectOnboardingProvidersByDriver([disabledCodex, missingCodex, readyCodex]).get("codex"),
-    ).toBe(readyCodex);
-  });
-});
-
 describe("resolveOnboardingProviderLoginCommand", () => {
   it("uses the selected Codex account binary", () => {
     const provider = { ...readyCodex, instanceId: ProviderInstanceId.make("codex_work") };
diff --git a/apps/web/src/onboarding/providerReadiness.logic.ts b/apps/web/src/onboarding/providerReadiness.logic.ts
index 6fb427100bdf7..43b0102d8816f 100644
--- a/apps/web/src/onboarding/providerReadiness.logic.ts
+++ b/apps/web/src/onboarding/providerReadiness.logic.ts
@@ -44,34 +44,6 @@ export function getOnboardingProviderState(provider: ServerProvider | undefined)
   return "attention";
 }
 
-const PROVIDER_STATE_PRIORITY = {
-  checking: 0,
-  disabled: 1,
-  install: 2,
-  attention: 3,
-  signIn: 4,
-  ready: 5,
-} as const;
-
-export function selectOnboardingProvidersByDriver(
-  providers: ReadonlyArray<ServerProvider> | null | undefined,
-) {
-  const providersByDriver = new Map<string, ServerProvider>();
-
-  for (const provider of providers ?? []) {
-    const existing = providersByDriver.get(provider.driver);
-    if (
-      existing === undefined ||
-      PROVIDER_STATE_PRIORITY[getOnboardingProviderState(provider)] >
-        PROVIDER_STATE_PRIORITY[getOnboardingProviderState(existing)]
-    ) {
-      providersByDriver.set(provider.driver, provider);
-    }
-  }
-
-  return providersByDriver;
-}
-
 // These need no Node/npm and install where provider maintenance recognizes native binaries.
 const NATIVE_INSTALL_COMMANDS = {
   claudeAgent: {
diff --git a/apps/web/src/onboarding/welcomeAgents.logic.test.ts b/apps/web/src/onboarding/welcomeAgents.logic.test.ts
index f07c619cae06b..e599b451c445e 100644
--- a/apps/web/src/onboarding/welcomeAgents.logic.test.ts
+++ b/apps/web/src/onboarding/welcomeAgents.logic.test.ts
@@ -23,6 +23,7 @@ function provider(name: string, overrides: Partial<ServerProvider> = {}): Server
 
 const nameOf = (entry: ServerProvider) => entry.displayName ?? entry.driver;
 const names = (entries: ReadonlyArray<ServerProvider>) => entries.map(nameOf);
+const allowAll = () => true;
 
 describe("groupWelcomeAgents", () => {
   it("lists agents on the computer by state, then name, and everything else by name", () => {
@@ -36,17 +37,31 @@ describe("groupWelcomeAgents", () => {
         provider("Cursor", { installed: false, status: "warning", auth: { status: "unknown" } }),
       ],
       nameOf,
+      allowAll,
     );
 
     expect(names(groups.found)).toEqual(["Claude", "Codex", "Zeta"]);
-    expect(names(groups.available)).toEqual(["Grok", "Pi"]);
-    // Cursor is still being checked, so it is in neither group yet.
+    // Cursor is still being checked; it stays listed instead of disappearing.
+    expect(names(groups.available)).toEqual(["Cursor", "Grok", "Pi"]);
     expect(groups.checking).toBe(true);
+    expect(groups.readyCount).toBe(2);
+  });
+
+  it("leaves out agents the computer's policy does not allow, ready or not", () => {
+    const groups = groupWelcomeAgents(
+      [provider("Codex"), provider("Blocked")],
+      nameOf,
+      (entry) => entry.driver !== "blocked",
+    );
+
+    expect(names(groups.found)).toEqual(["Codex"]);
+    expect(groups.readyCount).toBe(1);
   });
 
   it("reports checking before the computer has sent its providers", () => {
-    expect(groupWelcomeAgents(undefined, nameOf)).toEqual({
+    expect(groupWelcomeAgents(undefined, nameOf, allowAll)).toEqual({
       checking: true,
+      readyCount: 0,
       found: [],
       available: [],
     });
diff --git a/apps/web/src/onboarding/welcomeAgents.logic.ts b/apps/web/src/onboarding/welcomeAgents.logic.ts
index 5bea1581f52b3..2b7a6943b731a 100644
--- a/apps/web/src/onboarding/welcomeAgents.logic.ts
+++ b/apps/web/src/onboarding/welcomeAgents.logic.ts
@@ -9,20 +9,25 @@ type FoundState = keyof typeof FOUND_ORDER;
 const isFoundState = (state: string): state is FoundState => state in FOUND_ORDER;
 
 /**
- * Splits a computer's providers into agents already on it and agents the user can add.
- * Order inside each group is by state, then by the name the user sees.
+ * Splits a computer's allowed providers into agents already on it and agents the user can add.
+ * Order inside each group is by state, then by the name the user sees. Agents still being
+ * checked stay visible with the ones to add, so a slow check never hides an agent.
  */
 export function groupWelcomeAgents(
   providers: ReadonlyArray<ServerProvider> | null | undefined,
   nameOf: (provider: ServerProvider) => string,
+  isAllowed: (provider: ServerProvider) => boolean,
 ) {
   const found: ServerProvider[] = [];
   const available: ServerProvider[] = [];
   let checking = providers == null;
+  let readyCount = 0;
   for (const provider of providers ?? []) {
+    if (!isAllowed(provider)) continue;
     const state = getOnboardingProviderState(provider);
+    if (state === "ready") readyCount += 1;
     if (state === "checking") checking = true;
-    else if (isFoundState(state)) found.push(provider);
+    if (isFoundState(state)) found.push(provider);
     else available.push(provider);
   }
   const byName = (a: ServerProvider, b: ServerProvider) => nameOf(a).localeCompare(nameOf(b));
@@ -32,5 +37,5 @@ export function groupWelcomeAgents(
   };
   found.sort((a, b) => foundRank(a) - foundRank(b) || byName(a, b));
   available.sort(byName);
-  return { checking, found, available };
+  return { checking, readyCount, found, available };
 }
diff --git a/apps/web/src/routes/welcome.tsx b/apps/web/src/routes/welcome.tsx
index e01a918f4f901..37f31ec11075d 100644
--- a/apps/web/src/routes/welcome.tsx
+++ b/apps/web/src/routes/welcome.tsx
@@ -7,7 +7,7 @@ import * as Option from "effect/Option";
 import { NoProjectsHero } from "../components/NoProjectsHero";
 import { WelcomePage } from "../components/onboarding/WelcomePage";
 import { useNewThreadHandler } from "../hooks/useHandleNewThread";
-import { usePrimaryEnvironmentId } from "../state/environments";
+import { useEnvironments, usePrimaryEnvironmentId } from "../state/environments";
 
 const decodeEnvironmentId = Schema.decodeOption(EnvironmentId);
 
@@ -29,7 +29,13 @@ function WelcomeRouteView() {
     ? Option.getOrUndefined(decodeEnvironmentId(hash.slice("agents:".length)))
     : undefined;
   const primaryEnvironmentId = usePrimaryEnvironmentId();
-  const environmentId = resumeEnvironmentId ?? primaryEnvironmentId;
+  const { environments, isReady } = useEnvironments();
+  // Trust the id only once the catalog has it; an unknown computer falls back to this one.
+  const resumeKnown =
+    resumeEnvironmentId !== undefined &&
+    (!isReady ||
+      environments.some((environment) => environment.environmentId === resumeEnvironmentId));
+  const environmentId = (resumeKnown ? resumeEnvironmentId : undefined) ?? primaryEnvironmentId;
   // The root can remount this pending outlet after navigation; do not reopen setup.
   const isWelcomeRoute = useLocation({ select: (location) => location.pathname === "/welcome" });
   const [dismissed, setDismissed] = useState(false);
diff --git a/docs/user/install.md b/docs/user/install.md
index 48d96a4fef611..7b28781e69612 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -134,7 +134,7 @@ on first launch; after an update, or any time, choose **Install** next to
 **t3 command** in **Settings → About**. On macOS and Linux it adds a `t3` link
 in `~/.local/bin` (or `~/bin`); on Windows it adds the app's command folder to
 your `PATH`. Open a new terminal afterwards. If the folder is not on your
-`PATH`, **Add to PATH** in the welcome setup or **Settings → About** adds one
+`PATH`, **Add to PATH** on the Welcome page or in **Settings → About** adds one
 line to your shell's startup file. **Remove** takes it off, and the app does not
 add it again. If you already have another `t3`, it stays as it is.
 
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 23b757b907746..82a3750c4c255 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -22,28 +22,36 @@ unreadable settings with defaults.
 
 ## Agents
 
-T3 Code lists the agents it found on the computer first, ready ones on top. If
-Claude Code or Codex needs a sign-in or install, select its action to open a
-terminal with the correct command ready to run. Install uses the vendor's own
-installer, which keeps **Update now** working in Settings. Codex can also sign in
-with your ChatGPT account.
-
-**Add more agents** lists every other agent T3 Code supports. Agents without a
-one-command install open their page in **Settings → Providers**. **Browse**
-opens the ACP Registry for more agents. When no agent is found, this list opens
-by itself.
+T3 Code lists the agents it found on the computer first, ready ones on top.
+**Add more agents** lists every other agent T3 Code supports, A to Z, and opens by
+itself when no agent is found:
+
+- **Turn on** enables an agent that is off. T3 Code then checks whether it is
+  installed and signed in.
+- For Claude Code, **Install** or **Sign in** opens a terminal with the correct
+  command ready to run. Install uses the vendor's own installer, which keeps
+  **Update now** working in Settings.
+- For Codex, **Set up** offers sign-in with your ChatGPT account or your own
+  Codex CLI.
+- Other agents open their page in **Settings → Providers**.
+- **Browse** opens the ACP Registry for more agents.
+
+On the desktop app, when the folder of the `t3` command is not on your `PATH`,
+**Add to PATH** adds one line to your shell's startup file.
 
 The setup terminal uses the home directory and environment configured for the
 provider instance. Sensitive values remain redacted in Settings and
 terminal metadata while the terminal process can use them.
 
-**Start** waits for one ready agent. Select **Skip for now** to start without one.
+**Start** waits for one ready agent. Select **Start without an agent** to finish
+without one.
 
 ## Phone
 
-Select **Set up** to show QR codes for the App Store and Google Play. Then sign
-in to T3 Connect with the same account in the app, or pair the app from
-**Settings → Sharing & access** on builds without T3 Connect.
+Select **Set up** to show QR codes for the App Store and Google Play. Then select
+**Sign in to T3 Connect** and allow this computer when T3 Code asks, so the app can
+reach it. Sign in to the app with the same account. On builds without T3 Connect,
+pair the app from **Settings → Sharing & access**.
 
 ## Projects
 

From 0f0f9d4bd5cdebfe86fc657b3f990472440901d8 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 19:12:56 -0800
Subject: [PATCH 04/22] fix(web): Welcome page shows real phone and agent
 states and lets the app quit

- Phone: the check shows only when this computer is shared with the signed-in
  account; otherwise "Set up T3 Connect" opens Sharing & access.
- Import: blocks in-app navigation until the landing, with a toast, and no
  longer blocks quitting the desktop app.
- Agents: state follows this computer's settings, so a project-only agent offers
  Turn on; an agent that failed to load links to Settings instead of Turn on.
- Codex: one setup card; "Use existing CLI" opens the terminal and ChatGPT stays
  available until Codex is ready.
- Turning on Claude Code, Codex or Pi rescans projects. Read-only connections
  cannot pick projects or change the Codex mode.
- Settings search lists the Welcome page only with a primary computer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       |  85 +++++++-
 .../src/components/onboarding/WelcomePage.tsx | 192 +++++++++++-------
 .../settings/settingsSearch.test.ts           |  19 ++
 .../src/components/settings/settingsSearch.ts |   6 +-
 .../useAvailableSettingsSearchItems.ts        |   1 +
 .../onboarding/welcomeAgents.logic.test.ts    |  55 ++++-
 .../web/src/onboarding/welcomeAgents.logic.ts |  46 ++++-
 docs/user/welcome-page.md                     |  26 ++-
 8 files changed, 328 insertions(+), 102 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index 6e188150f0cf0..370bb32c692c1 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -9,6 +9,7 @@ import {
   type AgentSessionProjectCandidate,
   type AuthEnvironmentScope,
   type AuthSessionState,
+  type EnvironmentCloudLinkStateResult,
   type ServerProvider,
 } from "@t3tools/contracts";
 import { AsyncResult, Atom } from "effect/reactivity";
@@ -37,6 +38,9 @@ const state = vi.hoisted(() => ({
   scan: vi.fn(),
   refreshScan: vi.fn(),
   waitForProject: vi.fn(),
+  cloud: false,
+  auth: { isLoaded: true, isSignedIn: false, userId: null as string | null },
+  linkState: null as unknown,
 }));
 
 vi.mock(import("@t3tools/client-runtime/state/session"), async (original) => {
@@ -51,8 +55,25 @@ vi.mock(import("@t3tools/client-runtime/state/session"), async (original) => {
 });
 vi.mock(import("../../cloud/publicConfig"), async (original) => ({
   ...(await original()),
-  hasCloudPublicConfig: () => false,
+  hasCloudPublicConfig: () => state.cloud,
 }));
+vi.mock(import("@clerk/react"), async (original) => ({
+  ...(await original()),
+  useAuth: (() => state.auth) as never,
+}));
+vi.mock(import("../clerk/useT3ConnectAuthPrompt"), async (original) => ({
+  ...(await original()),
+  useT3ConnectAuthPrompt: (() => ({ openAuthPrompt: () => {} })) as never,
+}));
+vi.mock(import("../../cloud/cloudLinkState"), async (original) => {
+  const { useAtomValue } = await import("@effect/atom-react");
+  return {
+    ...(await original()),
+    useCloudLinkState: (() => ({
+      data: useAtomValue(state.linkState as Atom.Atom<EnvironmentCloudLinkStateResult | null>),
+    })) as never,
+  };
+});
 vi.mock(import("../../onboarding/firstRun"), async (original) => ({
   ...(await original()),
   completeOnboarding: state.completeOnboarding,
@@ -269,6 +290,9 @@ function setup() {
   state.scan.mockReset();
   state.refreshScan.mockReset();
   state.waitForProject.mockReset().mockImplementation(waitForRecordedProject);
+  state.cloud = false;
+  state.auth = { isLoaded: true, isSignedIn: false, userId: null };
+  state.linkState = Atom.make<EnvironmentCloudLinkStateResult | null>(null).pipe(Atom.keepAlive);
   return now;
 }
 
@@ -350,25 +374,76 @@ it("waits for a ready agent to start, and Start without an agent still finishes
   expect(state.createProject).toHaveBeenCalledTimes(2);
 });
 
-it("stays on the page while projects import, then lands as usual", async () => {
+it("blocks leaving the page until the imported projects have landed", async () => {
   using _now = setup();
   const creation = deferred<void>();
   state.createProject.mockImplementationOnce(async (input: CreateProjectInput) => {
     await creation.promise;
     return recordProject(input);
   });
+  const landing = deferred<void>();
+  state.waitForProject.mockImplementation(
+    async (ref: { environmentId: EnvironmentId; projectId: string }) => {
+      await landing.promise;
+      return waitForRecordedProject(ref);
+    },
+  );
   await using screen = await mountWelcome();
   await click("Add 2 projects and start");
 
   // A blocked navigation never settles, so it is not awaited.
-  await act(async () => {
-    void screen.router?.navigate({ to: "/settings" });
-  });
+  const leave = () =>
+    act(async () => {
+      void screen.router?.navigate({ to: "/settings" });
+    });
+  await leave();
   await act(async () => {
     creation.resolve();
     await creation.promise;
   });
+  await vi.waitFor(() => expect(state.waitForProject).toHaveBeenCalledOnce());
+  await leave();
+  expect(screen.router?.state.location.pathname).toBe("/");
+
+  await act(async () => {
+    landing.resolve();
+    await landing.promise;
+  });
   await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
   expect(screen.router?.state.location.pathname).toBe("/");
   expect(state.createProject).toHaveBeenCalledTimes(2);
 });
+
+it("starts without importing when this connection cannot import projects", async () => {
+  using _now = setup();
+  setGrant(primaryId, false);
+  await using _screen = await mountWelcome();
+  expect(pageText()).not.toContain("Review all");
+
+  await click("Start");
+  await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
+  expect(state.createProject).not.toHaveBeenCalled();
+});
+
+it("says the phone is set up only once this computer is shared with the signed-in account", async () => {
+  using _now = setup();
+  state.cloud = true;
+  state.auth = { isLoaded: true, isSignedIn: true, userId: "user_1" };
+  await using _screen = await mountWelcome();
+  await click("Set up");
+  // Signed in, but "Not now" on the share step left this computer unreachable.
+  expect(pageText()).toContain("Set up T3 Connect");
+
+  await act(async () =>
+    appAtomRegistry.set(state.linkState as Atom.Writable<EnvironmentCloudLinkStateResult | null>, {
+      linked: true,
+      cloudUserId: "user_1",
+      relayUrl: null,
+      relayIssuer: null,
+      managedTunnelActive: true,
+      publishAgentActivity: true,
+    }),
+  );
+  expect(pageText()).toContain("Your phone can reach this computer.");
+  expect(pageText()).not.toContain("Set up T3 Connect");
+});
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index e075217025854..0a548e3c42dac 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -36,6 +36,7 @@ import { TYPOGRAPHY_ADVANCED_STORAGE_KEY } from "../../appearanceFonts";
 import { isElectron } from "../../env";
 import { useLocalStorage } from "../../hooks/useLocalStorage";
 import { usePersistEnvironmentProviderInstanceMutation } from "../../hooks/useSettings";
+import { useCloudLinkState } from "../../cloud/cloudLinkState";
 import { hasCloudPublicConfig } from "../../cloud/publicConfig";
 import { PRIVACY_POLICY_URL } from "../../legalLinks";
 import { workspaceAreaProps } from "../../lib/workspaceFocus";
@@ -51,11 +52,10 @@ import {
   splitOnboardingProjectPath,
 } from "../../onboarding/projectImport.logic";
 import {
-  getOnboardingProviderState,
   resolveOnboardingProviderInstallCommand,
   resolveOnboardingProviderLoginCommand,
 } from "../../onboarding/providerReadiness.logic";
-import { groupWelcomeAgents } from "../../onboarding/welcomeAgents.logic";
+import { groupWelcomeAgents, welcomeAgentState } from "../../onboarding/welcomeAgents.logic";
 import { newProjectId, randomUUID } from "../../lib/utils";
 import { agentSessionImport } from "../../state/agentSessions";
 import { readProjects, waitForProject } from "../../state/entities";
@@ -98,8 +98,8 @@ const AGENT_ONBOARDING_THREAD_ID = ThreadId.make("onboarding-agent-setup");
 const SCAN_LIMIT_MESSAGE = "Scan limit reached. Some projects or conversations may be missing.";
 
 /**
- * First-run page for one computer: its agents, the projects found in Claude Code and Codex
- * history, and the phone app. Every part is optional except one ready agent to start chatting.
+ * First-run page for one computer: its agents, the projects found in agent history, and the
+ * phone app. Every part is optional except one ready agent to start chatting.
  */
 export function WelcomePage({
   environmentId,
@@ -205,13 +205,17 @@ export function WelcomePage({
               Setting up <span className="font-medium text-foreground">{label}</span>. You can
               change any of this later in Settings.
             </p>
-            <AgentsSection environmentId={environmentId} label={label} />
+            <AgentsSection
+              environmentId={environmentId}
+              label={label}
+              onImportSourceEnabled={() => scans[0]?.refresh()}
+            />
             <ProjectsSection
               scan={scans[0]}
               projectImport={projectImport}
               isImporting={isImporting}
             />
-            <PhoneSection />
+            <PhoneSection environmentId={environmentId} />
             <div className="mt-8 flex flex-wrap items-center justify-between gap-3 border-t border-border/70 pt-6">
               {agentReady ? (
                 <span />
@@ -312,20 +316,28 @@ function useWelcomeAgents(environmentId: EnvironmentId) {
   return {
     providers,
     serverConfig,
-    ...groupWelcomeAgents(providers, agentName, (provider) =>
+    ...groupWelcomeAgents(providers, serverConfig?.settings, agentName, (provider) =>
       isManagedDriverAllowed(managedPolicy, provider.driver),
     ),
   };
 }
 
+const isImportSource = Schema.is(AgentSessionSource);
+
+// The setup card opens below a long list, so bring it into view once.
+const revealOnMount = (node: HTMLElement | null) => node?.scrollIntoView({ block: "nearest" });
+
 const ACP_REGISTRY_DRIVER_KIND = ProviderDriverKind.make("acpRegistry");
 
 function AgentsSection({
   environmentId,
   label,
+  onImportSourceEnabled,
 }: {
   readonly environmentId: EnvironmentId;
   readonly label: string;
+  // The project scan only reads agents that are on, so turning one on can find more history.
+  readonly onImportSourceEnabled: () => void;
 }) {
   const { providers, serverConfig, checking, readyCount, found, available } =
     useWelcomeAgents(environmentId);
@@ -348,12 +360,16 @@ function AgentsSection({
   // With nothing on this computer yet, the list of agents to add is the main task.
   const showMore = moreOpen ?? found.length === 0;
   const acpAllowed = isManagedDriverAllowed(serverConfig?.managedPolicy, ACP_REGISTRY_DRIVER_KIND);
+  const stateOf = (provider: ServerProvider) => welcomeAgentState(provider, serverConfig?.settings);
+  const needsInstallOrSignIn = (provider: ServerProvider) => {
+    const state = stateOf(provider);
+    return isInstallableDriver(provider.driver) && (state === "install" || state === "signIn");
+  };
   // Codex setup stays mounted by instance while its status changes, so a sign-in that
   // starts after an install is not lost when the agent moves between groups.
   const codexSetupProvider =
     providers?.find(
-      (provider) =>
-        provider.instanceId === codexSetupId && getOnboardingProviderState(provider) !== "ready",
+      (provider) => provider.instanceId === codexSetupId && stateOf(provider) !== "ready",
     ) ?? null;
 
   const openTerminal = (provider: ServerProvider) => {
@@ -396,12 +412,13 @@ function AgentsSection({
       toastManager.add({ type: "error", title: `Could not turn on ${agentName(provider)}` });
       return;
     }
-    void refreshProviders({ environmentId, input: {} });
+    void refreshProviders({ environmentId, input: { instanceId: provider.instanceId } });
+    if (isImportSource(provider.driver)) onImportSourceEnabled();
   };
 
   // One action per agent, the same in the list and in the grid.
   const actionFor = (provider: ServerProvider) => {
-    const state = getOnboardingProviderState(provider);
+    const state = stateOf(provider);
     if (state === "disabled") {
       return (
         <Button
@@ -414,7 +431,7 @@ function AgentsSection({
         </Button>
       );
     }
-    if (provider.driver === "codex" && serverConfig !== null) {
+    if (provider.driver === "codex" && serverConfig !== null && needsInstallOrSignIn(provider)) {
       const open = codexSetupId === provider.instanceId;
       return (
         <Button
@@ -427,10 +444,10 @@ function AgentsSection({
         </Button>
       );
     }
-    if (isInstallableDriver(provider.driver) && (state === "install" || state === "signIn")) {
+    if (needsInstallOrSignIn(provider)) {
       return (
         <TerminalAction
-          provider={provider}
+          signIn={state === "signIn"}
           disabled={
             terminalSession?.providerInstanceId === provider.instanceId ||
             serverConfig === null ||
@@ -470,11 +487,16 @@ function AgentsSection({
       {found.length > 0 ? (
         <div className="space-y-1.5">
           {found.map((provider) => (
-            <AgentCard key={provider.instanceId} provider={provider} action={actionFor(provider)} />
+            <AgentCard
+              key={provider.instanceId}
+              provider={provider}
+              state={stateOf(provider)}
+              action={actionFor(provider)}
+            />
           ))}
         </div>
       ) : null}
-      {!canOperateTerminal ? (
+      {!canOperateTerminal && [...found, ...available].some(needsInstallOrSignIn) ? (
         <p className="mt-2 text-sm text-muted-foreground">
           This connection cannot control terminals.
         </p>
@@ -504,6 +526,7 @@ function AgentsSection({
                 <AgentCard
                   key={provider.instanceId}
                   provider={provider}
+                  state={stateOf(provider)}
                   compact
                   action={actionFor(provider)}
                 />
@@ -529,12 +552,11 @@ function AgentsSection({
         </CollapsiblePanel>
       </Collapsible>
       {codexSetupProvider !== null && serverConfig !== null ? (
-        <div className="mt-2">
+        <div key={codexSetupProvider.instanceId} ref={revealOnMount} className="mt-2">
           <OnboardingCodexSetup
             environmentId={environmentId}
             provider={codexSetupProvider}
             serverConfig={serverConfig}
-            terminalOpen={terminalSession?.providerInstanceId === codexSetupProvider.instanceId}
             onOpenTerminal={() => openTerminal(codexSetupProvider)}
           />
         </div>
@@ -611,7 +633,7 @@ function ProjectsSection({
     return (
       <WelcomeSection title="Projects">
         <p className="text-sm text-muted-foreground">
-          Looking for projects in your Claude Code and Codex history…
+          Looking for projects in your {IMPORT_SOURCES_LABEL} history…
         </p>
       </WelcomeSection>
     );
@@ -644,7 +666,7 @@ function ProjectsSection({
   const allKeys = candidates.map((candidate) => candidate.key);
   const defaultKeys = recent.length > 0 ? recent.map((candidate) => candidate.key) : allKeys;
   return (
-    <WelcomeSection title="Projects" status="From your Claude Code and Codex history">
+    <WelcomeSection title="Projects" status={`From your ${IMPORT_SOURCES_LABEL} history`}>
       <div className="flex items-center gap-3 rounded-lg border border-border bg-background px-4 py-3">
         <Checkbox
           aria-label="Bring in projects"
@@ -657,17 +679,19 @@ function ProjectsSection({
             ? `Bring in ${selected.length} ${selected.length === 1 ? "project" : "projects"} and their threads`
             : "Bring in projects and their threads"}
         </span>
-        <Button
-          variant="ghost-muted"
-          size="xs"
-          aria-expanded={reviewing}
-          onClick={() => setReviewing((open) => !open)}
-        >
-          {reviewing ? "Hide" : `Review all ${candidates.length}`}
-          <ChevronDownIcon className={cn("size-3.5", reviewing && "rotate-180")} />
-        </Button>
+        {canWrite ? (
+          <Button
+            variant="ghost-muted"
+            size="xs"
+            aria-expanded={reviewing}
+            onClick={() => setReviewing((open) => !open)}
+          >
+            {reviewing ? "Hide" : `Review all ${candidates.length}`}
+            <ChevronDownIcon className={cn("size-3.5", reviewing && "rotate-180")} />
+          </Button>
+        ) : null}
       </div>
-      {reviewing ? (
+      {reviewing && canWrite ? (
         <fieldset className="mt-2 min-w-0" disabled={isImporting}>
           <div className="flex items-center justify-between gap-3 px-1 text-xs text-muted-foreground">
             <span role="status">
@@ -715,7 +739,7 @@ function ProjectsSection({
   );
 }
 
-function PhoneSection() {
+function PhoneSection({ environmentId }: { readonly environmentId: EnvironmentId }) {
   const [open, setOpen] = useState(false);
   return (
     <WelcomeSection title="Phone" status="Optional">
@@ -754,7 +778,7 @@ function PhoneSection() {
             </div>
             <div className="flex flex-col justify-center gap-2 rounded-lg border border-border bg-background p-3.5">
               {hasCloudPublicConfig() ? (
-                <PhoneConnectLink />
+                <PhoneConnectLink environmentId={environmentId} />
               ) : (
                 <>
                   <span className="text-sm text-muted-foreground">
@@ -778,17 +802,43 @@ function PhoneSection() {
   );
 }
 
-function PhoneConnectLink() {
-  const { isLoaded, isSignedIn } = useAuth({ treatPendingAsSignedOut: false });
+function PhoneConnectLink({ environmentId }: { readonly environmentId: EnvironmentId }) {
+  const { isLoaded, isSignedIn, userId } = useAuth({ treatPendingAsSignedOut: false });
   const { openAuthPrompt } = useT3ConnectAuthPrompt();
-  if (isSignedIn) {
+  const link = useCloudLinkState(environmentId).data;
+  // The phone reaches this computer through its tunnel; older servers leave that flag out.
+  const shared =
+    link !== null &&
+    link.linked &&
+    link.linkRevoked !== true &&
+    link.cloudUserId === userId &&
+    link.managedTunnelActive !== false;
+  if (isSignedIn && shared) {
     return (
       <span className="inline-flex items-center gap-1.5 text-sm text-foreground">
-        <CheckIcon className="size-4 text-success-foreground" />
-        Signed in to T3 Connect. Use the same account in the app.
+        <CheckIcon className="size-4 shrink-0 text-success-foreground" />
+        Your phone can reach this computer. Sign in to the app with the same account.
       </span>
     );
   }
+  if (isSignedIn) {
+    // Signing in alone does not share this computer, for example after "Not now".
+    return (
+      <>
+        <span className="text-sm text-muted-foreground">
+          Signed in. Share this computer so the app can reach it.
+        </span>
+        <Button
+          variant="outline"
+          size="sm"
+          className="self-start"
+          render={<Link to="/settings/access" />}
+        >
+          Set up T3 Connect
+        </Button>
+      </>
+    );
+  }
   return (
     <>
       <span className="text-sm text-muted-foreground">
@@ -807,36 +857,32 @@ function PhoneConnectLink() {
   );
 }
 
+// The ChatGPT card and the CLI card stay one card, so either choice can be undone here.
 function OnboardingCodexSetup({
   environmentId,
   provider,
   serverConfig,
-  terminalOpen,
   onOpenTerminal,
 }: {
   readonly environmentId: EnvironmentId;
   readonly provider: ServerProvider;
   readonly serverConfig: ServerConfig;
-  readonly terminalOpen: boolean;
   readonly onOpenTerminal: () => void;
 }) {
-  const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
+  const canManageProviders = useEnvironmentScope(environmentId, AuthProvidersManageScope);
   const persistProviderInstance = usePersistEnvironmentProviderInstanceMutation(environmentId);
   const instanceId = provider.instanceId;
   const instance = serverConfig.settings.providerInstances[instanceId] ?? {
     driver: provider.driver,
     config: {},
   };
-  const mode = readCodexSetupMode(instance.config);
-  const existingChosen =
-    mode === "existing" &&
-    instance.config !== null &&
-    typeof instance.config === "object" &&
-    "setupMode" in instance.config &&
-    instance.config.setupMode === "existing";
+  const config =
+    instance.config !== null && typeof instance.config === "object" ? instance.config : {};
+  const mode = readCodexSetupMode(config);
   const changeMode = (setupMode: "managed" | "existing") => {
-    const config =
-      instance.config !== null && typeof instance.config === "object" ? instance.config : {};
+    // On the CLI card, "Use existing CLI" also opens a terminal to install or sign in.
+    if (setupMode === "existing" && mode === "existing") onOpenTerminal();
+    if (!readEnvironmentScope(environmentId, AuthProvidersManageScope)) return;
     // One-instance upsert keeps a provider another client added in the meantime.
     void persistProviderInstance({
       operation: "upsert",
@@ -848,18 +894,7 @@ function OnboardingCodexSetup({
       }
     });
   };
-  return existingChosen ? (
-    <AgentCard
-      provider={provider}
-      action={
-        <TerminalAction
-          provider={provider}
-          disabled={terminalOpen || !canOperateTerminal}
-          onClick={onOpenTerminal}
-        />
-      }
-    />
-  ) : (
+  return (
     <CodexSetupSection
       presentation="onboarding"
       environmentId={environmentId}
@@ -867,39 +902,41 @@ function OnboardingCodexSetup({
       provider={provider}
       mode={mode}
       enabled={provider.enabled}
+      readOnly={!canManageProviders}
       onModeChange={changeMode}
     />
   );
 }
 
 function TerminalAction({
-  provider,
+  signIn,
   disabled,
   onClick,
 }: {
-  readonly provider: ServerProvider;
+  readonly signIn: boolean;
   readonly disabled: boolean;
   readonly onClick: () => void;
 }) {
   return (
     <Button size="xs" variant="outline" disabled={disabled} onClick={onClick}>
       <TerminalIcon className="size-3.5" />
-      {getOnboardingProviderState(provider) === "signIn" ? "Sign in" : "Install"}
+      {signIn ? "Sign in" : "Install"}
     </Button>
   );
 }
 
 function AgentCard({
   provider,
+  state,
   action,
   compact = false,
 }: {
   readonly provider: ServerProvider;
+  readonly state: ReturnType<typeof welcomeAgentState>;
   readonly action?: ReactNode;
   // A tile for the "Add more agents" grid: the button carries the state, so no detail line.
   readonly compact?: boolean;
 }) {
-  const state = getOnboardingProviderState(provider);
   const name = agentName(provider);
   const detail =
     compact || state === "ready" || state === "checking"
@@ -908,7 +945,7 @@ function AgentCard({
         ? "Not installed"
         : state === "disabled"
           ? "Off"
-          : getProviderSummary(provider).headline;
+          : (provider.unavailableReason ?? getProviderSummary(provider).headline);
   return (
     <div
       className={cn(
@@ -1147,11 +1184,16 @@ function useProjectImport({
     new Map<string, { readonly projectId: ProjectId; readonly commandId: CommandId }>(),
   );
   const importGenerationRef = useRef(0);
-  const importLoopRef = useRef(false);
-  // Leaving mid-import would abandon the remaining projects and their retry state.
+  // True from the first project until the landing; leaving earlier drops the rest of the import.
+  const holdPageRef = useRef(false);
   useBlocker({
-    shouldBlockFn: () => importLoopRef.current,
-    enableBeforeUnload: () => importLoopRef.current,
+    shouldBlockFn: () => {
+      if (!holdPageRef.current) return false;
+      toastManager.add({ type: "info", title: "Importing projects", description: "One moment." });
+      return true;
+    },
+    // Electron cancels a quit silently when unload is blocked. A later visit resumes the import.
+    enableBeforeUnload: false,
   });
 
   // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- bumps the import generation on mount and unmount so in-flight imports drop stale results
@@ -1207,6 +1249,7 @@ function useProjectImport({
       return;
     }
     setIsImporting(true);
+    holdPageRef.current = true;
     const importGeneration = importGenerationRef.current;
     // waitForProject gives up after its timeout, so a project that never reaches the client
     // still finishes setup, just without landing in it.
@@ -1216,6 +1259,8 @@ function useProjectImport({
         () => undefined,
       )
       .then(async (landing) => {
+        // Release before onDone so its own navigation is not blocked.
+        holdPageRef.current = false;
         if (importGeneration !== importGenerationRef.current) return;
         const completed = await onDone(
           landing,
@@ -1345,9 +1390,9 @@ function useProjectImport({
       }
       return true;
     };
-    importLoopRef.current = true;
+    holdPageRef.current = true;
     const completed = await importEach().finally(() => {
-      importLoopRef.current = false;
+      holdPageRef.current = false;
     });
     if (!completed) return;
     for (const scan of scans) {
@@ -1583,6 +1628,9 @@ const IMPORT_SOURCE_NAMES: Record<AgentSessionSource, string> = {
   codex: "Codex",
   pi: "Pi",
 };
+const IMPORT_SOURCES_LABEL = new Intl.ListFormat("en", { type: "conjunction" }).format(
+  AgentSessionSource.literals.map((source) => IMPORT_SOURCE_NAMES[source]),
+);
 
 function ImportRowMeta({
   sources,
diff --git a/apps/web/src/components/settings/settingsSearch.test.ts b/apps/web/src/components/settings/settingsSearch.test.ts
index 6f62a0fa78693..c360265f81e31 100644
--- a/apps/web/src/components/settings/settingsSearch.test.ts
+++ b/apps/web/src/components/settings/settingsSearch.test.ts
@@ -168,6 +168,25 @@ describe("searchSettings", () => {
     );
   });
 
+  it("finds the Welcome page only where a primary computer can open it", () => {
+    const availability = {
+      hasCloudPublicConfig: true,
+      hasEnvironment: true,
+      hasProviderSettingsEnvironment: true,
+      canManageLocalBackend: false,
+      isWslSettingsRowVisible: false,
+      hasThreadAutoSettlement: false,
+    };
+    const ids = (hasPrimaryEnvironment: boolean) =>
+      searchSettings(
+        "welcome page",
+        filterAvailableSettingsSearchItems({ ...availability, hasPrimaryEnvironment }),
+      ).map((item) => item.id);
+    // Hosted web reaches remote computers but has no primary one to set up.
+    expect(ids(false)).not.toContain("welcome-page");
+    expect(ids(true)).toContain("welcome-page");
+  });
+
   it("finds keybinding commands by label, command id, and default key", () => {
     expect(searchSettings("toggle sidebar")[0]?.id).toBe("keybinding-sidebar.toggle");
     expect(searchSettings("sidebar.toggle")[0]?.id).toBe("keybinding-sidebar.toggle");
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index c00baade5f323..7e0c2a9cc73d6 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -65,6 +65,7 @@ export interface SettingsSearchItem {
   readonly providerSettingsOnly?: boolean;
   readonly localBackendManagementOnly?: boolean;
   readonly localEnvironmentOnly?: boolean;
+  readonly primaryEnvironmentOnly?: boolean;
   readonly wslAvailableOnly?: boolean;
   readonly managedTunnelOnly?: boolean;
   readonly peerLinksOnly?: boolean;
@@ -87,6 +88,7 @@ export interface SettingsSearchAvailability {
   readonly hasFastWorktreeCheckoutEnvironment?: boolean;
   /** An environment without a provider allow-list, which hides text generators. */
   readonly hasTextGeneratorsEnvironment?: boolean;
+  readonly hasPrimaryEnvironment?: boolean;
 }
 
 export const SETTINGS_SECTION_LABELS: Readonly<Record<SettingsPath, string>> = {
@@ -860,8 +862,7 @@ export const SETTINGS_SEARCH_ITEMS = [
     id: "welcome-page",
     title: "Welcome page",
     to: "/settings/about",
-    localEnvironmentOnly: true,
-    providerSettingsOnly: true,
+    primaryEnvironmentOnly: true,
     searchTerms: ["onboarding setup first run getting started agents import projects"],
   },
   {
@@ -1468,6 +1469,7 @@ export function filterAvailableSettingsSearchItems(
       (!item.providerSettingsOnly || availability.hasProviderSettingsEnvironment) &&
       (!item.localBackendManagementOnly || availability.canManageLocalBackend) &&
       (!item.localEnvironmentOnly || !availability.localEnvironmentDisabled) &&
+      (!item.primaryEnvironmentOnly || availability.hasPrimaryEnvironment === true) &&
       (!item.wslAvailableOnly || availability.isWslSettingsRowVisible) &&
       (!item.requiresThreadAutoSettlement || availability.hasThreadAutoSettlement) &&
       (!item.managedTunnelOnly || availability.managedTunnelActive === true) &&
diff --git a/apps/web/src/components/settings/useAvailableSettingsSearchItems.ts b/apps/web/src/components/settings/useAvailableSettingsSearchItems.ts
index 912e6c7c3f5a4..8dc0bce3a75f0 100644
--- a/apps/web/src/components/settings/useAvailableSettingsSearchItems.ts
+++ b/apps/web/src/components/settings/useAvailableSettingsSearchItems.ts
@@ -72,5 +72,6 @@ export function useAvailableSettingsSearchItems() {
     hasPeerLinkHost,
     hasFastWorktreeCheckoutEnvironment,
     hasTextGeneratorsEnvironment,
+    hasPrimaryEnvironment: primaryEnvironmentId !== null,
   });
 }
diff --git a/apps/web/src/onboarding/welcomeAgents.logic.test.ts b/apps/web/src/onboarding/welcomeAgents.logic.test.ts
index e599b451c445e..128cda4c41d92 100644
--- a/apps/web/src/onboarding/welcomeAgents.logic.test.ts
+++ b/apps/web/src/onboarding/welcomeAgents.logic.test.ts
@@ -1,4 +1,10 @@
-import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+import {
+  ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerProvider,
+  type ServerSettings,
+} from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
 import { groupWelcomeAgents } from "./welcomeAgents.logic";
@@ -36,6 +42,7 @@ describe("groupWelcomeAgents", () => {
         provider("Claude"),
         provider("Cursor", { installed: false, status: "warning", auth: { status: "unknown" } }),
       ],
+      undefined,
       nameOf,
       allowAll,
     );
@@ -47,9 +54,53 @@ describe("groupWelcomeAgents", () => {
     expect(groups.readyCount).toBe(2);
   });
 
+  it("uses this computer's settings and keeps agents that failed to load with the found ones", () => {
+    const acpRegistry = ProviderDriverKind.make("acpRegistry");
+    const settings: Pick<ServerSettings, "providerInstances" | "projectSettingsOverrides"> = {
+      providerInstances: {
+        [ProviderInstanceId.make("pi")]: { driver: ProviderDriverKind.make("pi") },
+        [ProviderInstanceId.make("registry")]: { driver: acpRegistry },
+      },
+      projectSettingsOverrides: {
+        [ProjectId.make("project-a")]: {
+          providerInstances: { [ProviderInstanceId.make("pi")]: { enabled: true } },
+        },
+      },
+    };
+    const groups = groupWelcomeAgents(
+      [
+        // The server checks Pi because project A turns it on; new projects still cannot use it.
+        provider("Pi"),
+        provider("Broken", {
+          enabled: false,
+          installed: false,
+          status: "error",
+          availability: "unavailable",
+          unavailableReason: "Invalid config for instance 'broken'.",
+        }),
+        // An ACP agent that is not prepared looks like one still being checked.
+        provider("Registry", {
+          driver: acpRegistry,
+          installed: false,
+          status: "warning",
+          auth: { status: "unknown" },
+        }),
+      ],
+      settings,
+      nameOf,
+      allowAll,
+    );
+
+    expect(names(groups.found)).toEqual(["Broken", "Registry"]);
+    expect(names(groups.available)).toEqual(["Pi"]);
+    expect(groups.readyCount).toBe(0);
+    expect(groups.checking).toBe(false);
+  });
+
   it("leaves out agents the computer's policy does not allow, ready or not", () => {
     const groups = groupWelcomeAgents(
       [provider("Codex"), provider("Blocked")],
+      undefined,
       nameOf,
       (entry) => entry.driver !== "blocked",
     );
@@ -59,7 +110,7 @@ describe("groupWelcomeAgents", () => {
   });
 
   it("reports checking before the computer has sent its providers", () => {
-    expect(groupWelcomeAgents(undefined, nameOf, allowAll)).toEqual({
+    expect(groupWelcomeAgents(undefined, undefined, nameOf, allowAll)).toEqual({
       checking: true,
       readyCount: 0,
       found: [],
diff --git a/apps/web/src/onboarding/welcomeAgents.logic.ts b/apps/web/src/onboarding/welcomeAgents.logic.ts
index 2b7a6943b731a..a01ccddde918c 100644
--- a/apps/web/src/onboarding/welcomeAgents.logic.ts
+++ b/apps/web/src/onboarding/welcomeAgents.logic.ts
@@ -1,13 +1,40 @@
-import type { ServerProvider } from "@t3tools/contracts";
+import {
+  isProviderAvailable,
+  ProviderDriverKind,
+  resolveProjectProviderInstanceEnabled,
+  type ServerProvider,
+  type ServerSettings,
+} from "@t3tools/contracts";
 
 import { getOnboardingProviderState } from "./providerReadiness.logic";
 
+type ComputerSettings = Pick<ServerSettings, "providerInstances" | "projectSettingsOverrides">;
+
 // Ready agents first, then ones that need a sign-in or a look. Never ranked by vendor.
 const FOUND_ORDER = { ready: 0, signIn: 1, attention: 2 } as const;
 type FoundState = keyof typeof FOUND_ORDER;
 
 const isFoundState = (state: string): state is FoundState => state in FOUND_ORDER;
 
+const ACP_REGISTRY_DRIVER = ProviderDriverKind.make("acpRegistry");
+
+/**
+ * An agent's state for new threads on this computer. The server also lists agents that only some
+ * projects turn on, and lists an agent it could not load as off, which Turn on cannot fix.
+ */
+export function welcomeAgentState(
+  provider: ServerProvider,
+  settings: ComputerSettings | null | undefined,
+) {
+  if (!isProviderAvailable(provider)) return "attention";
+  if (settings && !resolveProjectProviderInstanceEnabled(settings, null, provider.instanceId)) {
+    return "disabled";
+  }
+  const state = getOnboardingProviderState(provider);
+  // An ACP agent that is not prepared reports the same fields as one still being checked.
+  return state === "checking" && provider.driver === ACP_REGISTRY_DRIVER ? "attention" : state;
+}
+
 /**
  * Splits a computer's allowed providers into agents already on it and agents the user can add.
  * Order inside each group is by state, then by the name the user sees. Agents still being
@@ -15,27 +42,26 @@ const isFoundState = (state: string): state is FoundState => state in FOUND_ORDE
  */
 export function groupWelcomeAgents(
   providers: ReadonlyArray<ServerProvider> | null | undefined,
+  settings: ComputerSettings | null | undefined,
   nameOf: (provider: ServerProvider) => string,
   isAllowed: (provider: ServerProvider) => boolean,
 ) {
-  const found: ServerProvider[] = [];
+  const found: Array<{ readonly provider: ServerProvider; readonly state: FoundState }> = [];
   const available: ServerProvider[] = [];
   let checking = providers == null;
   let readyCount = 0;
   for (const provider of providers ?? []) {
     if (!isAllowed(provider)) continue;
-    const state = getOnboardingProviderState(provider);
+    const state = welcomeAgentState(provider, settings);
     if (state === "ready") readyCount += 1;
     if (state === "checking") checking = true;
-    if (isFoundState(state)) found.push(provider);
+    if (isFoundState(state)) found.push({ provider, state });
     else available.push(provider);
   }
   const byName = (a: ServerProvider, b: ServerProvider) => nameOf(a).localeCompare(nameOf(b));
-  const foundRank = (provider: ServerProvider) => {
-    const state = getOnboardingProviderState(provider);
-    return isFoundState(state) ? FOUND_ORDER[state] : FOUND_ORDER.attention;
-  };
-  found.sort((a, b) => foundRank(a) - foundRank(b) || byName(a, b));
+  found.sort(
+    (a, b) => FOUND_ORDER[a.state] - FOUND_ORDER[b.state] || byName(a.provider, b.provider),
+  );
   available.sort(byName);
-  return { checking, readyCount, found, available };
+  return { checking, readyCount, found: found.map((entry) => entry.provider), available };
 }
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 82a3750c4c255..3f9d2a3b5a74e 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -2,8 +2,8 @@
 
 T3 Code shows a Welcome page when you open a new installation. Existing
 workspaces skip it. It shows what T3 Code found on the computer you are using,
-on one page: your agents, projects from your Claude Code and Codex history, and
-the phone app. Only an agent is needed to start chatting.
+on one page: your agents, projects from your Claude Code, Codex, and Pi history,
+and the phone app. Only an agent is needed to start chatting.
 
 To see the page again, go to **Settings → About → Welcome page** and select
 **Open**. Direct links, such as Settings, open normally before setup is done.
@@ -26,14 +26,16 @@ T3 Code lists the agents it found on the computer first, ready ones on top.
 **Add more agents** lists every other agent T3 Code supports, A to Z, and opens by
 itself when no agent is found:
 
-- **Turn on** enables an agent that is off. T3 Code then checks whether it is
-  installed and signed in.
+- **Turn on** enables an agent that is off on this computer, including one only
+  some projects use. T3 Code then checks whether it is installed and signed in.
 - For Claude Code, **Install** or **Sign in** opens a terminal with the correct
   command ready to run. Install uses the vendor's own installer, which keeps
   **Update now** working in Settings.
 - For Codex, **Set up** offers sign-in with your ChatGPT account or your own
-  Codex CLI.
-- Other agents open their page in **Settings → Providers**.
+  Codex CLI. **Use existing CLI** opens the terminal to install or sign in, and
+  **Continue with ChatGPT** stays available until Codex is ready.
+- Other agents, and agents that could not load, open their page in
+  **Settings → Providers**.
 - **Browse** opens the ACP Registry for more agents.
 
 On the desktop app, when the folder of the `t3` command is not on your `PATH`,
@@ -50,8 +52,9 @@ without one.
 
 Select **Set up** to show QR codes for the App Store and Google Play. Then select
 **Sign in to T3 Connect** and allow this computer when T3 Code asks, so the app can
-reach it. Sign in to the app with the same account. On builds without T3 Connect,
-pair the app from **Settings → Sharing & access**.
+reach it. Sign in to the app with the same account. If you are signed in but this
+computer is not shared yet, select **Set up T3 Connect**. On builds without
+T3 Connect, pair the app from **Settings → Sharing & access**.
 
 ## Projects
 
@@ -62,7 +65,7 @@ one group. Directories that are not git repositories sit under "Other folders".
 
 The page offers git repositories active within the last 30 days with at least
 three conversations, already checked. Uncheck the row to start without them, or
-select **Review** to pick from everything found, with "Select all" and
+select **Review all** to pick from everything found, with "Select all" and
 "Select none". Linked worktrees of bare repositories
 can be offered as separate projects. Other linked git worktrees, Codex scratch
 directories under `Documents/Codex`, and anything under `Downloads` are not
@@ -73,7 +76,7 @@ projects it found and warns when projects or conversations may be missing.
 
 Imported projects include Claude, Codex and Pi conversations active within the last
 30 days. You can continue those conversations in T3 Code. Pi is off by default:
-enable it in Settings, then open the Welcome page again to import its sessions. Pi sessions
+select **Turn on** next to Pi, and the page looks for its sessions too. Pi sessions
 are read from each enabled Pi provider's session directory, which follows
 `PI_CODING_AGENT_SESSION_DIR` and `PI_CODING_AGENT_DIR` in its environment. A
 Pi conversation imports its active branch, the one Pi reopens.
@@ -94,4 +97,5 @@ with up to 100,000 input records. Run import again to continue a large batch.
 Completed conversations are not imported again. You can continue without the
 remaining history.
 
-You can start without importing. Navigation pauses while an import is running.
+You can start without importing. While an import runs, T3 Code stays on the
+Welcome page. If you quit, open the Welcome page again to import the rest.

From a424e9c0356f3880b87ef75322c67b1aaa9ef4e0 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 19:32:17 -0800
Subject: [PATCH 05/22] fix(web): Welcome page phone status follows the
 server's tunnel check

- Phone: only for the primary computer and only when policy allows other
  devices; T3 Connect sign-in only when Connect is allowed. The check needs a
  reachable result; unreachable offers "Check T3 Connect".
- Setup holds the page from Start until the landing, including the settings
  save, with one deduped toast.
- Codex: "Use existing CLI" opens the right terminal once Codex has checked the
  CLI, even from ChatGPT sign-in; a failed CLI check still offers Set up.
- A later scan's new projects get the default selection; projects already in
  T3 Code read "Import threads and start".
- Turned-on agents that are not installed say so; failed agents show the
  server's message. The fold decides once after the first check.
- The /welcome shell keeps running threads alive on desktop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       | 119 ++++++++---
 .../src/components/onboarding/WelcomePage.tsx | 198 ++++++++++++------
 apps/web/src/routes/__root.tsx                |   2 +
 docs/user/welcome-page.md                     |   6 +-
 4 files changed, 231 insertions(+), 94 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index 370bb32c692c1..7e1c1db8bf84d 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -29,7 +29,7 @@ const state = vi.hoisted(() => ({
   projects: null as unknown,
   providers: null as unknown,
   config: null as unknown,
-  candidates: [] as AgentSessionProjectCandidate[],
+  candidates: null as unknown,
   createProject: vi.fn(),
   importThreads: vi.fn(),
   refreshProviders: vi.fn(),
@@ -71,6 +71,7 @@ vi.mock(import("../../cloud/cloudLinkState"), async (original) => {
     ...(await original()),
     useCloudLinkState: (() => ({
       data: useAtomValue(state.linkState as Atom.Atom<EnvironmentCloudLinkStateResult | null>),
+      isPending: false,
     })) as never,
   };
 });
@@ -83,6 +84,7 @@ vi.mock(import("../../state/environments"), async (original) => ({
   useEnvironments: (() => ({
     environments: [{ environmentId: "primary", label: "primary" }],
   })) as never,
+  usePrimaryEnvironmentId: (() => "primary") as never,
 }));
 vi.mock(import("../../state/server"), async (original) => {
   const actual = await original();
@@ -113,20 +115,27 @@ vi.mock(import("../../state/agentSessions"), async (original) => ({
   ...(await original()),
   agentSessionImport: "importThreads" as never,
 }));
-vi.mock(import("../../onboarding/useProjectScans"), async (original) => ({
-  ...(await original()),
-  useProjectScans: (ids: readonly EnvironmentId[]) =>
-    ids.map((environmentId) => {
-      state.scan({ environmentId });
-      return {
-        environmentId,
-        data: { candidates: state.candidates, truncated: false } as never,
-        isPending: false,
-        error: null,
-        refresh: state.refreshScan,
-      };
-    }),
-}));
+vi.mock(import("../../onboarding/useProjectScans"), async (original) => {
+  const { useAtomValue } = await import("@effect/atom-react");
+  return {
+    ...(await original()),
+    useProjectScans: (ids: readonly EnvironmentId[]) => {
+      const candidates = useAtomValue(
+        state.candidates as Atom.Atom<AgentSessionProjectCandidate[]>,
+      );
+      return ids.map((environmentId) => {
+        state.scan({ environmentId });
+        return {
+          environmentId,
+          data: { candidates, truncated: false } as never,
+          isPending: false,
+          error: null,
+          refresh: state.refreshScan,
+        };
+      });
+    },
+  };
+});
 vi.mock(import("../../state/use-atom-command"), async (original) => ({
   ...(await original()),
   useAtomCommand: ((command: "createProject" | "importThreads" | "refreshProviders") =>
@@ -177,6 +186,10 @@ function projectsAtom() {
   return state.projects as Atom.Writable<ReadonlyArray<Project>>;
 }
 
+function candidatesAtom() {
+  return state.candidates as Atom.Writable<ReadonlyArray<AgentSessionProjectCandidate>>;
+}
+
 function setGrant(environmentId: EnvironmentId, allowed: boolean) {
   appAtomRegistry.set(
     sessionAtom(environmentId),
@@ -277,7 +290,10 @@ function setup() {
   state.projects = Atom.make<ReadonlyArray<Project>>([]).pipe(Atom.keepAlive);
   state.providers = Atom.make<ReadonlyArray<ServerProvider>>([readyClaude]).pipe(Atom.keepAlive);
   state.config = Atom.make(null).pipe(Atom.keepAlive);
-  state.candidates = [candidate("/projects/first"), candidate("/projects/second")];
+  state.candidates = Atom.make<ReadonlyArray<AgentSessionProjectCandidate>>([
+    candidate("/projects/first"),
+    candidate("/projects/second"),
+  ]).pipe(Atom.keepAlive);
   state.createProject
     .mockReset()
     .mockImplementation(async (input: CreateProjectInput) => recordProject(input));
@@ -325,7 +341,7 @@ it("rechecks after project creation and can retry its history without recreating
 
 it("completes accepted imports when permission is revoked after the final server write", async () => {
   using _now = setup();
-  state.candidates = state.candidates.slice(0, 1);
+  appAtomRegistry.set(candidatesAtom(), [candidate("/projects/first")]);
   const imported = deferred<{ importedCount: number; skippedCount: number }>();
   state.importThreads.mockImplementationOnce(async () =>
     AsyncResult.success(await imported.promise),
@@ -345,7 +361,7 @@ it("completes accepted imports when permission is revoked after the final server
 
 it("finishes setup without landing when the imported project never reaches the client", async () => {
   using _now = setup();
-  state.candidates = state.candidates.slice(0, 1);
+  appAtomRegistry.set(candidatesAtom(), [candidate("/projects/first")]);
   // The server accepts the project, but it never shows up in the client's projects.
   state.createProject.mockResolvedValue(AsyncResult.success(undefined));
   state.waitForProject.mockRejectedValue(new Error("The project did not appear."));
@@ -405,15 +421,42 @@ it("blocks leaving the page until the imported projects have landed", async () =
   await leave();
   expect(screen.router?.state.location.pathname).toBe("/");
 
+  const saved = deferred<void>();
+  state.completeOnboarding.mockImplementationOnce(() => saved.promise);
   await act(async () => {
     landing.resolve();
     await landing.promise;
   });
+  await vi.waitFor(() => expect(state.completeOnboarding).toHaveBeenCalledOnce());
+  await leave();
+  expect(screen.router?.state.location.pathname).toBe("/");
+
+  await act(async () => {
+    saved.resolve();
+    await saved.promise;
+  });
   await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
   expect(screen.router?.state.location.pathname).toBe("/");
   expect(state.createProject).toHaveBeenCalledTimes(2);
 });
 
+it("selects projects that a later scan finds after the selection was changed", async () => {
+  using _now = setup();
+  await using _screen = await mountWelcome();
+  const bringIn = document.querySelector<HTMLElement>('[role="checkbox"]');
+  await act(async () => bringIn?.click());
+  expect(button("Start").disabled).toBe(false);
+
+  // Turning on another agent rescans and finds a recent project the user has not seen.
+  await act(async () =>
+    appAtomRegistry.set(candidatesAtom(), [
+      ...appAtomRegistry.get(candidatesAtom()),
+      candidate("/projects/third"),
+    ]),
+  );
+  expect(button("Add 1 project and start").disabled).toBe(false);
+});
+
 it("starts without importing when this connection cannot import projects", async () => {
   using _now = setup();
   setGrant(primaryId, false);
@@ -434,16 +477,34 @@ it("says the phone is set up only once this computer is shared with the signed-i
   // Signed in, but "Not now" on the share step left this computer unreachable.
   expect(pageText()).toContain("Set up T3 Connect");
 
-  await act(async () =>
-    appAtomRegistry.set(state.linkState as Atom.Writable<EnvironmentCloudLinkStateResult | null>, {
-      linked: true,
-      cloudUserId: "user_1",
-      relayUrl: null,
-      relayIssuer: null,
-      managedTunnelActive: true,
-      publishAgentActivity: true,
-    }),
-  );
+  const share = (reachability: EnvironmentCloudLinkStateResult["reachability"]) =>
+    act(async () =>
+      appAtomRegistry.set(
+        state.linkState as Atom.Writable<EnvironmentCloudLinkStateResult | null>,
+        {
+          linked: true,
+          cloudUserId: "user_1",
+          relayUrl: null,
+          relayIssuer: null,
+          managedTunnelActive: true,
+          publishAgentActivity: true,
+          reachability,
+        },
+      ),
+    );
+  const checkedAt = "2026-01-01T00:00:00.000Z";
+  await share({
+    status: "unreachable",
+    checkedAt,
+    cause: "connector_not_running",
+    reason: "The tunnel is not running.",
+    hint: null,
+    fix: "Turn T3 Connect off and on.",
+  });
+  expect(pageText()).toContain("Check T3 Connect");
+  expect(pageText()).not.toContain("Your phone can reach this computer.");
+
+  await share({ status: "reachable", checkedAt, readyConnections: 4, protocol: "quic" });
   expect(pageText()).toContain("Your phone can reach this computer.");
-  expect(pageText()).not.toContain("Set up T3 Connect");
+  expect(pageText()).not.toContain("Check T3 Connect");
 });
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index 0a548e3c42dac..d02827695e3d4 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -18,6 +18,8 @@ import {
   CommandId,
   AuthOrchestrationOperateScope,
   isManagedDriverAllowed,
+  isProviderAvailable,
+  managedCapabilityDenial,
   ProviderDriverKind,
   ThreadId,
 } from "@t3tools/contracts";
@@ -59,7 +61,7 @@ import { groupWelcomeAgents, welcomeAgentState } from "../../onboarding/welcomeA
 import { newProjectId, randomUUID } from "../../lib/utils";
 import { agentSessionImport } from "../../state/agentSessions";
 import { readProjects, waitForProject } from "../../state/entities";
-import { useEnvironments } from "../../state/environments";
+import { useEnvironments, usePrimaryEnvironmentId } from "../../state/environments";
 import { managedTelemetryOffMessage, useManagedPolicy } from "../../state/managedPolicy";
 import { useProjectScans } from "../../onboarding/useProjectScans";
 import { projectEnvironment } from "../../state/projects";
@@ -113,9 +115,27 @@ export function WelcomePage({
     environments.find((environment) => environment.environmentId === environmentId)?.label ??
     "this computer";
   const agentReady = useWelcomeAgents(environmentId).readyCount > 0;
+  // The phone links and pairs the primary computer, so it is offered only when setting that one up.
+  const isPrimary = usePrimaryEnvironmentId() === environmentId;
   const scans = useProjectScans([environmentId]);
   const [importSelection, setImportSelection] = useState<ImportSelection | null>(null);
   const [isImporting, setIsImporting] = useState(false);
+  // True from Start until the landing; leaving earlier would drop the import or the landing.
+  const holdPageRef = useRef(false);
+  useBlocker({
+    shouldBlockFn: () => {
+      if (!holdPageRef.current) return false;
+      toastManager.add({
+        id: "welcome-finishing",
+        type: "info",
+        title: "Finishing setup",
+        description: "One moment.",
+      });
+      return true;
+    },
+    // Electron cancels a quit silently when unload is blocked. A later visit resumes the import.
+    enableBeforeUnload: false,
+  });
   const finishingPromiseRef = useRef<Promise<boolean> | null>(null);
   const completionErrorToastIdRef = useRef<ReturnType<typeof toastManager.add> | null>(null);
   const finish = (
@@ -129,12 +149,15 @@ export function WelcomePage({
       completionErrorToastIdRef.current = null;
     }
 
+    holdPageRef.current = true;
     const completion = completeOnboarding()
       .then(async () => {
         if (completionErrorToastIdRef.current !== null) {
           toastManager.close(completionErrorToastIdRef.current);
           completionErrorToastIdRef.current = null;
         }
+        // Release before onDone so its own navigation is not blocked.
+        holdPageRef.current = false;
         await onDone(projectRef);
         if (importWarning) {
           toastManager.add({
@@ -152,6 +175,7 @@ export function WelcomePage({
         return true;
       })
       .catch(() => {
+        holdPageRef.current = false;
         const errorToast = {
           type: "error",
           title: "Could not finish setup",
@@ -178,12 +202,14 @@ export function WelcomePage({
     onImportSelectionChange: setImportSelection,
     isImporting,
     setIsImporting,
+    holdPageRef,
     onDone: finish,
   });
   // Without import permission, starting simply skips the projects.
-  const selectedCount = projectImport.canWrite ? projectImport.selected.length : 0;
+  const selected = projectImport.canWrite ? projectImport.selected : [];
+  const newCount = selected.filter((candidate) => !candidate.alreadyImported).length;
   const start = () => {
-    if (selectedCount > 0) void projectImport.runImport(projectImport.selected);
+    if (selected.length > 0) void projectImport.runImport(selected);
     else projectImport.finishAfterImport();
   };
 
@@ -215,7 +241,7 @@ export function WelcomePage({
               projectImport={projectImport}
               isImporting={isImporting}
             />
-            <PhoneSection environmentId={environmentId} />
+            {isPrimary ? <PhoneSection environmentId={environmentId} /> : null}
             <div className="mt-8 flex flex-wrap items-center justify-between gap-3 border-t border-border/70 pt-6">
               {agentReady ? (
                 <span />
@@ -231,9 +257,11 @@ export function WelcomePage({
                 <Button disabled={!agentReady || isImporting} onClick={start}>
                   {isImporting
                     ? "Importing…"
-                    : selectedCount > 0
-                      ? `Add ${selectedCount} ${selectedCount === 1 ? "project" : "projects"} and start`
-                      : "Start"}
+                    : newCount > 0
+                      ? `Add ${newCount} ${newCount === 1 ? "project" : "projects"} and start`
+                      : selected.length > 0
+                        ? "Import threads and start"
+                        : "Start"}
                 </Button>
               </div>
             </div>
@@ -351,20 +379,29 @@ function AgentsSection({
   const [moreOpen, setMoreOpen] = useState<boolean | null>(null);
   const [addingProvider, setAddingProvider] = useState(false);
   const [codexSetupId, setCodexSetupId] = useState<ProviderInstanceId | null>(null);
+  const [cliTerminalFor, setCliTerminalFor] = useState<ProviderInstanceId | null>(null);
 
   // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- asks the environment to refresh its provider list when the environment changes
   useEffect(() => {
     void refreshProviders({ environmentId, input: {} });
   }, [environmentId, refreshProviders]);
 
-  // With nothing on this computer yet, the list of agents to add is the main task.
-  const showMore = moreOpen ?? found.length === 0;
+  // Decided once the first check ends: with nothing on this computer, adding an agent is the task.
+  if (moreOpen === null && !checking) setMoreOpen(found.length === 0);
+  const showMore = moreOpen === true;
   const acpAllowed = isManagedDriverAllowed(serverConfig?.managedPolicy, ACP_REGISTRY_DRIVER_KIND);
   const stateOf = (provider: ServerProvider) => welcomeAgentState(provider, serverConfig?.settings);
   const needsInstallOrSignIn = (provider: ServerProvider) => {
     const state = stateOf(provider);
     return isInstallableDriver(provider.driver) && (state === "install" || state === "signIn");
   };
+  // Codex's card also offers ChatGPT sign-in, which still works when the CLI check failed.
+  const codexNeedsSetup = (provider: ServerProvider) =>
+    provider.driver === "codex" &&
+    (needsInstallOrSignIn(provider) ||
+      (stateOf(provider) === "attention" &&
+        isProviderAvailable(provider) &&
+        provider.auth.status !== "authenticated"));
   // Codex setup stays mounted by instance while its status changes, so a sign-in that
   // starts after an install is not lost when the agent moves between groups.
   const codexSetupProvider =
@@ -398,6 +435,21 @@ function AgentsSection({
     });
   };
 
+  // "Use existing CLI" opens the CLI's terminal once Codex has checked the CLI. Only the
+  // ChatGPT sign-in runtime reports `setup.canAuthenticate`, so its status is not the CLI's.
+  const cliProvider =
+    cliTerminalFor === null
+      ? undefined
+      : providers?.find((provider) => provider.instanceId === cliTerminalFor);
+  if (
+    cliProvider !== undefined &&
+    cliProvider.setup?.canAuthenticate !== true &&
+    stateOf(cliProvider) !== "checking"
+  ) {
+    setCliTerminalFor(null);
+    if (needsInstallOrSignIn(cliProvider)) openTerminal(cliProvider);
+  }
+
   const turnOn = async (provider: ServerProvider) => {
     if (serverConfig === null) return;
     const instance = serverConfig.settings.providerInstances[provider.instanceId] ?? {
@@ -408,8 +460,10 @@ function AgentsSection({
       instanceId: provider.instanceId,
       instance: { ...instance, enabled: true },
     });
-    if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
-      toastManager.add({ type: "error", title: `Could not turn on ${agentName(provider)}` });
+    if (result._tag === "Failure") {
+      if (!isAtomCommandInterrupted(result)) {
+        toastManager.add({ type: "error", title: `Could not turn on ${agentName(provider)}` });
+      }
       return;
     }
     void refreshProviders({ environmentId, input: { instanceId: provider.instanceId } });
@@ -431,7 +485,7 @@ function AgentsSection({
         </Button>
       );
     }
-    if (provider.driver === "codex" && serverConfig !== null && needsInstallOrSignIn(provider)) {
+    if (serverConfig !== null && codexNeedsSetup(provider)) {
       const open = codexSetupId === provider.instanceId;
       return (
         <Button
@@ -557,7 +611,7 @@ function AgentsSection({
             environmentId={environmentId}
             provider={codexSetupProvider}
             serverConfig={serverConfig}
-            onOpenTerminal={() => openTerminal(codexSetupProvider)}
+            onUseCli={() => setCliTerminalFor(codexSetupProvider.instanceId)}
           />
         </div>
       ) : null}
@@ -629,7 +683,7 @@ function ProjectsSection({
     visibleImportError,
   } = projectImport;
   if (scan === undefined) return null;
-  if (scan.isPending && scan.data === null) {
+  if (scan.isPending && candidates.length === 0) {
     return (
       <WelcomeSection title="Projects">
         <p className="text-sm text-muted-foreground">
@@ -668,17 +722,18 @@ function ProjectsSection({
   return (
     <WelcomeSection title="Projects" status={`From your ${IMPORT_SOURCES_LABEL} history`}>
       <div className="flex items-center gap-3 rounded-lg border border-border bg-background px-4 py-3">
-        <Checkbox
-          aria-label="Bring in projects"
-          checked={canWrite && selected.length > 0}
-          disabled={isImporting || !canWrite}
-          onCheckedChange={(checked) => setSelectedKeys(new Set(checked ? defaultKeys : []))}
-        />
-        <span className="min-w-0 flex-1 text-sm text-foreground">
-          {canWrite && selected.length > 0
-            ? `Bring in ${selected.length} ${selected.length === 1 ? "project" : "projects"} and their threads`
-            : "Bring in projects and their threads"}
-        </span>
+        <label className="flex min-w-0 flex-1 items-center gap-3">
+          <Checkbox
+            checked={canWrite && selected.length > 0}
+            disabled={isImporting || !canWrite}
+            onCheckedChange={(checked) => setSelectedKeys(new Set(checked ? defaultKeys : []))}
+          />
+          <span className="min-w-0 flex-1 text-sm text-foreground">
+            {canWrite && selected.length > 0
+              ? `Bring in ${selected.length} ${selected.length === 1 ? "project" : "projects"} and their threads`
+              : "Bring in projects and their threads"}
+          </span>
+        </label>
         {canWrite ? (
           <Button
             variant="ghost-muted"
@@ -741,6 +796,11 @@ function ProjectsSection({
 
 function PhoneSection({ environmentId }: { readonly environmentId: EnvironmentId }) {
   const [open, setOpen] = useState(false);
+  const policy = useManagedPolicy(environmentId);
+  // A policy that blocks other devices leaves the phone nothing to connect to.
+  if (managedCapabilityDenial(policy, "remoteClients") !== undefined) return null;
+  const connectAllowed =
+    hasCloudPublicConfig() && managedCapabilityDenial(policy, "connect") === undefined;
   return (
     <WelcomeSection title="Phone" status="Optional">
       <Collapsible open={open} onOpenChange={setOpen}>
@@ -777,7 +837,7 @@ function PhoneSection({ environmentId }: { readonly environmentId: EnvironmentId
               <span className="text-sm text-muted-foreground">Scan to get the app.</span>
             </div>
             <div className="flex flex-col justify-center gap-2 rounded-lg border border-border bg-background p-3.5">
-              {hasCloudPublicConfig() ? (
+              {connectAllowed ? (
                 <PhoneConnectLink environmentId={environmentId} />
               ) : (
                 <>
@@ -805,7 +865,8 @@ function PhoneSection({ environmentId }: { readonly environmentId: EnvironmentId
 function PhoneConnectLink({ environmentId }: { readonly environmentId: EnvironmentId }) {
   const { isLoaded, isSignedIn, userId } = useAuth({ treatPendingAsSignedOut: false });
   const { openAuthPrompt } = useT3ConnectAuthPrompt();
-  const link = useCloudLinkState(environmentId).data;
+  const linkState = useCloudLinkState(environmentId);
+  const link = linkState.data;
   // The phone reaches this computer through its tunnel; older servers leave that flag out.
   const shared =
     link !== null &&
@@ -813,7 +874,12 @@ function PhoneConnectLink({ environmentId }: { readonly environmentId: Environme
     link.linkRevoked !== true &&
     link.cloudUserId === userId &&
     link.managedTunnelActive !== false;
-  if (isSignedIn && shared) {
+  // The server checks the tunnel on its own; until it has, the result is unknown.
+  const reachability = shared ? link.reachability?.status : undefined;
+  if (isSignedIn && link === null && linkState.isPending) {
+    return <span className="text-sm text-muted-foreground">Checking T3 Connect…</span>;
+  }
+  if (isSignedIn && reachability === "reachable") {
     return (
       <span className="inline-flex items-center gap-1.5 text-sm text-foreground">
         <CheckIcon className="size-4 shrink-0 text-success-foreground" />
@@ -821,12 +887,21 @@ function PhoneConnectLink({ environmentId }: { readonly environmentId: Environme
       </span>
     );
   }
+  if (isSignedIn && shared && reachability === undefined) {
+    return (
+      <span className="text-sm text-muted-foreground">
+        T3 Connect is on for this computer. Sign in to the app with the same account.
+      </span>
+    );
+  }
   if (isSignedIn) {
     // Signing in alone does not share this computer, for example after "Not now".
     return (
       <>
         <span className="text-sm text-muted-foreground">
-          Signed in. Share this computer so the app can reach it.
+          {shared
+            ? "T3 Connect is on, but the app cannot reach this computer."
+            : "Signed in. Share this computer so the app can reach it."}
         </span>
         <Button
           variant="outline"
@@ -834,7 +909,7 @@ function PhoneConnectLink({ environmentId }: { readonly environmentId: Environme
           className="self-start"
           render={<Link to="/settings/access" />}
         >
-          Set up T3 Connect
+          {shared ? "Check T3 Connect" : "Set up T3 Connect"}
         </Button>
       </>
     );
@@ -862,12 +937,12 @@ function OnboardingCodexSetup({
   environmentId,
   provider,
   serverConfig,
-  onOpenTerminal,
+  onUseCli,
 }: {
   readonly environmentId: EnvironmentId;
   readonly provider: ServerProvider;
   readonly serverConfig: ServerConfig;
-  readonly onOpenTerminal: () => void;
+  readonly onUseCli: () => void;
 }) {
   const canManageProviders = useEnvironmentScope(environmentId, AuthProvidersManageScope);
   const persistProviderInstance = usePersistEnvironmentProviderInstanceMutation(environmentId);
@@ -880,9 +955,10 @@ function OnboardingCodexSetup({
     instance.config !== null && typeof instance.config === "object" ? instance.config : {};
   const mode = readCodexSetupMode(config);
   const changeMode = (setupMode: "managed" | "existing") => {
-    // On the CLI card, "Use existing CLI" also opens a terminal to install or sign in.
-    if (setupMode === "existing" && mode === "existing") onOpenTerminal();
-    if (!readEnvironmentScope(environmentId, AuthProvidersManageScope)) return;
+    // "Use existing CLI" also opens a terminal to install or sign in to the CLI.
+    if (setupMode === "existing") onUseCli();
+    const unchanged = "setupMode" in config && config.setupMode === setupMode;
+    if (unchanged || !readEnvironmentScope(environmentId, AuthProvidersManageScope)) return;
     // One-instance upsert keeps a provider another client added in the meantime.
     void persistProviderInstance({
       operation: "upsert",
@@ -938,14 +1014,19 @@ function AgentCard({
   readonly compact?: boolean;
 }) {
   const name = agentName(provider);
+  // Claude Code and Codex tiles show Install or Set up; other agents that are on say why not.
   const detail =
-    compact || state === "ready" || state === "checking"
-      ? null
-      : state === "install"
-        ? "Not installed"
-        : state === "disabled"
-          ? "Off"
-          : (provider.unavailableReason ?? getProviderSummary(provider).headline);
+    state === "install"
+      ? isInstallableDriver(provider.driver)
+        ? null
+        : "Not installed"
+      : compact || state === "ready" || state === "checking"
+        ? null
+        : state === "attention"
+          ? (provider.unavailableReason ??
+            provider.message ??
+            getProviderSummary(provider).headline)
+          : getProviderSummary(provider).headline;
   return (
     <div
       className={cn(
@@ -961,7 +1042,7 @@ function AgentCard({
       <div className="min-w-0 flex-1">
         <span className="block truncate text-sm font-medium text-foreground">{name}</span>
         {detail ? (
-          <p className="mt-0.5 text-xs leading-relaxed break-words text-muted-foreground">
+          <p className="mt-0.5 line-clamp-2 text-xs leading-relaxed break-words text-muted-foreground">
             {detail}
           </p>
         ) : null}
@@ -1146,8 +1227,8 @@ function AgentInstallTerminal({
 const IMPORT_PERMISSION_MESSAGE = "This connection cannot import projects or thread history.";
 
 interface ImportSelection {
-  // Computers whose projects were listed when the selection changed; later ones get the defaults.
-  readonly environmentIds: ReadonlySet<EnvironmentId>;
+  // Projects listed when the selection changed; projects found later get the defaults.
+  readonly knownKeys: ReadonlySet<string>;
   readonly keys: ReadonlySet<string>;
 }
 
@@ -1159,6 +1240,7 @@ function useProjectImport({
   onImportSelectionChange,
   isImporting,
   setIsImporting,
+  holdPageRef,
   onDone,
 }: {
   readonly scans: ReturnType<typeof useProjectScans>;
@@ -1166,6 +1248,8 @@ function useProjectImport({
   readonly onImportSelectionChange: (next: ImportSelection) => void;
   readonly isImporting: boolean;
   readonly setIsImporting: (value: boolean) => void;
+  // Blocks leaving the page; onDone releases it before landing.
+  readonly holdPageRef: { current: boolean };
   readonly onDone: (
     projectRef?: ScopedProjectRef,
     importWarning?: string,
@@ -1184,17 +1268,6 @@ function useProjectImport({
     new Map<string, { readonly projectId: ProjectId; readonly commandId: CommandId }>(),
   );
   const importGenerationRef = useRef(0);
-  // True from the first project until the landing; leaving earlier drops the rest of the import.
-  const holdPageRef = useRef(false);
-  useBlocker({
-    shouldBlockFn: () => {
-      if (!holdPageRef.current) return false;
-      toastManager.add({ type: "info", title: "Importing projects", description: "One moment." });
-      return true;
-    },
-    // Electron cancels a quit silently when unload is blocked. A later visit resumes the import.
-    enableBeforeUnload: false,
-  });
 
   // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- bumps the import generation on mount and unmount so in-flight imports drop stale results
   useEffect(() => {
@@ -1215,16 +1288,14 @@ function useProjectImport({
   );
   const recentKeys = new Set(recent.map((candidate) => candidate.key));
   const selected = candidates.filter((candidate) =>
-    importSelection?.environmentIds.has(candidate.environmentId)
+    importSelection?.knownKeys.has(candidate.key)
       ? importSelection.keys.has(candidate.key)
       : recentKeys.has(candidate.key),
   );
   const selectedKeys = new Set(selected.map((candidate) => candidate.key));
   const setSelectedKeys = (keys: ReadonlySet<string>) =>
     onImportSelectionChange({
-      environmentIds: new Set(
-        scans.flatMap((scan) => (scan.data === null ? [] : [scan.environmentId])),
-      ),
+      knownKeys: new Set(candidates.map((candidate) => candidate.key)),
       keys,
     });
 
@@ -1259,9 +1330,10 @@ function useProjectImport({
         () => undefined,
       )
       .then(async (landing) => {
-        // Release before onDone so its own navigation is not blocked.
-        holdPageRef.current = false;
-        if (importGeneration !== importGenerationRef.current) return;
+        if (importGeneration !== importGenerationRef.current) {
+          holdPageRef.current = false;
+          return;
+        }
         const completed = await onDone(
           landing,
           importWarningRef.current,
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index d4e40af9a4263..feec09043c7ec 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -169,6 +169,8 @@ function RootRouteBranch() {
       <>
         {/* The Welcome page can sign in to T3 Connect; this links the computer for the phone. */}
         <ConnectOnboardingDialog />
+        {/* Settings can reopen the page while threads run. */}
+        {isElectron ? <RunningThreadKeepAlive /> : null}
         <CustomSnoozeDialogHost />
         <GuestShareDialogHost />
         <CommandPalette>
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 3f9d2a3b5a74e..e49a1ba85730a 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -53,8 +53,10 @@ without one.
 Select **Set up** to show QR codes for the App Store and Google Play. Then select
 **Sign in to T3 Connect** and allow this computer when T3 Code asks, so the app can
 reach it. Sign in to the app with the same account. If you are signed in but this
-computer is not shared yet, select **Set up T3 Connect**. On builds without
-T3 Connect, pair the app from **Settings → Sharing & access**.
+computer is not shared yet, select **Set up T3 Connect**. If T3 Connect is on but
+the app cannot reach this computer, select **Check T3 Connect** to see why. On
+builds without T3 Connect, or when your organization turns it off, pair the app
+from **Settings → Sharing & access**.
 
 ## Projects
 

From 461a04453f67988b3d37f00dbda0f6a2eadd8397 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 19:47:33 -0800
Subject: [PATCH 06/22] fix(web): Welcome page keeps project choices and mounts
 the app's dialogs

- Both shells mount the same action dialogs, so sharing this computer can
  install the relay client and sidebar confirmations work on /welcome.
- A computer's project choices survive a visit to Settings and clear when
  setup finishes; new projects are counted against the current project list.
- Setup stays busy while it saves after an import with nothing to open.
- "Use existing CLI" also opens the terminal when the CLI check failed, and the
  phone status rereads the tunnel check every 30 s while open.
- A ChatGPT sign-in return waits for the computer list before choosing.
- "Import" is the one verb for projects; the checkbox shows a partial choice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       |  70 ++++++++--
 .../src/components/onboarding/WelcomePage.tsx | 128 +++++++++++-------
 ...ogic.test.ts => welcomePage.logic.test.ts} |  43 +++++-
 ...meAgents.logic.ts => welcomePage.logic.ts} |  38 ++++++
 apps/web/src/onboarding/welcomeState.ts       |  19 +++
 apps/web/src/routes/__root.tsx                |  29 ++--
 apps/web/src/routes/welcome.tsx               |   5 +-
 7 files changed, 258 insertions(+), 74 deletions(-)
 rename apps/web/src/onboarding/{welcomeAgents.logic.test.ts => welcomePage.logic.test.ts} (67%)
 rename apps/web/src/onboarding/{welcomeAgents.logic.ts => welcomePage.logic.ts} (67%)
 create mode 100644 apps/web/src/onboarding/welcomeState.ts

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index 7e1c1db8bf84d..cf782ee1aecf6 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -146,6 +146,7 @@ vi.mock(import("../settings/ChatGptWelcomeCoordinator"), async (original) => ({
   ChatGptWelcomeCoordinator: () => <></>,
 }));
 
+import { welcomeImportSelectionAtom } from "../../onboarding/welcomeState";
 import { appAtomRegistry } from "../../rpc/atomRegistry";
 import { WelcomePage } from "./WelcomePage";
 
@@ -309,6 +310,7 @@ function setup() {
   state.cloud = false;
   state.auth = { isLoaded: true, isSignedIn: false, userId: null };
   state.linkState = Atom.make<EnvironmentCloudLinkStateResult | null>(null).pipe(Atom.keepAlive);
+  appAtomRegistry.set(welcomeImportSelectionAtom(primaryId), null);
   return now;
 }
 
@@ -320,7 +322,7 @@ it("rechecks after project creation and can retry its history without recreating
     return recordProject(input);
   });
   await using _screen = await mountWelcome();
-  await click("Add 2 projects and start");
+  await click("Import 2 projects and start");
   expect(state.createProject).toHaveBeenCalledOnce();
   await act(async () => {
     setGrant(primaryId, false);
@@ -330,10 +332,11 @@ it("rechecks after project creation and can retry its history without recreating
   expect(state.importThreads).not.toHaveBeenCalled();
   expect(state.createProject).toHaveBeenCalledOnce();
   expect(state.onDone).not.toHaveBeenCalled();
-  expect(pageText()).toContain(permissionMessage);
+  await vi.waitFor(() => expect(pageText()).toContain(permissionMessage));
 
   await act(async () => setGrant(primaryId, true));
-  await click("Add 2 projects and start");
+  // The first project now exists, so only the second counts as new.
+  await click("Import 1 project and start");
   expect(state.createProject).toHaveBeenCalledTimes(2);
   expect(state.importThreads).toHaveBeenCalledTimes(2);
   expect(state.onDone).toHaveBeenCalledOnce();
@@ -347,7 +350,7 @@ it("completes accepted imports when permission is revoked after the final server
     AsyncResult.success(await imported.promise),
   );
   await using _screen = await mountWelcome();
-  await click("Add 1 project and start");
+  await click("Import 1 project and start");
   await act(async () => {
     setGrant(primaryId, false);
     imported.resolve({ importedCount: 1, skippedCount: 0 });
@@ -368,13 +371,13 @@ it("finishes setup without landing when the imported project never reaches the c
   state.completeOnboarding.mockRejectedValueOnce(new Error("offline"));
   await using _screen = await mountWelcome();
 
-  await click("Add 1 project and start");
+  await click("Import 1 project and start");
   await vi.waitFor(() => expect(state.completeOnboarding).toHaveBeenCalledOnce());
   // A failed completion hands the step back instead of leaving it importing.
-  await vi.waitFor(() => expect(button("Add 1 project and start").disabled).toBe(false));
+  await vi.waitFor(() => expect(button("Import 1 project and start").disabled).toBe(false));
   expect(state.onDone).not.toHaveBeenCalled();
 
-  await click("Add 1 project and start");
+  await click("Import 1 project and start");
   await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
   expect(state.onDone).toHaveBeenCalledWith(undefined);
 });
@@ -383,7 +386,7 @@ it("waits for a ready agent to start, and Start without an agent still finishes
   using _now = setup();
   appAtomRegistry.set(state.providers as Atom.Writable<ReadonlyArray<ServerProvider>>, []);
   await using _screen = await mountWelcome();
-  expect(button("Add 2 projects and start").disabled).toBe(true);
+  expect(button("Import 2 projects and start").disabled).toBe(true);
 
   await click("Start without an agent");
   await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
@@ -405,7 +408,7 @@ it("blocks leaving the page until the imported projects have landed", async () =
     },
   );
   await using screen = await mountWelcome();
-  await click("Add 2 projects and start");
+  await click("Import 2 projects and start");
 
   // A blocked navigation never settles, so it is not awaited.
   const leave = () =>
@@ -445,7 +448,7 @@ it("selects projects that a later scan finds after the selection was changed", a
   await using _screen = await mountWelcome();
   const bringIn = document.querySelector<HTMLElement>('[role="checkbox"]');
   await act(async () => bringIn?.click());
-  expect(button("Start").disabled).toBe(false);
+  await vi.waitFor(() => expect(button("Start").disabled).toBe(false));
 
   // Turning on another agent rescans and finds a recent project the user has not seen.
   await act(async () =>
@@ -454,7 +457,46 @@ it("selects projects that a later scan finds after the selection was changed", a
       candidate("/projects/third"),
     ]),
   );
-  expect(button("Add 1 project and start").disabled).toBe(false);
+  await vi.waitFor(() => expect(button("Import 1 project and start").disabled).toBe(false));
+});
+
+it("keeps the project choice across a visit to Settings until setup finishes", async () => {
+  using _now = setup();
+  {
+    await using _first = await mountWelcome();
+    const importProjects = document.querySelector<HTMLElement>('[role="checkbox"]');
+    await act(async () => importProjects?.click());
+    await vi.waitFor(() => expect(button("Start").disabled).toBe(false));
+  }
+  // Coming back from Settings mounts the page again.
+  {
+    await using _second = await mountWelcome();
+    expect(button("Start").disabled).toBe(false);
+    await click("Start");
+    await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
+    expect(state.createProject).not.toHaveBeenCalled();
+  }
+  await using _third = await mountWelcome();
+  expect(button("Import 2 projects and start").disabled).toBe(false);
+});
+
+it("stays busy while setup saves after an import with nothing to open", async () => {
+  using _now = setup();
+  appAtomRegistry.set(candidatesAtom(), [candidate("/projects/first")]);
+  state.importThreads.mockResolvedValue(AsyncResult.success({ importedCount: 0, skippedCount: 1 }));
+  const saved = deferred<void>();
+  state.completeOnboarding.mockImplementationOnce(() => saved.promise);
+  await using _screen = await mountWelcome();
+
+  await click("Import 1 project and start");
+  await vi.waitFor(() => expect(state.completeOnboarding).toHaveBeenCalledOnce());
+  expect(button("Importing…").disabled).toBe(true);
+  await act(async () => {
+    saved.resolve();
+    await saved.promise;
+  });
+  await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
+  expect(state.createProject).toHaveBeenCalledOnce();
 });
 
 it("starts without importing when this connection cannot import projects", async () => {
@@ -475,7 +517,7 @@ it("says the phone is set up only once this computer is shared with the signed-i
   await using _screen = await mountWelcome();
   await click("Set up");
   // Signed in, but "Not now" on the share step left this computer unreachable.
-  expect(pageText()).toContain("Set up T3 Connect");
+  await vi.waitFor(() => expect(pageText()).toContain("Set up T3 Connect"));
 
   const share = (reachability: EnvironmentCloudLinkStateResult["reachability"]) =>
     act(async () =>
@@ -501,10 +543,10 @@ it("says the phone is set up only once this computer is shared with the signed-i
     hint: null,
     fix: "Turn T3 Connect off and on.",
   });
-  expect(pageText()).toContain("Check T3 Connect");
+  await vi.waitFor(() => expect(pageText()).toContain("Check T3 Connect"));
   expect(pageText()).not.toContain("Your phone can reach this computer.");
 
   await share({ status: "reachable", checkedAt, readyConnections: 4, protocol: "quic" });
-  expect(pageText()).toContain("Your phone can reach this computer.");
+  await vi.waitFor(() => expect(pageText()).toContain("Your phone can reach this computer."));
   expect(pageText()).not.toContain("Check T3 Connect");
 });
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index d02827695e3d4..5deb65580b6f4 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -1,5 +1,5 @@
 import { useAuth } from "@clerk/react";
-import { useAtomValue } from "@effect/atom-react";
+import { useAtomSet, useAtomValue } from "@effect/atom-react";
 import type {
   AgentSessionProjectCandidate,
   EnvironmentId,
@@ -19,7 +19,6 @@ import {
   AuthOrchestrationOperateScope,
   isManagedDriverAllowed,
   isProviderAvailable,
-  managedCapabilityDenial,
   ProviderDriverKind,
   ThreadId,
 } from "@t3tools/contracts";
@@ -32,7 +31,7 @@ import {
   SmartphoneIcon,
   TerminalIcon,
 } from "lucide-react";
-import { useEffect, useRef, useState, type ReactNode } from "react";
+import { useEffect, useEffectEvent, useRef, useState, type ReactNode } from "react";
 
 import { TYPOGRAPHY_ADVANCED_STORAGE_KEY } from "../../appearanceFonts";
 import { isElectron } from "../../env";
@@ -57,10 +56,19 @@ import {
   resolveOnboardingProviderInstallCommand,
   resolveOnboardingProviderLoginCommand,
 } from "../../onboarding/providerReadiness.logic";
-import { groupWelcomeAgents, welcomeAgentState } from "../../onboarding/welcomeAgents.logic";
+import {
+  cliTerminalStep,
+  groupWelcomeAgents,
+  welcomeAgentState,
+  welcomePhonePath,
+} from "../../onboarding/welcomePage.logic";
+import {
+  type WelcomeImportSelection,
+  welcomeImportSelectionAtom,
+} from "../../onboarding/welcomeState";
 import { newProjectId, randomUUID } from "../../lib/utils";
 import { agentSessionImport } from "../../state/agentSessions";
-import { readProjects, waitForProject } from "../../state/entities";
+import { readProjects, useProjects, waitForProject } from "../../state/entities";
 import { useEnvironments, usePrimaryEnvironmentId } from "../../state/environments";
 import { managedTelemetryOffMessage, useManagedPolicy } from "../../state/managedPolicy";
 import { useProjectScans } from "../../onboarding/useProjectScans";
@@ -115,10 +123,14 @@ export function WelcomePage({
     environments.find((environment) => environment.environmentId === environmentId)?.label ??
     "this computer";
   const agentReady = useWelcomeAgents(environmentId).readyCount > 0;
-  // The phone links and pairs the primary computer, so it is offered only when setting that one up.
-  const isPrimary = usePrimaryEnvironmentId() === environmentId;
+  const phonePath = welcomePhonePath({
+    isPrimary: usePrimaryEnvironmentId() === environmentId,
+    cloud: hasCloudPublicConfig(),
+    policy: useManagedPolicy(environmentId),
+  });
   const scans = useProjectScans([environmentId]);
-  const [importSelection, setImportSelection] = useState<ImportSelection | null>(null);
+  const importSelection = useAtomValue(welcomeImportSelectionAtom(environmentId));
+  const setImportSelection = useAtomSet(welcomeImportSelectionAtom(environmentId));
   const [isImporting, setIsImporting] = useState(false);
   // True from Start until the landing; leaving earlier would drop the import or the landing.
   const holdPageRef = useRef(false);
@@ -159,6 +171,7 @@ export function WelcomePage({
         // Release before onDone so its own navigation is not blocked.
         holdPageRef.current = false;
         await onDone(projectRef);
+        setImportSelection(null);
         if (importWarning) {
           toastManager.add({
             type: "warning",
@@ -207,7 +220,12 @@ export function WelcomePage({
   });
   // Without import permission, starting simply skips the projects.
   const selected = projectImport.canWrite ? projectImport.selected : [];
-  const newCount = selected.filter((candidate) => !candidate.alreadyImported).length;
+  // The scan can be a little old, so a project added a moment ago is matched here too.
+  const projects = useProjects();
+  const newCount = selected.filter(
+    (candidate) =>
+      resolveOnboardingProjectId(projects, candidate.environmentId, candidate) === null,
+  ).length;
   const start = () => {
     if (selected.length > 0) void projectImport.runImport(selected);
     else projectImport.finishAfterImport();
@@ -241,7 +259,9 @@ export function WelcomePage({
               projectImport={projectImport}
               isImporting={isImporting}
             />
-            {isPrimary ? <PhoneSection environmentId={environmentId} /> : null}
+            {phonePath === null ? null : (
+              <PhoneSection environmentId={environmentId} path={phonePath} />
+            )}
             <div className="mt-8 flex flex-wrap items-center justify-between gap-3 border-t border-border/70 pt-6">
               {agentReady ? (
                 <span />
@@ -258,7 +278,7 @@ export function WelcomePage({
                   {isImporting
                     ? "Importing…"
                     : newCount > 0
-                      ? `Add ${newCount} ${newCount === 1 ? "project" : "projects"} and start`
+                      ? `Import ${newCount} ${newCount === 1 ? "project" : "projects"} and start`
                       : selected.length > 0
                         ? "Import threads and start"
                         : "Start"}
@@ -435,19 +455,16 @@ function AgentsSection({
     });
   };
 
-  // "Use existing CLI" opens the CLI's terminal once Codex has checked the CLI. Only the
-  // ChatGPT sign-in runtime reports `setup.canAuthenticate`, so its status is not the CLI's.
+  // "Use existing CLI" opens the CLI's terminal once Codex has checked the CLI.
   const cliProvider =
     cliTerminalFor === null
       ? undefined
       : providers?.find((provider) => provider.instanceId === cliTerminalFor);
-  if (
-    cliProvider !== undefined &&
-    cliProvider.setup?.canAuthenticate !== true &&
-    stateOf(cliProvider) !== "checking"
-  ) {
+  const cliStep =
+    cliProvider === undefined ? "done" : cliTerminalStep(cliProvider, serverConfig?.settings);
+  if (cliProvider !== undefined && cliStep !== "wait") {
     setCliTerminalFor(null);
-    if (needsInstallOrSignIn(cliProvider)) openTerminal(cliProvider);
+    if (cliStep === "open") openTerminal(cliProvider);
   }
 
   const turnOn = async (provider: ServerProvider) => {
@@ -550,7 +567,10 @@ function AgentsSection({
           ))}
         </div>
       ) : null}
-      {!canOperateTerminal && [...found, ...available].some(needsInstallOrSignIn) ? (
+      {!canOperateTerminal &&
+      [...found, ...available].some(
+        (provider) => needsInstallOrSignIn(provider) || codexNeedsSetup(provider),
+      ) ? (
         <p className="mt-2 text-sm text-muted-foreground">
           This connection cannot control terminals.
         </p>
@@ -611,7 +631,9 @@ function AgentsSection({
             environmentId={environmentId}
             provider={codexSetupProvider}
             serverConfig={serverConfig}
-            onUseCli={() => setCliTerminalFor(codexSetupProvider.instanceId)}
+            onUseCliChange={(useCli) =>
+              setCliTerminalFor(useCli ? codexSetupProvider.instanceId : null)
+            }
           />
         </div>
       ) : null}
@@ -719,19 +741,22 @@ function ProjectsSection({
 
   const allKeys = candidates.map((candidate) => candidate.key);
   const defaultKeys = recent.length > 0 ? recent.map((candidate) => candidate.key) : allKeys;
+  const isDefaultSelection =
+    selected.length === defaultKeys.length && defaultKeys.every((key) => selectedKeys.has(key));
   return (
     <WelcomeSection title="Projects" status={`From your ${IMPORT_SOURCES_LABEL} history`}>
       <div className="flex items-center gap-3 rounded-lg border border-border bg-background px-4 py-3">
         <label className="flex min-w-0 flex-1 items-center gap-3">
           <Checkbox
             checked={canWrite && selected.length > 0}
+            indeterminate={canWrite && selected.length > 0 && !isDefaultSelection}
             disabled={isImporting || !canWrite}
             onCheckedChange={(checked) => setSelectedKeys(new Set(checked ? defaultKeys : []))}
           />
           <span className="min-w-0 flex-1 text-sm text-foreground">
             {canWrite && selected.length > 0
-              ? `Bring in ${selected.length} ${selected.length === 1 ? "project" : "projects"} and their threads`
-              : "Bring in projects and their threads"}
+              ? `Import ${selected.length} ${selected.length === 1 ? "project" : "projects"} and their threads`
+              : "Import projects and their threads"}
           </span>
         </label>
         {canWrite ? (
@@ -794,13 +819,14 @@ function ProjectsSection({
   );
 }
 
-function PhoneSection({ environmentId }: { readonly environmentId: EnvironmentId }) {
+function PhoneSection({
+  environmentId,
+  path,
+}: {
+  readonly environmentId: EnvironmentId;
+  readonly path: "connect" | "pairing";
+}) {
   const [open, setOpen] = useState(false);
-  const policy = useManagedPolicy(environmentId);
-  // A policy that blocks other devices leaves the phone nothing to connect to.
-  if (managedCapabilityDenial(policy, "remoteClients") !== undefined) return null;
-  const connectAllowed =
-    hasCloudPublicConfig() && managedCapabilityDenial(policy, "connect") === undefined;
   return (
     <WelcomeSection title="Phone" status="Optional">
       <Collapsible open={open} onOpenChange={setOpen}>
@@ -837,7 +863,7 @@ function PhoneSection({ environmentId }: { readonly environmentId: EnvironmentId
               <span className="text-sm text-muted-foreground">Scan to get the app.</span>
             </div>
             <div className="flex flex-col justify-center gap-2 rounded-lg border border-border bg-background p-3.5">
-              {connectAllowed ? (
+              {path === "connect" ? (
                 <PhoneConnectLink environmentId={environmentId} />
               ) : (
                 <>
@@ -866,6 +892,13 @@ function PhoneConnectLink({ environmentId }: { readonly environmentId: Environme
   const { isLoaded, isSignedIn, userId } = useAuth({ treatPendingAsSignedOut: false });
   const { openAuthPrompt } = useT3ConnectAuthPrompt();
   const linkState = useCloudLinkState(environmentId);
+  const refreshLinkState = useEffectEvent(linkState.refresh);
+  // The server rechecks the tunnel every 30 s; read its latest result while this panel is open.
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- 30 s interval that refreshes the cloud link reachability while mounted
+  useEffect(() => {
+    const interval = window.setInterval(() => refreshLinkState(), 30_000);
+    return () => window.clearInterval(interval);
+  }, []);
   const link = linkState.data;
   // The phone reaches this computer through its tunnel; older servers leave that flag out.
   const shared =
@@ -937,12 +970,13 @@ function OnboardingCodexSetup({
   environmentId,
   provider,
   serverConfig,
-  onUseCli,
+  onUseCliChange,
 }: {
   readonly environmentId: EnvironmentId;
   readonly provider: ServerProvider;
   readonly serverConfig: ServerConfig;
-  readonly onUseCli: () => void;
+  // True asks for the CLI's install or sign-in terminal once Codex has checked the CLI.
+  readonly onUseCliChange: (useCli: boolean) => void;
 }) {
   const canManageProviders = useEnvironmentScope(environmentId, AuthProvidersManageScope);
   const persistProviderInstance = usePersistEnvironmentProviderInstanceMutation(environmentId);
@@ -956,8 +990,8 @@ function OnboardingCodexSetup({
   const mode = readCodexSetupMode(config);
   const changeMode = (setupMode: "managed" | "existing") => {
     // "Use existing CLI" also opens a terminal to install or sign in to the CLI.
-    if (setupMode === "existing") onUseCli();
-    const unchanged = "setupMode" in config && config.setupMode === setupMode;
+    onUseCliChange(setupMode === "existing");
+    const unchanged = mode === setupMode && provider.enabled;
     if (unchanged || !readEnvironmentScope(environmentId, AuthProvidersManageScope)) return;
     // One-instance upsert keeps a provider another client added in the meantime.
     void persistProviderInstance({
@@ -965,8 +999,11 @@ function OnboardingCodexSetup({
       instanceId,
       instance: { ...instance, enabled: true, config: { ...config, enabled: true, setupMode } },
     }).then((result) => {
-      if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
-        toastManager.add({ type: "error", title: "Could not save Codex setup" });
+      if (result._tag === "Failure") {
+        onUseCliChange(false);
+        if (!isAtomCommandInterrupted(result)) {
+          toastManager.add({ type: "error", title: "Could not save Codex setup" });
+        }
       }
     });
   };
@@ -1226,12 +1263,6 @@ function AgentInstallTerminal({
 
 const IMPORT_PERMISSION_MESSAGE = "This connection cannot import projects or thread history.";
 
-interface ImportSelection {
-  // Projects listed when the selection changed; projects found later get the defaults.
-  readonly knownKeys: ReadonlySet<string>;
-  readonly keys: ReadonlySet<string>;
-}
-
 // Creates the selected projects, then imports each one's agent history. Owns retry state so a
 // second Start resumes instead of recreating projects.
 function useProjectImport({
@@ -1244,8 +1275,8 @@ function useProjectImport({
   onDone,
 }: {
   readonly scans: ReturnType<typeof useProjectScans>;
-  readonly importSelection: ImportSelection | null;
-  readonly onImportSelectionChange: (next: ImportSelection) => void;
+  readonly importSelection: WelcomeImportSelection | null;
+  readonly onImportSelectionChange: (next: WelcomeImportSelection) => void;
   readonly isImporting: boolean;
   readonly setIsImporting: (value: boolean) => void;
   // Blocks leaving the page; onDone releases it before landing.
@@ -1315,11 +1346,16 @@ function useProjectImport({
       projectsWithImportedHistoryRef.current,
       importedProjectsRef.current,
     );
+    // Busy until setup is saved, so Start cannot run the import again meanwhile.
+    setIsImporting(true);
     if (projectRef === undefined) {
-      void onDone(undefined, importWarningRef.current, importedThreadCountRef.current);
+      void onDone(undefined, importWarningRef.current, importedThreadCountRef.current).then(
+        (completed) => {
+          if (!completed) setIsImporting(false);
+        },
+      );
       return;
     }
-    setIsImporting(true);
     holdPageRef.current = true;
     const importGeneration = importGenerationRef.current;
     // waitForProject gives up after its timeout, so a project that never reaches the client
diff --git a/apps/web/src/onboarding/welcomeAgents.logic.test.ts b/apps/web/src/onboarding/welcomePage.logic.test.ts
similarity index 67%
rename from apps/web/src/onboarding/welcomeAgents.logic.test.ts
rename to apps/web/src/onboarding/welcomePage.logic.test.ts
index 128cda4c41d92..b90ff8924ab61 100644
--- a/apps/web/src/onboarding/welcomeAgents.logic.test.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.test.ts
@@ -1,4 +1,5 @@
 import {
+  type ManagedPolicySummary,
   ProjectId,
   ProviderDriverKind,
   ProviderInstanceId,
@@ -7,7 +8,7 @@ import {
 } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
-import { groupWelcomeAgents } from "./welcomeAgents.logic";
+import { cliTerminalStep, groupWelcomeAgents, welcomePhonePath } from "./welcomePage.logic";
 
 function provider(name: string, overrides: Partial<ServerProvider> = {}): ServerProvider {
   return {
@@ -118,3 +119,43 @@ describe("groupWelcomeAgents", () => {
     });
   });
 });
+
+describe("cliTerminalStep", () => {
+  it("waits for the CLI's own check, then opens its terminal unless Codex is ready", () => {
+    const codex = (overrides: Partial<ServerProvider> = {}) => provider("Codex", overrides);
+    const step = (overrides?: Partial<ServerProvider>) =>
+      cliTerminalStep(codex(overrides), undefined);
+
+    // Still the ChatGPT sign-in runtime, before the switch to the CLI lands.
+    expect(
+      step({
+        setup: { canAuthenticate: true, canInstall: true },
+        auth: { status: "unauthenticated" },
+      }),
+    ).toBe("wait");
+    expect(step({ installed: false, status: "warning", auth: { status: "unknown" } })).toBe("wait");
+    expect(step({ installed: false, status: "error", auth: { status: "unknown" } })).toBe("open");
+    expect(step({ auth: { status: "unauthenticated" } })).toBe("open");
+    // A check that timed out still gets the sign-in command.
+    expect(step({ status: "error", auth: { status: "unknown" } })).toBe("open");
+    expect(step()).toBe("done");
+  });
+});
+
+describe("welcomePhonePath", () => {
+  it("offers T3 Connect or a pairing code only for the primary computer and only when allowed", () => {
+    const policy = (limits: ManagedPolicySummary["limits"]): ManagedPolicySummary => ({
+      organization: "Acme",
+      lockedSettings: [],
+      ...(limits === undefined ? {} : { limits }),
+    });
+    const path = (input: Partial<Parameters<typeof welcomePhonePath>[0]>) =>
+      welcomePhonePath({ isPrimary: true, cloud: true, policy: undefined, ...input });
+
+    expect(path({})).toBe("connect");
+    expect(path({ cloud: false })).toBe("pairing");
+    expect(path({ policy: policy({ connect: false }) })).toBe("pairing");
+    expect(path({ policy: policy({ clients: ["desktop"] }) })).toBeNull();
+    expect(path({ isPrimary: false })).toBeNull();
+  });
+});
diff --git a/apps/web/src/onboarding/welcomeAgents.logic.ts b/apps/web/src/onboarding/welcomePage.logic.ts
similarity index 67%
rename from apps/web/src/onboarding/welcomeAgents.logic.ts
rename to apps/web/src/onboarding/welcomePage.logic.ts
index a01ccddde918c..b339b087599ad 100644
--- a/apps/web/src/onboarding/welcomeAgents.logic.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.ts
@@ -1,5 +1,7 @@
 import {
   isProviderAvailable,
+  managedCapabilityDenial,
+  type ManagedPolicySummary,
   ProviderDriverKind,
   resolveProjectProviderInstanceEnabled,
   type ServerProvider,
@@ -65,3 +67,39 @@ export function groupWelcomeAgents(
   available.sort(byName);
   return { checking, readyCount, found: found.map((entry) => entry.provider), available };
 }
+
+/**
+ * What "Use existing CLI" does next for Codex: wait for the CLI's own check, open its terminal,
+ * or stop. Only the ChatGPT sign-in runtime reports `setup.canAuthenticate`.
+ */
+export function cliTerminalStep(
+  provider: ServerProvider,
+  settings: ComputerSettings | null | undefined,
+) {
+  if (provider.setup?.canAuthenticate === true) return "wait";
+  const state = welcomeAgentState(provider, settings);
+  if (state === "checking") return "wait";
+  // The terminal shows the command first, so it also helps a CLI whose check failed.
+  const fixable =
+    state === "install" ||
+    state === "signIn" ||
+    (state === "attention" && isProviderAvailable(provider));
+  return fixable ? "open" : "done";
+}
+
+/**
+ * How the Welcome page offers the phone: T3 Connect sign-in, a pairing code, or not at all.
+ * Both act on the primary computer, so another computer gets neither.
+ */
+export function welcomePhonePath(input: {
+  readonly isPrimary: boolean;
+  readonly cloud: boolean;
+  readonly policy: ManagedPolicySummary | undefined;
+}) {
+  if (!input.isPrimary || managedCapabilityDenial(input.policy, "remoteClients") !== undefined) {
+    return null;
+  }
+  return input.cloud && managedCapabilityDenial(input.policy, "connect") === undefined
+    ? "connect"
+    : "pairing";
+}
diff --git a/apps/web/src/onboarding/welcomeState.ts b/apps/web/src/onboarding/welcomeState.ts
new file mode 100644
index 0000000000000..87755339ea826
--- /dev/null
+++ b/apps/web/src/onboarding/welcomeState.ts
@@ -0,0 +1,19 @@
+import type { EnvironmentId } from "@t3tools/contracts";
+import { Atom } from "effect/reactivity";
+
+export interface WelcomeImportSelection {
+  // Projects listed when the selection changed; projects found later get the defaults.
+  readonly knownKeys: ReadonlySet<string>;
+  readonly keys: ReadonlySet<string>;
+}
+
+/**
+ * A computer's project choices on the Welcome page. They survive a visit to Settings during
+ * setup, and finishing setup clears them.
+ */
+export const welcomeImportSelectionAtom = Atom.family((environmentId: EnvironmentId) =>
+  Atom.make<WelcomeImportSelection | null>(null).pipe(
+    Atom.keepAlive,
+    Atom.withLabel(`welcome-import-selection:${environmentId}`),
+  ),
+);
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index feec09043c7ec..b1ffdaccb9173 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -167,12 +167,9 @@ function RootRouteBranch() {
   if (pathname === "/welcome") {
     return (
       <>
-        {/* The Welcome page can sign in to T3 Connect; this links the computer for the phone. */}
-        <ConnectOnboardingDialog />
+        <ActionDialogHosts />
         {/* Settings can reopen the page while threads run. */}
         {isElectron ? <RunningThreadKeepAlive /> : null}
-        <CustomSnoozeDialogHost />
-        <GuestShareDialogHost />
         <CommandPalette>
           <AppSidebarLayout>
             <Outlet />
@@ -206,16 +203,10 @@ function RootRouteBranch() {
           <DesktopWebLinkCoordinator />
         ) : null}
         {isElectron ? <RunningThreadKeepAlive /> : null}
-        <RelayClientInstallDialog />
-        <ConnectOnboardingDialog />
-        <SshPasswordPromptDialog />
+        <ActionDialogHosts />
         <SnapShotCoordinator />
         <ReopenClosedViewShortcut />
-        <ConfirmDialogHost />
-        <CustomSnoozeDialogHost />
-        <GuestShareDialogHost />
         <ProjectCloneToastCoordinator />
-        <AddProjectToMachineDialogHost />
         {import.meta.env.DEV && primaryEnvironmentAuthenticated ? <DevReplayHost /> : null}
         {primaryEnvironmentAuthenticated ? (
           <EventRouter skipInitialBootstrapNavigation={returningFromWelcome} />
@@ -228,6 +219,22 @@ function RootRouteBranch() {
   );
 }
 
+// Dialogs that the sidebar and pages open from anywhere, so both shells mount them. The Welcome
+// page's T3 Connect sign-in needs the Connect and relay client dialogs to share this computer.
+function ActionDialogHosts() {
+  return (
+    <>
+      <RelayClientInstallDialog />
+      <ConnectOnboardingDialog />
+      <SshPasswordPromptDialog />
+      <ConfirmDialogHost />
+      <CustomSnoozeDialogHost />
+      <GuestShareDialogHost />
+      <AddProjectToMachineDialogHost />
+    </>
+  );
+}
+
 function RootRouteErrorView({ error }: ErrorComponentProps) {
   const router = useRouter();
   const message = errorMessage(error);
diff --git a/apps/web/src/routes/welcome.tsx b/apps/web/src/routes/welcome.tsx
index 37f31ec11075d..03daff013ab7c 100644
--- a/apps/web/src/routes/welcome.tsx
+++ b/apps/web/src/routes/welcome.tsx
@@ -31,15 +31,16 @@ function WelcomeRouteView() {
   const primaryEnvironmentId = usePrimaryEnvironmentId();
   const { environments, isReady } = useEnvironments();
   // Trust the id only once the catalog has it; an unknown computer falls back to this one.
+  const waitingForCatalog = resumeEnvironmentId !== undefined && !isReady;
   const resumeKnown =
     resumeEnvironmentId !== undefined &&
-    (!isReady ||
-      environments.some((environment) => environment.environmentId === resumeEnvironmentId));
+    environments.some((environment) => environment.environmentId === resumeEnvironmentId);
   const environmentId = (resumeKnown ? resumeEnvironmentId : undefined) ?? primaryEnvironmentId;
   // The root can remount this pending outlet after navigation; do not reopen setup.
   const isWelcomeRoute = useLocation({ select: (location) => location.pathname === "/welcome" });
   const [dismissed, setDismissed] = useState(false);
   const openNewThread = useNewThreadHandler();
+  if (waitingForCatalog) return null;
   if (environmentId === null || !isWelcomeRoute || dismissed) return <NoProjectsHero />;
   return (
     <WelcomePage

From 50a2448458642cb2004a444cb7f05aaba1359663 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 19:57:26 -0800
Subject: [PATCH 07/22] fix(web): Welcome page keeps an import opt-out and the
 app's activation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Unchecking the main import box also leaves out projects a later scan finds,
  until it is checked again; picks in the list still give new ones the default.
- A failed rescan keeps the project controls and shows Retry beside them.
- A failed T3 Connect status read says so instead of asking to share again.
- /welcome mounts desktop activation (`t3 app`), the theme editor, and the
  ChatGPT welcome, so the page behaves like the app when reopened.
- Start reads "Starting…" when nothing is imported; dead import checks removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       | 53 ++++++++---
 .../src/components/onboarding/WelcomePage.tsx | 93 +++++++++++--------
 .../components/settings/SettingsPanels.tsx    |  2 +-
 apps/web/src/onboarding/welcomeState.ts       |  2 +
 apps/web/src/routes/__root.tsx                |  7 +-
 docs/user/welcome-page.md                     |  2 +-
 6 files changed, 101 insertions(+), 58 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index cf782ee1aecf6..1078663875855 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -41,6 +41,8 @@ const state = vi.hoisted(() => ({
   cloud: false,
   auth: { isLoaded: true, isSignedIn: false, userId: null as string | null },
   linkState: null as unknown,
+  linkError: null as string | null,
+  refreshLinkState: vi.fn(),
 }));
 
 vi.mock(import("@t3tools/client-runtime/state/session"), async (original) => {
@@ -71,7 +73,9 @@ vi.mock(import("../../cloud/cloudLinkState"), async (original) => {
     ...(await original()),
     useCloudLinkState: (() => ({
       data: useAtomValue(state.linkState as Atom.Atom<EnvironmentCloudLinkStateResult | null>),
+      error: state.linkError,
       isPending: false,
+      refresh: state.refreshLinkState,
     })) as never,
   };
 });
@@ -141,10 +145,6 @@ vi.mock(import("../../state/use-atom-command"), async (original) => ({
   useAtomCommand: ((command: "createProject" | "importThreads" | "refreshProviders") =>
     state[command]) as never,
 }));
-vi.mock(import("../settings/ChatGptWelcomeCoordinator"), async (original) => ({
-  ...(await original()),
-  ChatGptWelcomeCoordinator: () => <></>,
-}));
 
 import { welcomeImportSelectionAtom } from "../../onboarding/welcomeState";
 import { appAtomRegistry } from "../../rpc/atomRegistry";
@@ -310,6 +310,8 @@ function setup() {
   state.cloud = false;
   state.auth = { isLoaded: true, isSignedIn: false, userId: null };
   state.linkState = Atom.make<EnvironmentCloudLinkStateResult | null>(null).pipe(Atom.keepAlive);
+  state.linkError = null;
+  state.refreshLinkState.mockReset();
   appAtomRegistry.set(welcomeImportSelectionAtom(primaryId), null);
   return now;
 }
@@ -443,21 +445,27 @@ it("blocks leaving the page until the imported projects have landed", async () =
   expect(state.createProject).toHaveBeenCalledTimes(2);
 });
 
-it("selects projects that a later scan finds after the selection was changed", async () => {
+it("gives projects a later scan finds the default, unless the main box was unchecked", async () => {
   using _now = setup();
   await using _screen = await mountWelcome();
-  const bringIn = document.querySelector<HTMLElement>('[role="checkbox"]');
-  await act(async () => bringIn?.click());
-  await vi.waitFor(() => expect(button("Start").disabled).toBe(false));
-
   // Turning on another agent rescans and finds a recent project the user has not seen.
-  await act(async () =>
-    appAtomRegistry.set(candidatesAtom(), [
-      ...appAtomRegistry.get(candidatesAtom()),
-      candidate("/projects/third"),
-    ]),
-  );
+  const findProject = (path: string) =>
+    act(async () =>
+      appAtomRegistry.set(candidatesAtom(), [
+        ...appAtomRegistry.get(candidatesAtom()),
+        candidate(path),
+      ]),
+    );
+
+  await click("Review all 2");
+  await click("Select none");
+  await findProject("/projects/third");
   await vi.waitFor(() => expect(button("Import 1 project and start").disabled).toBe(false));
+
+  const importProjects = document.querySelector<HTMLElement>('[role="checkbox"]');
+  await act(async () => importProjects?.click());
+  await findProject("/projects/fourth");
+  await vi.waitFor(() => expect(button("Start").disabled).toBe(false));
 });
 
 it("keeps the project choice across a visit to Settings until setup finishes", async () => {
@@ -514,8 +522,23 @@ it("says the phone is set up only once this computer is shared with the signed-i
   using _now = setup();
   state.cloud = true;
   state.auth = { isLoaded: true, isSignedIn: true, userId: "user_1" };
+  state.linkError = "Could not read T3 Connect link state.";
   await using _screen = await mountWelcome();
   await click("Set up");
+  // A failed read says so instead of asking to share the computer again.
+  await vi.waitFor(() => expect(pageText()).toContain("Could not check T3 Connect."));
+  expect(pageText()).not.toContain("Set up T3 Connect");
+
+  state.linkError = null;
+  await act(async () =>
+    appAtomRegistry.set(state.linkState as Atom.Writable<EnvironmentCloudLinkStateResult | null>, {
+      linked: false,
+      cloudUserId: null,
+      relayUrl: null,
+      relayIssuer: null,
+      publishAgentActivity: false,
+    }),
+  );
   // Signed in, but "Not now" on the share step left this computer unreachable.
   await vi.waitFor(() => expect(pageText()).toContain("Set up T3 Connect"));
 
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index 5deb65580b6f4..a77a2400ccf84 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -84,7 +84,6 @@ import { useAtomCommand } from "../../state/use-atom-command";
 import { getProviderSummary } from "../settings/providerStatus";
 import { providerClients } from "../settings/providerDriverMeta";
 import { AddProviderInstanceDialog } from "../settings/AddProviderInstanceDialog";
-import { ChatGptWelcomeCoordinator } from "../settings/ChatGptWelcomeCoordinator";
 import { useDesktopCliCommand } from "../settings/CliCommandSettingsRow";
 import { CodexSetupSection } from "../settings/CodexSetupSection";
 import { readCodexSetupMode } from "../settings/CodexSetupSection.logic";
@@ -276,7 +275,9 @@ export function WelcomePage({
                 )}
                 <Button disabled={!agentReady || isImporting} onClick={start}>
                   {isImporting
-                    ? "Importing…"
+                    ? selected.length > 0
+                      ? "Importing…"
+                      : "Starting…"
                     : newCount > 0
                       ? `Import ${newCount} ${newCount === 1 ? "project" : "projects"} and start`
                       : selected.length > 0
@@ -289,7 +290,6 @@ export function WelcomePage({
           </div>
         </div>
       </div>
-      <ChatGptWelcomeCoordinator />
     </SidebarInset>
   );
 }
@@ -714,7 +714,12 @@ function ProjectsSection({
       </WelcomeSection>
     );
   }
-  if (scan.error !== null) {
+  const retry = (
+    <Button variant="ghost" size="sm" onClick={scan.refresh}>
+      Retry
+    </Button>
+  );
+  if (scan.error !== null && candidates.length === 0) {
     return (
       <WelcomeSection title="Projects">
         <div
@@ -722,9 +727,7 @@ function ProjectsSection({
           className="flex items-center justify-between gap-3 text-sm text-muted-foreground"
         >
           <span>Could not check projects. {scan.error}</span>
-          <Button variant="ghost" size="sm" onClick={scan.refresh}>
-            Retry
-          </Button>
+          {retry}
         </div>
       </WelcomeSection>
     );
@@ -741,17 +744,21 @@ function ProjectsSection({
 
   const allKeys = candidates.map((candidate) => candidate.key);
   const defaultKeys = recent.length > 0 ? recent.map((candidate) => candidate.key) : allKeys;
-  const isDefaultSelection =
-    selected.length === defaultKeys.length && defaultKeys.every((key) => selectedKeys.has(key));
+  const partial =
+    selected.length > 0 &&
+    selected.length < candidates.length &&
+    !(selected.length === defaultKeys.length && defaultKeys.every((key) => selectedKeys.has(key)));
   return (
     <WelcomeSection title="Projects" status={`From your ${IMPORT_SOURCES_LABEL} history`}>
       <div className="flex items-center gap-3 rounded-lg border border-border bg-background px-4 py-3">
         <label className="flex min-w-0 flex-1 items-center gap-3">
           <Checkbox
             checked={canWrite && selected.length > 0}
-            indeterminate={canWrite && selected.length > 0 && !isDefaultSelection}
+            indeterminate={canWrite && partial}
             disabled={isImporting || !canWrite}
-            onCheckedChange={(checked) => setSelectedKeys(new Set(checked ? defaultKeys : []))}
+            onCheckedChange={(checked) =>
+              setSelectedKeys(new Set(checked ? defaultKeys : []), { optedOut: !checked })
+            }
           />
           <span className="min-w-0 flex-1 text-sm text-foreground">
             {canWrite && selected.length > 0
@@ -812,6 +819,15 @@ function ProjectsSection({
           {SCAN_LIMIT_MESSAGE}
         </p>
       ) : null}
+      {scan.error !== null ? (
+        <div
+          role="alert"
+          className="mt-2 flex items-center justify-between gap-3 text-sm text-muted-foreground"
+        >
+          <span>Could not check projects again. {scan.error}</span>
+          {retry}
+        </div>
+      ) : null}
       {visibleImportError ? (
         <p className="mt-2 text-sm text-destructive">{visibleImportError}</p>
       ) : null}
@@ -912,6 +928,21 @@ function PhoneConnectLink({ environmentId }: { readonly environmentId: Environme
   if (isSignedIn && link === null && linkState.isPending) {
     return <span className="text-sm text-muted-foreground">Checking T3 Connect…</span>;
   }
+  if (isSignedIn && linkState.error !== null) {
+    return (
+      <>
+        <span className="text-sm text-muted-foreground">Could not check T3 Connect.</span>
+        <Button
+          variant="outline"
+          size="sm"
+          className="self-start"
+          render={<Link to="/settings/access" />}
+        >
+          Check T3 Connect
+        </Button>
+      </>
+    );
+  }
   if (isSignedIn && reachability === "reachable") {
     return (
       <span className="inline-flex items-center gap-1.5 text-sm text-foreground">
@@ -1318,16 +1349,19 @@ function useProjectImport({
     ),
   );
   const recentKeys = new Set(recent.map((candidate) => candidate.key));
-  const selected = candidates.filter((candidate) =>
-    importSelection?.knownKeys.has(candidate.key)
-      ? importSelection.keys.has(candidate.key)
-      : recentKeys.has(candidate.key),
-  );
+  const selected = importSelection?.optedOut
+    ? []
+    : candidates.filter((candidate) =>
+        importSelection?.knownKeys.has(candidate.key)
+          ? importSelection.keys.has(candidate.key)
+          : recentKeys.has(candidate.key),
+      );
   const selectedKeys = new Set(selected.map((candidate) => candidate.key));
-  const setSelectedKeys = (keys: ReadonlySet<string>) =>
+  const setSelectedKeys = (keys: ReadonlySet<string>, { optedOut = false } = {}) =>
     onImportSelectionChange({
       knownKeys: new Set(candidates.map((candidate) => candidate.key)),
       keys,
+      optedOut,
     });
 
   const canImport = selected.every((candidate) =>
@@ -1393,10 +1427,6 @@ function useProjectImport({
       stopForDeniedAccess();
       return;
     }
-    if (selection.length === 0) {
-      void onDone();
-      return;
-    }
     setIsImporting(true);
     importWarningRef.current = "";
     importedThreadCountRef.current = 0;
@@ -1415,12 +1445,7 @@ function useProjectImport({
     const importEach = async () => {
       for (const candidate of selection) {
         const { environmentId } = candidate;
-        if (
-          importGeneration !== importGenerationRef.current ||
-          importedProjects !== importedProjectsRef.current
-        ) {
-          return false;
-        }
+        if (importGeneration !== importGenerationRef.current) return false;
         if (!hasAccess()) {
           stopForDeniedAccess();
           return false;
@@ -1449,12 +1474,7 @@ function useProjectImport({
               defaultModelSelection: null,
             },
           });
-          if (
-            importGeneration !== importGenerationRef.current ||
-            importedProjects !== importedProjectsRef.current
-          ) {
-            return false;
-          }
+          if (importGeneration !== importGenerationRef.current) return false;
           if (result._tag !== "Success") {
             if (!isAtomCommandInterrupted(result)) {
               projectAttempts.delete(candidate.key);
@@ -1472,12 +1492,7 @@ function useProjectImport({
           environmentId,
           input: { projectId, expectedWorkspaceRoot: candidate.path },
         });
-        if (
-          importGeneration !== importGenerationRef.current ||
-          importedProjects !== importedProjectsRef.current
-        ) {
-          return false;
-        }
+        if (importGeneration !== importGenerationRef.current) return false;
         if (threadImportResult._tag === "Success") {
           importedThreadCount += threadImportResult.value.importedCount;
           skippedThreadCount += threadImportResult.value.skippedCount;
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 9cceaa019dd1a..00bdcf6cf57b6 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -2094,7 +2094,7 @@ export function AboutSettingsPanel() {
         {primaryEnvironmentId === null ? null : (
           <SettingsRow
             {...searchableSetting("welcome-page")}
-            description="See your agents, bring in projects, and set up your phone."
+            description="See your agents, import projects, and set up your phone."
             control={
               <Button size="sm" variant="outline" render={<Link to="/welcome" />}>
                 Open
diff --git a/apps/web/src/onboarding/welcomeState.ts b/apps/web/src/onboarding/welcomeState.ts
index 87755339ea826..8443e74b1552e 100644
--- a/apps/web/src/onboarding/welcomeState.ts
+++ b/apps/web/src/onboarding/welcomeState.ts
@@ -5,6 +5,8 @@ export interface WelcomeImportSelection {
   // Projects listed when the selection changed; projects found later get the defaults.
   readonly knownKeys: ReadonlySet<string>;
   readonly keys: ReadonlySet<string>;
+  // Unchecking the main box also leaves out projects found later, until it is checked again.
+  readonly optedOut: boolean;
 }
 
 /**
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index b1ffdaccb9173..16097eac4675f 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -165,16 +165,19 @@ function RootRouteBranch() {
   }
 
   if (pathname === "/welcome") {
+    // Settings can reopen the page mid-session, so it keeps the app's activation and threads.
     return (
       <>
-        <ActionDialogHosts />
-        {/* Settings can reopen the page while threads run. */}
+        <ChatGptWelcomeCoordinator />
+        {primaryEnvironmentAuthenticated ? <DesktopAppActivationCoordinator /> : null}
         {isElectron ? <RunningThreadKeepAlive /> : null}
+        <ActionDialogHosts />
         <CommandPalette>
           <AppSidebarLayout>
             <Outlet />
           </AppSidebarLayout>
         </CommandPalette>
+        <ThemeEditorHost />
       </>
     );
   }
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index e49a1ba85730a..1eef27b360aef 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -46,7 +46,7 @@ provider instance. Sensitive values remain redacted in Settings and
 terminal metadata while the terminal process can use them.
 
 **Start** waits for one ready agent. Select **Start without an agent** to finish
-without one.
+without one. Checked projects are still imported.
 
 ## Phone
 

From ec1f50c0e90de1ae6703696787a07a47ac640154 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 20:20:11 -0800
Subject: [PATCH 08/22] fix(web): Welcome page stores project choices and
 shares the app's hosts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Project choices are stored per computer until setup finishes, so an app
  restart during phone setup keeps an import opt-out.
- Projects already in T3 Code are not checked again when the page reopens.
- A CLI whose version the server marks broken needs attention, not Ready.
- /welcome mounts the same hosts as the app (desktop links included); the theme
  editor and ChatGPT welcome sit above both shells, so drafts survive.
- The status line shows "Checking…" while checks run, the fold settles once an
  agent is found, and a failed Turn on shows the server's reason.
- Removed a dead import error state; docs name both fold labels.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       |  40 ++++++-
 .../src/components/onboarding/WelcomePage.tsx |  74 ++++++++-----
 .../src/onboarding/welcomePage.logic.test.ts  |  11 +-
 apps/web/src/onboarding/welcomePage.logic.ts  |   6 +-
 apps/web/src/onboarding/welcomeState.ts       |  31 +++---
 apps/web/src/routes/__root.tsx                | 103 ++++++++----------
 docs/user/welcome-page.md                     |  10 +-
 7 files changed, 163 insertions(+), 112 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index 1078663875855..cb19b300eb353 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -43,6 +43,7 @@ const state = vi.hoisted(() => ({
   linkState: null as unknown,
   linkError: null as string | null,
   refreshLinkState: vi.fn(),
+  scanError: null as string | null,
 }));
 
 vi.mock(import("@t3tools/client-runtime/state/session"), async (original) => {
@@ -133,7 +134,7 @@ vi.mock(import("../../onboarding/useProjectScans"), async (original) => {
           environmentId,
           data: { candidates, truncated: false } as never,
           isPending: false,
-          error: null,
+          error: state.scanError,
           refresh: state.refreshScan,
         };
       });
@@ -146,7 +147,7 @@ vi.mock(import("../../state/use-atom-command"), async (original) => ({
     state[command]) as never,
 }));
 
-import { welcomeImportSelectionAtom } from "../../onboarding/welcomeState";
+import { welcomeImportSelectionKey } from "../../onboarding/welcomeState";
 import { appAtomRegistry } from "../../rpc/atomRegistry";
 import { WelcomePage } from "./WelcomePage";
 
@@ -201,7 +202,10 @@ function setGrant(environmentId: EnvironmentId, allowed: boolean) {
 // Default selection only picks recently active projects, so pin "now".
 const NOW = Date.parse("2026-01-01T00:00:00.000Z");
 
-function candidate(path: string): AgentSessionProjectCandidate {
+function candidate(
+  path: string,
+  overrides: Partial<AgentSessionProjectCandidate> = {},
+): AgentSessionProjectCandidate {
   return {
     path,
     title: path.split("/").at(-1)!,
@@ -209,6 +213,7 @@ function candidate(path: string): AgentSessionProjectCandidate {
     threadCount: 10,
     lastActiveAt: new Date(NOW - 60_000).toISOString(),
     alreadyImported: false,
+    ...overrides,
   };
 }
 
@@ -312,7 +317,8 @@ function setup() {
   state.linkState = Atom.make<EnvironmentCloudLinkStateResult | null>(null).pipe(Atom.keepAlive);
   state.linkError = null;
   state.refreshLinkState.mockReset();
-  appAtomRegistry.set(welcomeImportSelectionAtom(primaryId), null);
+  state.scanError = null;
+  localStorage.removeItem(welcomeImportSelectionKey(primaryId));
   return now;
 }
 
@@ -507,6 +513,32 @@ it("stays busy while setup saves after an import with nothing to open", async ()
   expect(state.createProject).toHaveBeenCalledOnce();
 });
 
+it("leaves projects already in T3 Code out of the default import", async () => {
+  using _now = setup();
+  const existing = ProjectId.make("existing");
+  appAtomRegistry.set(projectsAtom(), [
+    { id: existing, environmentId: primaryId, workspaceRoot: "/projects/first" },
+  ]);
+  appAtomRegistry.set(candidatesAtom(), [
+    candidate("/projects/first", { alreadyImported: true, projectId: existing }),
+    candidate("/projects/second"),
+  ]);
+  await using _screen = await mountWelcome();
+  await vi.waitFor(() => expect(pageText()).toContain("Import 1 project and their threads"));
+});
+
+it("keeps the project controls when a later scan fails", async () => {
+  using _now = setup();
+  await using _screen = await mountWelcome();
+  state.scanError = "The scan timed out.";
+  await act(async () =>
+    appAtomRegistry.set(candidatesAtom(), [...appAtomRegistry.get(candidatesAtom())]),
+  );
+  await vi.waitFor(() => expect(pageText()).toContain("Could not check projects again."));
+  expect(button("Import 2 projects and start").disabled).toBe(false);
+  expect(button("Retry").disabled).toBe(false);
+});
+
 it("starts without importing when this connection cannot import projects", async () => {
   using _now = setup();
   setGrant(primaryId, false);
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index a77a2400ccf84..952e18b96099f 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -1,5 +1,5 @@
 import { useAuth } from "@clerk/react";
-import { useAtomSet, useAtomValue } from "@effect/atom-react";
+import { useAtomValue } from "@effect/atom-react";
 import type {
   AgentSessionProjectCandidate,
   EnvironmentId,
@@ -10,7 +10,10 @@ import type {
   ServerProvider,
 } from "@t3tools/contracts";
 import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime/environment";
-import { isAtomCommandInterrupted } from "@t3tools/client-runtime/state/runtime";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
 import {
   AgentSessionSource,
   AuthProvidersManageScope,
@@ -63,8 +66,9 @@ import {
   welcomePhonePath,
 } from "../../onboarding/welcomePage.logic";
 import {
+  StoredWelcomeImportSelection,
   type WelcomeImportSelection,
-  welcomeImportSelectionAtom,
+  welcomeImportSelectionKey,
 } from "../../onboarding/welcomeState";
 import { newProjectId, randomUUID } from "../../lib/utils";
 import { agentSessionImport } from "../../state/agentSessions";
@@ -128,8 +132,11 @@ export function WelcomePage({
     policy: useManagedPolicy(environmentId),
   });
   const scans = useProjectScans([environmentId]);
-  const importSelection = useAtomValue(welcomeImportSelectionAtom(environmentId));
-  const setImportSelection = useAtomSet(welcomeImportSelectionAtom(environmentId));
+  const [importSelection, setImportSelection] = useLocalStorage(
+    welcomeImportSelectionKey(environmentId),
+    null,
+    StoredWelcomeImportSelection,
+  );
   const [isImporting, setIsImporting] = useState(false);
   // True from Start until the landing; leaving earlier would drop the import or the landing.
   const holdPageRef = useRef(false);
@@ -406,8 +413,8 @@ function AgentsSection({
     void refreshProviders({ environmentId, input: {} });
   }, [environmentId, refreshProviders]);
 
-  // Decided once the first check ends: with nothing on this computer, adding an agent is the task.
-  if (moreOpen === null && !checking) setMoreOpen(found.length === 0);
+  // Decided once, when an agent is found or every check ends: with nothing found, adding one is the task.
+  if (moreOpen === null && (found.length > 0 || !checking)) setMoreOpen(found.length === 0);
   const showMore = moreOpen === true;
   const acpAllowed = isManagedDriverAllowed(serverConfig?.managedPolicy, ACP_REGISTRY_DRIVER_KIND);
   const stateOf = (provider: ServerProvider) => welcomeAgentState(provider, serverConfig?.settings);
@@ -479,7 +486,12 @@ function AgentsSection({
     });
     if (result._tag === "Failure") {
       if (!isAtomCommandInterrupted(result)) {
-        toastManager.add({ type: "error", title: `Could not turn on ${agentName(provider)}` });
+        const cause = squashAtomCommandFailure(result);
+        toastManager.add({
+          type: "error",
+          title: `Could not turn on ${agentName(provider)}`,
+          ...(cause instanceof Error ? { description: cause.message } : {}),
+        });
       }
       return;
     }
@@ -548,10 +560,10 @@ function AgentsSection({
     <WelcomeSection
       title="Agents"
       status={
-        checking && found.length === 0
-          ? `Checking ${label}…`
-          : readyCount > 0
-            ? `${readyCount} ready on ${label}`
+        readyCount > 0
+          ? `${readyCount} ready on ${label}`
+          : checking
+            ? `Checking ${label}…`
             : `None ready on ${label} yet`
       }
     >
@@ -743,7 +755,9 @@ function ProjectsSection({
   }
 
   const allKeys = candidates.map((candidate) => candidate.key);
-  const defaultKeys = recent.length > 0 ? recent.map((candidate) => candidate.key) : allKeys;
+  const defaultKeys = (
+    recent.length > 0 ? recent : candidates.filter((candidate) => !candidate.alreadyImported)
+  ).map((candidate) => candidate.key);
   const partial =
     selected.length > 0 &&
     selected.length < candidates.length &&
@@ -1092,6 +1106,9 @@ function AgentCard({
         ? null
         : state === "attention"
           ? (provider.unavailableReason ??
+            (provider.compatibilityAdvisory?.status === "broken"
+              ? provider.compatibilityAdvisory.message
+              : null) ??
             provider.message ??
             getProviderSummary(provider).headline)
           : getProviderSummary(provider).headline;
@@ -1339,7 +1356,7 @@ function useProjectImport({
     };
   }, []);
 
-  const { available: candidates, recent } = partitionOnboardingProjects(
+  const { available: candidates, recent: recentActive } = partitionOnboardingProjects(
     scans.flatMap((scan) =>
       (scan.data?.candidates ?? []).map((candidate) => ({
         ...candidate,
@@ -1348,31 +1365,32 @@ function useProjectImport({
       })),
     ),
   );
+  // Projects already in T3 Code stay in the list, but reopening the page does not import their
+  // history again unless the user picks them.
+  const recent = recentActive.filter((candidate) => !candidate.alreadyImported);
   const recentKeys = new Set(recent.map((candidate) => candidate.key));
+  const knownKeys = new Set(importSelection?.knownKeys);
+  const pickedKeys = new Set(importSelection?.keys);
   const selected = importSelection?.optedOut
     ? []
     : candidates.filter((candidate) =>
-        importSelection?.knownKeys.has(candidate.key)
-          ? importSelection.keys.has(candidate.key)
+        knownKeys.has(candidate.key)
+          ? pickedKeys.has(candidate.key)
           : recentKeys.has(candidate.key),
       );
   const selectedKeys = new Set(selected.map((candidate) => candidate.key));
   const setSelectedKeys = (keys: ReadonlySet<string>, { optedOut = false } = {}) =>
     onImportSelectionChange({
-      knownKeys: new Set(candidates.map((candidate) => candidate.key)),
-      keys,
+      knownKeys: candidates.map((candidate) => candidate.key),
+      keys: [...keys],
       optedOut,
     });
 
+  const canWrite = scans.every((scan) => writableEnvironments.has(scan.environmentId));
   const canImport = selected.every((candidate) =>
     writableEnvironments.has(candidate.environmentId),
   );
-  const [importError, setImportError] = useState("");
-  const visibleImportError = !canImport
-    ? IMPORT_PERMISSION_MESSAGE
-    : importError === IMPORT_PERMISSION_MESSAGE
-      ? ""
-      : importError;
+  const visibleImportError = canWrite && canImport ? "" : IMPORT_PERMISSION_MESSAGE;
 
   const finishAfterImport = () => {
     const projectRef = resolveOnboardingLandingProject(
@@ -1419,10 +1437,8 @@ function useProjectImport({
       selection.every((candidate) =>
         readEnvironmentScope(candidate.environmentId, AuthOrchestrationOperateScope),
       );
-    const stopForDeniedAccess = () => {
-      setIsImporting(false);
-      setImportError(IMPORT_PERMISSION_MESSAGE);
-    };
+    // The permission message shows from the session's scopes.
+    const stopForDeniedAccess = () => setIsImporting(false);
     if (!hasAccess()) {
       stopForDeniedAccess();
       return;
@@ -1538,7 +1554,7 @@ function useProjectImport({
   };
 
   return {
-    canWrite: scans.every((scan) => writableEnvironments.has(scan.environmentId)),
+    canWrite,
     candidates,
     recent,
     selected,
diff --git a/apps/web/src/onboarding/welcomePage.logic.test.ts b/apps/web/src/onboarding/welcomePage.logic.test.ts
index b90ff8924ab61..b1f835072ebe2 100644
--- a/apps/web/src/onboarding/welcomePage.logic.test.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.test.ts
@@ -79,6 +79,15 @@ describe("groupWelcomeAgents", () => {
           availability: "unavailable",
           unavailableReason: "Invalid config for instance 'broken'.",
         }),
+        // Signed in and healthy, but the server knows this CLI version is broken.
+        provider("Codex", {
+          compatibilityAdvisory: {
+            status: "broken",
+            message: "Update Codex to 0.170 or later.",
+            recommendedVersion: "0.170.0",
+            recommendedRange: null,
+          },
+        }),
         // An ACP agent that is not prepared looks like one still being checked.
         provider("Registry", {
           driver: acpRegistry,
@@ -92,7 +101,7 @@ describe("groupWelcomeAgents", () => {
       allowAll,
     );
 
-    expect(names(groups.found)).toEqual(["Broken", "Registry"]);
+    expect(names(groups.found)).toEqual(["Broken", "Codex", "Registry"]);
     expect(names(groups.available)).toEqual(["Pi"]);
     expect(groups.readyCount).toBe(0);
     expect(groups.checking).toBe(false);
diff --git a/apps/web/src/onboarding/welcomePage.logic.ts b/apps/web/src/onboarding/welcomePage.logic.ts
index b339b087599ad..acfc7a4400fe8 100644
--- a/apps/web/src/onboarding/welcomePage.logic.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.ts
@@ -22,7 +22,8 @@ const ACP_REGISTRY_DRIVER = ProviderDriverKind.make("acpRegistry");
 
 /**
  * An agent's state for new threads on this computer. The server also lists agents that only some
- * projects turn on, and lists an agent it could not load as off, which Turn on cannot fix.
+ * projects turn on, lists an agent it could not load as off, which Turn on cannot fix, and can pass
+ * a CLI whose version it knows is broken.
  */
 export function welcomeAgentState(
   provider: ServerProvider,
@@ -33,6 +34,7 @@ export function welcomeAgentState(
     return "disabled";
   }
   const state = getOnboardingProviderState(provider);
+  if (state === "ready" && provider.compatibilityAdvisory?.status === "broken") return "attention";
   // An ACP agent that is not prepared reports the same fields as one still being checked.
   return state === "checking" && provider.driver === ACP_REGISTRY_DRIVER ? "attention" : state;
 }
@@ -40,7 +42,7 @@ export function welcomeAgentState(
 /**
  * Splits a computer's allowed providers into agents already on it and agents the user can add.
  * Order inside each group is by state, then by the name the user sees. Agents still being
- * checked stay visible with the ones to add, so a slow check never hides an agent.
+ * checked are listed with the ones to add, so a slow check never drops an agent.
  */
 export function groupWelcomeAgents(
   providers: ReadonlyArray<ServerProvider> | null | undefined,
diff --git a/apps/web/src/onboarding/welcomeState.ts b/apps/web/src/onboarding/welcomeState.ts
index 8443e74b1552e..e418cc361491c 100644
--- a/apps/web/src/onboarding/welcomeState.ts
+++ b/apps/web/src/onboarding/welcomeState.ts
@@ -1,21 +1,20 @@
 import type { EnvironmentId } from "@t3tools/contracts";
-import { Atom } from "effect/reactivity";
+import * as Schema from "effect/Schema";
 
-export interface WelcomeImportSelection {
+/**
+ * A computer's project choices on the Welcome page. They are stored until setup finishes, so a
+ * visit to Settings or an app restart during setup keeps them.
+ */
+export const WelcomeImportSelection = Schema.Struct({
   // Projects listed when the selection changed; projects found later get the defaults.
-  readonly knownKeys: ReadonlySet<string>;
-  readonly keys: ReadonlySet<string>;
+  knownKeys: Schema.Array(Schema.String),
+  keys: Schema.Array(Schema.String),
   // Unchecking the main box also leaves out projects found later, until it is checked again.
-  readonly optedOut: boolean;
-}
+  optedOut: Schema.Boolean,
+});
+export type WelcomeImportSelection = typeof WelcomeImportSelection.Type;
 
-/**
- * A computer's project choices on the Welcome page. They survive a visit to Settings during
- * setup, and finishing setup clears them.
- */
-export const welcomeImportSelectionAtom = Atom.family((environmentId: EnvironmentId) =>
-  Atom.make<WelcomeImportSelection | null>(null).pipe(
-    Atom.keepAlive,
-    Atom.withLabel(`welcome-import-selection:${environmentId}`),
-  ),
-);
+export const StoredWelcomeImportSelection = Schema.NullOr(WelcomeImportSelection);
+
+export const welcomeImportSelectionKey = (environmentId: EnvironmentId) =>
+  `t3code:welcome-import-selection:${environmentId}`;
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 16097eac4675f..1b94d8a322298 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -164,28 +164,37 @@ function RootRouteBranch() {
     return hostedPromptLinkLanding;
   }
 
-  if (pathname === "/welcome") {
-    // Settings can reopen the page mid-session, so it keeps the app's activation and threads.
-    return (
-      <>
-        <ChatGptWelcomeCoordinator />
-        {primaryEnvironmentAuthenticated ? <DesktopAppActivationCoordinator /> : null}
-        {isElectron ? <RunningThreadKeepAlive /> : null}
-        <ActionDialogHosts />
-        <CommandPalette>
-          <AppSidebarLayout>
-            <Outlet />
-          </AppSidebarLayout>
-        </CommandPalette>
-        <ThemeEditorHost />
-      </>
-    );
-  }
-
-  if (authGateState.status !== "authenticated" && authGateState.status !== "hosted-static") {
+  const isWelcome = pathname === "/welcome";
+  if (
+    !isWelcome &&
+    authGateState.status !== "authenticated" &&
+    authGateState.status !== "hosted-static"
+  ) {
     return <Outlet />;
   }
 
+  // Settings can reopen /welcome mid-session, so it mounts everything the app does except the
+  // first-run gate and the event router, whose first navigation would leave the page.
+  const appHosts = (
+    <>
+      {primaryEnvironmentAuthenticated ? <DesktopAppActivationCoordinator /> : null}
+      {primaryEnvironmentAuthenticated || localEnvironmentDisabled ? (
+        <DesktopWebLinkCoordinator />
+      ) : null}
+      {isElectron ? <RunningThreadKeepAlive /> : null}
+      <RelayClientInstallDialog />
+      <ConnectOnboardingDialog />
+      <SshPasswordPromptDialog />
+      <SnapShotCoordinator />
+      <ReopenClosedViewShortcut />
+      <ConfirmDialogHost />
+      <CustomSnoozeDialogHost />
+      <GuestShareDialogHost />
+      <ProjectCloneToastCoordinator />
+      <AddProjectToMachineDialogHost />
+      {import.meta.env.DEV && primaryEnvironmentAuthenticated ? <DevReplayHost /> : null}
+    </>
+  );
   const appShell = (
     <CommandPalette>
       <AppSidebarLayout>
@@ -197,43 +206,25 @@ function RootRouteBranch() {
   return (
     <>
       <ChatGptWelcomeCoordinator />
-      <FirstRunGate
-        enabled={primaryEnvironmentAuthenticated}
-        hostedStatic={authGateState.status === "hosted-static"}
-      >
-        {primaryEnvironmentAuthenticated ? <DesktopAppActivationCoordinator /> : null}
-        {primaryEnvironmentAuthenticated || localEnvironmentDisabled ? (
-          <DesktopWebLinkCoordinator />
-        ) : null}
-        {isElectron ? <RunningThreadKeepAlive /> : null}
-        <ActionDialogHosts />
-        <SnapShotCoordinator />
-        <ReopenClosedViewShortcut />
-        <ProjectCloneToastCoordinator />
-        {import.meta.env.DEV && primaryEnvironmentAuthenticated ? <DevReplayHost /> : null}
-        {primaryEnvironmentAuthenticated ? (
-          <EventRouter skipInitialBootstrapNavigation={returningFromWelcome} />
-        ) : null}
-        {appShell}
-        {/* Keep the theme editor above the router so drafts survive navigation. */}
-        <ThemeEditorHost />
-      </FirstRunGate>
-    </>
-  );
-}
-
-// Dialogs that the sidebar and pages open from anywhere, so both shells mount them. The Welcome
-// page's T3 Connect sign-in needs the Connect and relay client dialogs to share this computer.
-function ActionDialogHosts() {
-  return (
-    <>
-      <RelayClientInstallDialog />
-      <ConnectOnboardingDialog />
-      <SshPasswordPromptDialog />
-      <ConfirmDialogHost />
-      <CustomSnoozeDialogHost />
-      <GuestShareDialogHost />
-      <AddProjectToMachineDialogHost />
+      {isWelcome ? (
+        <>
+          {appHosts}
+          {appShell}
+        </>
+      ) : (
+        <FirstRunGate
+          enabled={primaryEnvironmentAuthenticated}
+          hostedStatic={authGateState.status === "hosted-static"}
+        >
+          {appHosts}
+          {primaryEnvironmentAuthenticated ? (
+            <EventRouter skipInitialBootstrapNavigation={returningFromWelcome} />
+          ) : null}
+          {appShell}
+        </FirstRunGate>
+      )}
+      {/* Above both shells and the router, so drafts survive navigation, including to /welcome. */}
+      <ThemeEditorHost />
     </>
   );
 }
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 1eef27b360aef..9b67469891a66 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -23,8 +23,8 @@ unreadable settings with defaults.
 ## Agents
 
 T3 Code lists the agents it found on the computer first, ready ones on top.
-**Add more agents** lists every other agent T3 Code supports, A to Z, and opens by
-itself when no agent is found:
+**Add more agents** lists every other agent T3 Code supports, A to Z. When no agent
+is found, it reads **Set up an agent** and opens by itself:
 
 - **Turn on** enables an agent that is off on this computer, including one only
   some projects use. T3 Code then checks whether it is installed and signed in.
@@ -66,7 +66,8 @@ group shows the repository as `owner/name`. Clones with the same remote share
 one group. Directories that are not git repositories sit under "Other folders".
 
 The page offers git repositories active within the last 30 days with at least
-three conversations, already checked. Uncheck the row to start without them, or
+three conversations, already checked. Projects already in T3 Code are not checked
+again. Uncheck the box to start without them, or
 select **Review all** to pick from everything found, with "Select all" and
 "Select none". Linked worktrees of bare repositories
 can be offered as separate projects. Other linked git worktrees, Codex scratch
@@ -78,7 +79,8 @@ projects it found and warns when projects or conversations may be missing.
 
 Imported projects include Claude, Codex and Pi conversations active within the last
 30 days. You can continue those conversations in T3 Code. Pi is off by default:
-select **Turn on** next to Pi, and the page looks for its sessions too. Pi sessions
+open **Add more agents** and select **Turn on** next to Pi, and the page looks for
+its sessions too. Pi sessions
 are read from each enabled Pi provider's session directory, which follows
 `PI_CODING_AGENT_SESSION_DIR` and `PI_CODING_AGENT_DIR` in its environment. A
 Pi conversation imports its active branch, the one Pi reopens.

From af6a330820f7ab9e9506883e93db0efabc57d802 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 20:39:22 -0800
Subject: [PATCH 09/22] fix(web): Welcome page resumes a quit import and names
 each agent instance

- Start stores the chosen projects, so after a quit mid-import a reopened page
  keeps them checked even though they now exist.
- The live project list decides which projects are new, so a cached scan does
  not offer a just-imported project again; with nothing new, checking the box
  picks every listed project.
- The Codex setup card closes once Codex is signed in, and "Use existing CLI"
  stops for a broken CLI version, whose row offers the update.
- T3 Connect setup is offered only with relay access; otherwise pairing.
- Agents use the model picker's instance names; a failed Codex save shows the
  server's reason; a cold /welcome visit waits for the computer list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       | 47 ++++++++++++-
 .../src/components/onboarding/WelcomePage.tsx | 66 ++++++++++++-------
 .../src/onboarding/welcomePage.logic.test.ts  | 20 +++++-
 apps/web/src/onboarding/welcomePage.logic.ts  |  8 ++-
 apps/web/src/routes/__root.tsx                |  6 +-
 apps/web/src/routes/welcome.tsx               |  3 +-
 docs/user/welcome-page.md                     |  6 +-
 7 files changed, 119 insertions(+), 37 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index cb19b300eb353..df7fa28d46c68 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -2,6 +2,8 @@ import { RegistryContext } from "@effect/atom-react";
 import {
   AuthOrchestrationOperateScope,
   AuthOrchestrationReadScope,
+  AuthRelayReadScope,
+  AuthRelayWriteScope,
   EnvironmentId,
   ProjectId,
   ProviderDriverKind,
@@ -513,18 +515,53 @@ it("stays busy while setup saves after an import with nothing to open", async ()
   expect(state.createProject).toHaveBeenCalledOnce();
 });
 
-it("leaves projects already in T3 Code out of the default import", async () => {
+it("leaves projects already in T3 Code out of the default import, unless the box is checked", async () => {
   using _now = setup();
   const existing = ProjectId.make("existing");
+  const justAdded = ProjectId.make("just-added");
   appAtomRegistry.set(projectsAtom(), [
     { id: existing, environmentId: primaryId, workspaceRoot: "/projects/first" },
+    // Added a moment ago, so the cached scan does not know it exists yet.
+    { id: justAdded, environmentId: primaryId, workspaceRoot: "/projects/second" },
   ]);
   appAtomRegistry.set(candidatesAtom(), [
     candidate("/projects/first", { alreadyImported: true, projectId: existing }),
     candidate("/projects/second"),
+    candidate("/projects/third"),
   ]);
+  {
+    await using _screen = await mountWelcome();
+    await vi.waitFor(() => expect(pageText()).toContain("Import 1 project and their threads"));
+  }
+
+  // With every project already in T3 Code, checking the box still picks them.
+  appAtomRegistry.set(candidatesAtom(), appAtomRegistry.get(candidatesAtom()).slice(0, 2));
   await using _screen = await mountWelcome();
-  await vi.waitFor(() => expect(pageText()).toContain("Import 1 project and their threads"));
+  const importProjects = document.querySelector<HTMLElement>('[role="checkbox"]');
+  await act(async () => importProjects?.click());
+  await vi.waitFor(() => expect(pageText()).toContain("Import 2 projects and their threads"));
+  expect(button("Import threads and start").disabled).toBe(false);
+});
+
+it("keeps the started projects checked when the page opens again after a quit", async () => {
+  using _now = setup();
+  const imported = deferred<{ importedCount: number; skippedCount: number }>();
+  state.importThreads.mockImplementationOnce(async () =>
+    AsyncResult.success(await imported.promise),
+  );
+  {
+    await using _first = await mountWelcome();
+    await click("Import 2 projects and start");
+    await vi.waitFor(() => expect(state.importThreads).toHaveBeenCalledOnce());
+  }
+  // The app quit during the first project's history; it now exists in T3 Code.
+  const [first] = appAtomRegistry.get(projectsAtom());
+  appAtomRegistry.set(candidatesAtom(), [
+    candidate("/projects/first", { alreadyImported: true, projectId: first!.id }),
+    candidate("/projects/second"),
+  ]);
+  await using _second = await mountWelcome();
+  await vi.waitFor(() => expect(pageText()).toContain("Import 2 projects and their threads"));
 });
 
 it("keeps the project controls when a later scan fails", async () => {
@@ -554,6 +591,12 @@ it("says the phone is set up only once this computer is shared with the signed-i
   using _now = setup();
   state.cloud = true;
   state.auth = { isLoaded: true, isSignedIn: true, userId: "user_1" };
+  appAtomRegistry.set(
+    sessionAtom(primaryId),
+    AsyncResult.success(
+      session([AuthOrchestrationOperateScope, AuthRelayReadScope, AuthRelayWriteScope]),
+    ),
+  );
   state.linkError = "Could not read T3 Connect link state.";
   await using _screen = await mountWelcome();
   await click("Set up");
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index 952e18b96099f..1988b5b92ec89 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -10,6 +10,7 @@ import type {
   ServerProvider,
 } from "@t3tools/contracts";
 import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime/environment";
+import { resolveProviderInstanceDisplayName } from "@t3tools/client-runtime/state/provider-instance-display";
 import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
@@ -17,6 +18,8 @@ import {
 import {
   AgentSessionSource,
   AuthProvidersManageScope,
+  AuthRelayReadScope,
+  AuthRelayWriteScope,
   AuthTerminalOperateScope,
   CommandId,
   AuthOrchestrationOperateScope,
@@ -86,7 +89,6 @@ import {
 import { terminalEnvironment } from "../../state/terminal";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { getProviderSummary } from "../settings/providerStatus";
-import { providerClients } from "../settings/providerDriverMeta";
 import { AddProviderInstanceDialog } from "../settings/AddProviderInstanceDialog";
 import { useDesktopCliCommand } from "../settings/CliCommandSettingsRow";
 import { CodexSetupSection } from "../settings/CodexSetupSection";
@@ -126,9 +128,13 @@ export function WelcomePage({
     environments.find((environment) => environment.environmentId === environmentId)?.label ??
     "this computer";
   const agentReady = useWelcomeAgents(environmentId).readyCount > 0;
+  // Sharing this computer needs the same relay access as Settings → Sharing & access.
+  const canReadRelay = useEnvironmentScope(environmentId, AuthRelayReadScope);
+  const canWriteRelay = useEnvironmentScope(environmentId, AuthRelayWriteScope);
   const phonePath = welcomePhonePath({
     isPrimary: usePrimaryEnvironmentId() === environmentId,
     cloud: hasCloudPublicConfig(),
+    canShare: canReadRelay && canWriteRelay,
     policy: useManagedPolicy(environmentId),
   });
   const scans = useProjectScans([environmentId]);
@@ -226,15 +232,15 @@ export function WelcomePage({
   });
   // Without import permission, starting simply skips the projects.
   const selected = projectImport.canWrite ? projectImport.selected : [];
-  // The scan can be a little old, so a project added a moment ago is matched here too.
-  const projects = useProjects();
-  const newCount = selected.filter(
-    (candidate) =>
-      resolveOnboardingProjectId(projects, candidate.environmentId, candidate) === null,
-  ).length;
+  const newCount = selected.filter(projectImport.isNew).length;
   const start = () => {
-    if (selected.length > 0) void projectImport.runImport(selected);
-    else projectImport.finishAfterImport();
+    if (selected.length === 0) {
+      projectImport.finishAfterImport();
+      return;
+    }
+    // Stored now, so after a restart mid-import these stay checked even once they exist.
+    projectImport.setSelectedKeys(new Set(selected.map((candidate) => candidate.key)));
+    void projectImport.runImport(selected);
   };
 
   return (
@@ -354,14 +360,8 @@ interface AgentTerminalSession {
   readonly keybindings: ServerConfig["keybindings"];
 }
 
-function agentName(provider: ServerProvider) {
-  return (
-    provider.displayName ||
-    (provider.driver === "claudeAgent"
-      ? "Claude Code"
-      : (providerClients.get(provider.driver)?.label ?? provider.driver))
-  );
-}
+// The same name the model picker shows, which tells two unnamed instances of one agent apart.
+const agentName = resolveProviderInstanceDisplayName;
 
 // Shared by the page (to enable Start) and the agents section, so both agree on what is ready.
 function useWelcomeAgents(environmentId: EnvironmentId) {
@@ -430,10 +430,14 @@ function AgentsSection({
         isProviderAvailable(provider) &&
         provider.auth.status !== "authenticated"));
   // Codex setup stays mounted by instance while its status changes, so a sign-in that
-  // starts after an install is not lost when the agent moves between groups.
+  // starts after an install is not lost when the agent moves between groups. It closes once
+  // Codex is signed in; anything left, such as a broken version, shows on its row.
   const codexSetupProvider =
     providers?.find(
-      (provider) => provider.instanceId === codexSetupId && stateOf(provider) !== "ready",
+      (provider) =>
+        provider.instanceId === codexSetupId &&
+        stateOf(provider) !== "ready" &&
+        provider.auth.status !== "authenticated",
     ) ?? null;
 
   const openTerminal = (provider: ServerProvider) => {
@@ -710,6 +714,7 @@ function ProjectsSection({
   const {
     canWrite,
     candidates,
+    isNew,
     recent,
     selected,
     selectedKeys,
@@ -755,9 +760,11 @@ function ProjectsSection({
   }
 
   const allKeys = candidates.map((candidate) => candidate.key);
-  const defaultKeys = (
-    recent.length > 0 ? recent : candidates.filter((candidate) => !candidate.alreadyImported)
-  ).map((candidate) => candidate.key);
+  // Checking the box picks recent new projects, else any new ones, else everything listed.
+  const fresh = candidates.filter(isNew);
+  const defaultKeys = (recent.length > 0 ? recent : fresh.length > 0 ? fresh : candidates).map(
+    (candidate) => candidate.key,
+  );
   const partial =
     selected.length > 0 &&
     selected.length < candidates.length &&
@@ -1047,7 +1054,12 @@ function OnboardingCodexSetup({
       if (result._tag === "Failure") {
         onUseCliChange(false);
         if (!isAtomCommandInterrupted(result)) {
-          toastManager.add({ type: "error", title: "Could not save Codex setup" });
+          const cause = squashAtomCommandFailure(result);
+          toastManager.add({
+            type: "error",
+            title: "Could not save Codex setup",
+            ...(cause instanceof Error ? { description: cause.message } : {}),
+          });
         }
       }
     });
@@ -1366,8 +1378,11 @@ function useProjectImport({
     ),
   );
   // Projects already in T3 Code stay in the list, but reopening the page does not import their
-  // history again unless the user picks them.
-  const recent = recentActive.filter((candidate) => !candidate.alreadyImported);
+  // history again unless the user picks them. The scan can be 30 s old, so the live list decides.
+  const projects = useProjects();
+  const isNew = (candidate: ImportCandidate) =>
+    resolveOnboardingProjectId(projects, candidate.environmentId, candidate) === null;
+  const recent = recentActive.filter(isNew);
   const recentKeys = new Set(recent.map((candidate) => candidate.key));
   const knownKeys = new Set(importSelection?.knownKeys);
   const pickedKeys = new Set(importSelection?.keys);
@@ -1556,6 +1571,7 @@ function useProjectImport({
   return {
     canWrite,
     candidates,
+    isNew,
     recent,
     selected,
     selectedKeys,
diff --git a/apps/web/src/onboarding/welcomePage.logic.test.ts b/apps/web/src/onboarding/welcomePage.logic.test.ts
index b1f835072ebe2..667905f82ce6f 100644
--- a/apps/web/src/onboarding/welcomePage.logic.test.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.test.ts
@@ -147,6 +147,17 @@ describe("cliTerminalStep", () => {
     expect(step({ auth: { status: "unauthenticated" } })).toBe("open");
     // A check that timed out still gets the sign-in command.
     expect(step({ status: "error", auth: { status: "unknown" } })).toBe("open");
+    // A broken version needs the update its row offers, not another sign-in.
+    expect(
+      step({
+        compatibilityAdvisory: {
+          status: "broken",
+          message: "Update Codex.",
+          recommendedVersion: null,
+          recommendedRange: null,
+        },
+      }),
+    ).toBe("done");
     expect(step()).toBe("done");
   });
 });
@@ -159,10 +170,17 @@ describe("welcomePhonePath", () => {
       ...(limits === undefined ? {} : { limits }),
     });
     const path = (input: Partial<Parameters<typeof welcomePhonePath>[0]>) =>
-      welcomePhonePath({ isPrimary: true, cloud: true, policy: undefined, ...input });
+      welcomePhonePath({
+        isPrimary: true,
+        cloud: true,
+        canShare: true,
+        policy: undefined,
+        ...input,
+      });
 
     expect(path({})).toBe("connect");
     expect(path({ cloud: false })).toBe("pairing");
+    expect(path({ canShare: false })).toBe("pairing");
     expect(path({ policy: policy({ connect: false }) })).toBe("pairing");
     expect(path({ policy: policy({ clients: ["desktop"] }) })).toBeNull();
     expect(path({ isPrimary: false })).toBeNull();
diff --git a/apps/web/src/onboarding/welcomePage.logic.ts b/apps/web/src/onboarding/welcomePage.logic.ts
index acfc7a4400fe8..d3cae21bbec97 100644
--- a/apps/web/src/onboarding/welcomePage.logic.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.ts
@@ -81,6 +81,8 @@ export function cliTerminalStep(
   if (provider.setup?.canAuthenticate === true) return "wait";
   const state = welcomeAgentState(provider, settings);
   if (state === "checking") return "wait";
+  // A broken version needs an update, which its row offers; signing in again would not help.
+  if (provider.compatibilityAdvisory?.status === "broken") return "done";
   // The terminal shows the command first, so it also helps a CLI whose check failed.
   const fixable =
     state === "install" ||
@@ -96,12 +98,16 @@ export function cliTerminalStep(
 export function welcomePhonePath(input: {
   readonly isPrimary: boolean;
   readonly cloud: boolean;
+  // Relay read and write access, which sharing this computer through T3 Connect needs.
+  readonly canShare: boolean;
   readonly policy: ManagedPolicySummary | undefined;
 }) {
   if (!input.isPrimary || managedCapabilityDenial(input.policy, "remoteClients") !== undefined) {
     return null;
   }
-  return input.cloud && managedCapabilityDenial(input.policy, "connect") === undefined
+  return input.cloud &&
+    input.canShare &&
+    managedCapabilityDenial(input.policy, "connect") === undefined
     ? "connect"
     : "pairing";
 }
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 1b94d8a322298..6322e00991f6e 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -165,11 +165,7 @@ function RootRouteBranch() {
   }
 
   const isWelcome = pathname === "/welcome";
-  if (
-    !isWelcome &&
-    authGateState.status !== "authenticated" &&
-    authGateState.status !== "hosted-static"
-  ) {
+  if (authGateState.status !== "authenticated" && authGateState.status !== "hosted-static") {
     return <Outlet />;
   }
 
diff --git a/apps/web/src/routes/welcome.tsx b/apps/web/src/routes/welcome.tsx
index 03daff013ab7c..5fbb52359a1cf 100644
--- a/apps/web/src/routes/welcome.tsx
+++ b/apps/web/src/routes/welcome.tsx
@@ -31,7 +31,8 @@ function WelcomeRouteView() {
   const primaryEnvironmentId = usePrimaryEnvironmentId();
   const { environments, isReady } = useEnvironments();
   // Trust the id only once the catalog has it; an unknown computer falls back to this one.
-  const waitingForCatalog = resumeEnvironmentId !== undefined && !isReady;
+  const waitingForCatalog =
+    !isReady && (resumeEnvironmentId !== undefined || primaryEnvironmentId === null);
   const resumeKnown =
     resumeEnvironmentId !== undefined &&
     environments.some((environment) => environment.environmentId === resumeEnvironmentId);
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 9b67469891a66..80c9efe9d5d30 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -97,9 +97,11 @@ does not count toward that limit. It ignores malformed records and skips
 unreadable or unparseable conversations.
 
 Each import attempt reads up to 100 conversation files and 4 GiB per project,
-with up to 100,000 input records. Run import again to continue a large batch.
+with up to 100,000 input records. To continue a large batch, open the Welcome page again
+and pick the project in **Review all**.
 Completed conversations are not imported again. You can continue without the
 remaining history.
 
 You can start without importing. While an import runs, T3 Code stays on the
-Welcome page. If you quit, open the Welcome page again to import the rest.
+Welcome page. If you quit, open the Welcome page again from **Settings → About**; the
+projects you started stay checked.

From 9b506d17bcd26a5dd6d2f1c7632946081afcd2cd Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 20:56:48 -0800
Subject: [PATCH 10/22] fix(web): Welcome page opens Codex sign-in for a broken
 CLI and checks pairing access

- "Use existing CLI" stops for a broken version only once Codex is signed in;
  a signed-out CLI still gets its sign-in terminal.
- Codex's setup card opens only while Codex is not signed in (codexNeedsSetup),
  so a signed-in Codex without its binary gets Install, and the card shows the
  instance name.
- The phone offers pairing only with access to create a code, and is hidden
  until the session's access is known; Add to PATH shows only for the primary
  computer.
- Starting before the project list loads keeps saved picks.
- Agent actions name their agent for screen readers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       | 19 +++++-
 .../src/components/onboarding/WelcomePage.tsx | 59 ++++++++++++-------
 .../src/onboarding/welcomePage.logic.test.ts  | 50 ++++++++++++----
 apps/web/src/onboarding/welcomePage.logic.ts  | 32 ++++++++--
 docs/user/welcome-page.md                     |  2 +-
 5 files changed, 122 insertions(+), 40 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index df7fa28d46c68..6484d24521690 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -46,6 +46,7 @@ const state = vi.hoisted(() => ({
   linkError: null as string | null,
   refreshLinkState: vi.fn(),
   scanError: null as string | null,
+  scanPending: false,
 }));
 
 vi.mock(import("@t3tools/client-runtime/state/session"), async (original) => {
@@ -134,8 +135,8 @@ vi.mock(import("../../onboarding/useProjectScans"), async (original) => {
         state.scan({ environmentId });
         return {
           environmentId,
-          data: { candidates, truncated: false } as never,
-          isPending: false,
+          data: (state.scanPending ? null : { candidates, truncated: false }) as never,
+          isPending: state.scanPending,
           error: state.scanError,
           refresh: state.refreshScan,
         };
@@ -320,6 +321,7 @@ function setup() {
   state.linkError = null;
   state.refreshLinkState.mockReset();
   state.scanError = null;
+  state.scanPending = false;
   localStorage.removeItem(welcomeImportSelectionKey(primaryId));
   return now;
 }
@@ -576,6 +578,19 @@ it("keeps the project controls when a later scan fails", async () => {
   expect(button("Retry").disabled).toBe(false);
 });
 
+it("keeps saved picks when Start comes before the project list loads", async () => {
+  using _now = setup();
+  const saved = JSON.stringify({ knownKeys: ["a"], keys: ["a"], optedOut: false });
+  localStorage.setItem(welcomeImportSelectionKey(primaryId), saved);
+  state.scanPending = true;
+  await using _screen = await mountWelcome();
+
+  await click("Start");
+  await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
+  // An import a quit cut short is still checked on the next visit.
+  expect(localStorage.getItem(welcomeImportSelectionKey(primaryId))).toBe(saved);
+});
+
 it("starts without importing when this connection cannot import projects", async () => {
   using _now = setup();
   setGrant(primaryId, false);
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index 1988b5b92ec89..e66e670486f02 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -10,13 +10,14 @@ import type {
   ServerProvider,
 } from "@t3tools/contracts";
 import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime/environment";
-import { resolveProviderInstanceDisplayName } from "@t3tools/client-runtime/state/provider-instance-display";
+import { resolveProviderInstanceDisplayName as agentName } from "@t3tools/client-runtime/state/provider-instance-display";
 import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
 import {
   AgentSessionSource,
+  AuthAccessWriteScope,
   AuthProvidersManageScope,
   AuthRelayReadScope,
   AuthRelayWriteScope,
@@ -24,7 +25,6 @@ import {
   CommandId,
   AuthOrchestrationOperateScope,
   isManagedDriverAllowed,
-  isProviderAvailable,
   ProviderDriverKind,
   ThreadId,
 } from "@t3tools/contracts";
@@ -64,6 +64,7 @@ import {
 } from "../../onboarding/providerReadiness.logic";
 import {
   cliTerminalStep,
+  codexNeedsSetup,
   groupWelcomeAgents,
   welcomeAgentState,
   welcomePhonePath,
@@ -128,13 +129,17 @@ export function WelcomePage({
     environments.find((environment) => environment.environmentId === environmentId)?.label ??
     "this computer";
   const agentReady = useWelcomeAgents(environmentId).readyCount > 0;
-  // Sharing this computer needs the same relay access as Settings → Sharing & access.
+  // The phone and `t3` on PATH belong to the primary computer, so only it offers them.
+  const isPrimary = usePrimaryEnvironmentId() === environmentId;
+  // The same access Settings → Sharing & access checks.
   const canReadRelay = useEnvironmentScope(environmentId, AuthRelayReadScope);
   const canWriteRelay = useEnvironmentScope(environmentId, AuthRelayWriteScope);
+  const canPair = useEnvironmentScope(environmentId, AuthAccessWriteScope);
   const phonePath = welcomePhonePath({
-    isPrimary: usePrimaryEnvironmentId() === environmentId,
+    isPrimary,
     cloud: hasCloudPublicConfig(),
     canShare: canReadRelay && canWriteRelay,
+    canPair,
     policy: useManagedPolicy(environmentId),
   });
   const scans = useProjectScans([environmentId]);
@@ -161,6 +166,8 @@ export function WelcomePage({
     enableBeforeUnload: false,
   });
   const finishingPromiseRef = useRef<Promise<boolean> | null>(null);
+  // Starting before the project list loads keeps saved picks, such as an import a quit cut short.
+  const keepChoicesRef = useRef(false);
   const completionErrorToastIdRef = useRef<ReturnType<typeof toastManager.add> | null>(null);
   const finish = (
     projectRef?: ScopedProjectRef,
@@ -183,7 +190,7 @@ export function WelcomePage({
         // Release before onDone so its own navigation is not blocked.
         holdPageRef.current = false;
         await onDone(projectRef);
-        setImportSelection(null);
+        if (!keepChoicesRef.current) setImportSelection(null);
         if (importWarning) {
           toastManager.add({
             type: "warning",
@@ -234,6 +241,7 @@ export function WelcomePage({
   const selected = projectImport.canWrite ? projectImport.selected : [];
   const newCount = selected.filter(projectImport.isNew).length;
   const start = () => {
+    keepChoicesRef.current = scans.some((scan) => scan.data === null);
     if (selected.length === 0) {
       projectImport.finishAfterImport();
       return;
@@ -264,6 +272,7 @@ export function WelcomePage({
             <AgentsSection
               environmentId={environmentId}
               label={label}
+              isPrimary={isPrimary}
               onImportSourceEnabled={() => scans[0]?.refresh()}
             />
             <ProjectsSection
@@ -360,9 +369,6 @@ interface AgentTerminalSession {
   readonly keybindings: ServerConfig["keybindings"];
 }
 
-// The same name the model picker shows, which tells two unnamed instances of one agent apart.
-const agentName = resolveProviderInstanceDisplayName;
-
 // Shared by the page (to enable Start) and the agents section, so both agree on what is ready.
 function useWelcomeAgents(environmentId: EnvironmentId) {
   const providers = useAtomValue(serverEnvironment.providersValueAtom(environmentId));
@@ -387,10 +393,12 @@ const ACP_REGISTRY_DRIVER_KIND = ProviderDriverKind.make("acpRegistry");
 function AgentsSection({
   environmentId,
   label,
+  isPrimary,
   onImportSourceEnabled,
 }: {
   readonly environmentId: EnvironmentId;
   readonly label: string;
+  readonly isPrimary: boolean;
   // The project scan only reads agents that are on, so turning one on can find more history.
   readonly onImportSourceEnabled: () => void;
 }) {
@@ -423,12 +431,6 @@ function AgentsSection({
     return isInstallableDriver(provider.driver) && (state === "install" || state === "signIn");
   };
   // Codex's card also offers ChatGPT sign-in, which still works when the CLI check failed.
-  const codexNeedsSetup = (provider: ServerProvider) =>
-    provider.driver === "codex" &&
-    (needsInstallOrSignIn(provider) ||
-      (stateOf(provider) === "attention" &&
-        isProviderAvailable(provider) &&
-        provider.auth.status !== "authenticated"));
   // Codex setup stays mounted by instance while its status changes, so a sign-in that
   // starts after an install is not lost when the agent moves between groups. It closes once
   // Codex is signed in; anything left, such as a broken version, shows on its row.
@@ -506,11 +508,13 @@ function AgentsSection({
   // One action per agent, the same in the list and in the grid.
   const actionFor = (provider: ServerProvider) => {
     const state = stateOf(provider);
+    const name = agentName(provider);
     if (state === "disabled") {
       return (
         <Button
           size="xs"
           variant="outline"
+          aria-label={`Turn on: ${name}`}
           disabled={!canManageProviders || serverConfig === null}
           onClick={() => void turnOn(provider)}
         >
@@ -518,12 +522,13 @@ function AgentsSection({
         </Button>
       );
     }
-    if (serverConfig !== null && codexNeedsSetup(provider)) {
+    if (serverConfig !== null && codexNeedsSetup(provider, serverConfig.settings)) {
       const open = codexSetupId === provider.instanceId;
       return (
         <Button
           size="xs"
           variant="outline"
+          aria-label={`Set up: ${name}`}
           aria-expanded={open}
           onClick={() => setCodexSetupId(open ? null : provider.instanceId)}
         >
@@ -534,6 +539,7 @@ function AgentsSection({
     if (needsInstallOrSignIn(provider)) {
       return (
         <TerminalAction
+          name={name}
           signIn={state === "signIn"}
           disabled={
             terminalSession?.providerInstanceId === provider.instanceId ||
@@ -544,10 +550,12 @@ function AgentsSection({
         />
       );
     }
+    const label = state === "signIn" ? "Sign in" : state === "attention" ? "Details" : "Set up";
     return (
       <Button
         size="xs"
         variant="outline"
+        aria-label={`${label}: ${name}`}
         render={
           <Link
             to="/settings/providers"
@@ -555,7 +563,7 @@ function AgentsSection({
           />
         }
       >
-        {state === "signIn" ? "Sign in" : state === "attention" ? "Details" : "Set up"}
+        {label}
       </Button>
     );
   };
@@ -585,7 +593,8 @@ function AgentsSection({
       ) : null}
       {!canOperateTerminal &&
       [...found, ...available].some(
-        (provider) => needsInstallOrSignIn(provider) || codexNeedsSetup(provider),
+        (provider) =>
+          needsInstallOrSignIn(provider) || codexNeedsSetup(provider, serverConfig?.settings),
       ) ? (
         <p className="mt-2 text-sm text-muted-foreground">
           This connection cannot control terminals.
@@ -653,7 +662,7 @@ function AgentsSection({
           />
         </div>
       ) : null}
-      <CliPathSetup />
+      {isPrimary ? <CliPathSetup /> : null}
       {terminalSession !== null ? (
         <AgentInstallTerminal
           key={`${terminalSession.environmentId}:${terminalSession.providerInstanceId}:${terminalSession.driver}`}
@@ -1073,24 +1082,34 @@ function OnboardingCodexSetup({
       mode={mode}
       enabled={provider.enabled}
       readOnly={!canManageProviders}
+      displayName={agentName(provider)}
       onModeChange={changeMode}
     />
   );
 }
 
 function TerminalAction({
+  name,
   signIn,
   disabled,
   onClick,
 }: {
+  readonly name: string;
   readonly signIn: boolean;
   readonly disabled: boolean;
   readonly onClick: () => void;
 }) {
+  const label = signIn ? "Sign in" : "Install";
   return (
-    <Button size="xs" variant="outline" disabled={disabled} onClick={onClick}>
+    <Button
+      size="xs"
+      variant="outline"
+      aria-label={`${label}: ${name}`}
+      disabled={disabled}
+      onClick={onClick}
+    >
       <TerminalIcon className="size-3.5" />
-      {signIn ? "Sign in" : "Install"}
+      {label}
     </Button>
   );
 }
diff --git a/apps/web/src/onboarding/welcomePage.logic.test.ts b/apps/web/src/onboarding/welcomePage.logic.test.ts
index 667905f82ce6f..aba15e8a9e5bf 100644
--- a/apps/web/src/onboarding/welcomePage.logic.test.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.test.ts
@@ -8,7 +8,12 @@ import {
 } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
-import { cliTerminalStep, groupWelcomeAgents, welcomePhonePath } from "./welcomePage.logic";
+import {
+  cliTerminalStep,
+  codexNeedsSetup,
+  groupWelcomeAgents,
+  welcomePhonePath,
+} from "./welcomePage.logic";
 
 function provider(name: string, overrides: Partial<ServerProvider> = {}): ServerProvider {
   return {
@@ -147,21 +152,39 @@ describe("cliTerminalStep", () => {
     expect(step({ auth: { status: "unauthenticated" } })).toBe("open");
     // A check that timed out still gets the sign-in command.
     expect(step({ status: "error", auth: { status: "unknown" } })).toBe("open");
-    // A broken version needs the update its row offers, not another sign-in.
-    expect(
-      step({
-        compatibilityAdvisory: {
-          status: "broken",
-          message: "Update Codex.",
-          recommendedVersion: null,
-          recommendedRange: null,
-        },
-      }),
-    ).toBe("done");
+    // Signed in with a broken version: the update its row offers fixes it, not another sign-in.
+    const broken = {
+      status: "broken",
+      message: "Update Codex.",
+      recommendedVersion: null,
+      recommendedRange: null,
+    } as const;
+    expect(step({ compatibilityAdvisory: broken })).toBe("done");
+    // Signed out, it still needs the sign-in first.
+    expect(step({ compatibilityAdvisory: broken, auth: { status: "unauthenticated" } })).toBe(
+      "open",
+    );
     expect(step()).toBe("done");
   });
 });
 
+describe("codexNeedsSetup", () => {
+  it("opens the setup card only while Codex is not signed in", () => {
+    const setup = (overrides: Partial<ServerProvider>) =>
+      codexNeedsSetup(provider("Codex", overrides), undefined);
+
+    expect(setup({ installed: false, status: "error", auth: { status: "unknown" } })).toBe(true);
+    expect(setup({ auth: { status: "unauthenticated" } })).toBe(true);
+    // A check that timed out can still sign in with ChatGPT.
+    expect(setup({ status: "error", auth: { status: "unknown" } })).toBe(true);
+    // Signed in from its home files but the binary is gone: Install, not the card.
+    expect(setup({ installed: false, status: "error" })).toBe(false);
+    expect(setup({})).toBe(false);
+    const claude = provider("Claude", { auth: { status: "unauthenticated" } });
+    expect(codexNeedsSetup(claude, undefined)).toBe(false);
+  });
+});
+
 describe("welcomePhonePath", () => {
   it("offers T3 Connect or a pairing code only for the primary computer and only when allowed", () => {
     const policy = (limits: ManagedPolicySummary["limits"]): ManagedPolicySummary => ({
@@ -174,6 +197,7 @@ describe("welcomePhonePath", () => {
         isPrimary: true,
         cloud: true,
         canShare: true,
+        canPair: true,
         policy: undefined,
         ...input,
       });
@@ -181,6 +205,8 @@ describe("welcomePhonePath", () => {
     expect(path({})).toBe("connect");
     expect(path({ cloud: false })).toBe("pairing");
     expect(path({ canShare: false })).toBe("pairing");
+    // Without access to share or to create a pairing code, the phone has no way in.
+    expect(path({ canShare: false, canPair: false })).toBeNull();
     expect(path({ policy: policy({ connect: false }) })).toBe("pairing");
     expect(path({ policy: policy({ clients: ["desktop"] }) })).toBeNull();
     expect(path({ isPrimary: false })).toBeNull();
diff --git a/apps/web/src/onboarding/welcomePage.logic.ts b/apps/web/src/onboarding/welcomePage.logic.ts
index d3cae21bbec97..ba735d6422716 100644
--- a/apps/web/src/onboarding/welcomePage.logic.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.ts
@@ -81,8 +81,8 @@ export function cliTerminalStep(
   if (provider.setup?.canAuthenticate === true) return "wait";
   const state = welcomeAgentState(provider, settings);
   if (state === "checking") return "wait";
-  // A broken version needs an update, which its row offers; signing in again would not help.
-  if (provider.compatibilityAdvisory?.status === "broken") return "done";
+  // Signed in with a broken version: the row offers the update, and signing in again would not help.
+  if (state === "attention" && provider.compatibilityAdvisory?.status === "broken") return "done";
   // The terminal shows the command first, so it also helps a CLI whose check failed.
   const fixable =
     state === "install" ||
@@ -91,6 +91,23 @@ export function cliTerminalStep(
   return fixable ? "open" : "done";
 }
 
+/**
+ * Whether Codex's row opens its setup card, which offers ChatGPT sign-in or the CLI. A signed-in
+ * Codex gets the plain Install or Details action instead, since the card has nothing left for it.
+ */
+export function codexNeedsSetup(
+  provider: ServerProvider,
+  settings: ComputerSettings | null | undefined,
+) {
+  if (provider.driver !== "codex" || provider.auth.status === "authenticated") return false;
+  const state = welcomeAgentState(provider, settings);
+  return (
+    state === "install" ||
+    state === "signIn" ||
+    (state === "attention" && isProviderAvailable(provider))
+  );
+}
+
 /**
  * How the Welcome page offers the phone: T3 Connect sign-in, a pairing code, or not at all.
  * Both act on the primary computer, so another computer gets neither.
@@ -100,14 +117,19 @@ export function welcomePhonePath(input: {
   readonly cloud: boolean;
   // Relay read and write access, which sharing this computer through T3 Connect needs.
   readonly canShare: boolean;
+  // Access to create a pairing code, as in Settings → Sharing & access.
+  readonly canPair: boolean;
   readonly policy: ManagedPolicySummary | undefined;
 }) {
   if (!input.isPrimary || managedCapabilityDenial(input.policy, "remoteClients") !== undefined) {
     return null;
   }
-  return input.cloud &&
+  if (
+    input.cloud &&
     input.canShare &&
     managedCapabilityDenial(input.policy, "connect") === undefined
-    ? "connect"
-    : "pairing";
+  ) {
+    return "connect";
+  }
+  return input.canPair ? "pairing" : null;
 }
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 80c9efe9d5d30..5926acca42d6a 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -33,7 +33,7 @@ is found, it reads **Set up an agent** and opens by itself:
   **Update now** working in Settings.
 - For Codex, **Set up** offers sign-in with your ChatGPT account or your own
   Codex CLI. **Use existing CLI** opens the terminal to install or sign in, and
-  **Continue with ChatGPT** stays available until Codex is ready.
+  **Continue with ChatGPT** stays available until Codex is signed in.
 - Other agents, and agents that could not load, open their page in
   **Settings → Providers**.
 - **Browse** opens the ACP Registry for more agents.

From 65214c4af0d6204e4756aa188c4aa6071c310713 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 21:10:16 -0800
Subject: [PATCH 11/22] fix(web): Welcome page updates a broken CLI and checks
 access before setup actions

- A CLI version the server marks broken gets the vendor installer, labelled
  Update, from its row or from "Use existing CLI", instead of a sign-in that
  cannot fix it or a dead click.
- The Codex setup card closes once Codex is signed in or cannot use it.
- Pairing needs read and write access, so the created code can be shown;
  "Use existing CLI" is disabled when this session cannot open a terminal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/components/onboarding/WelcomePage.tsx | 51 +++++++++++--------
 .../components/settings/CodexSetupSection.tsx |  9 +++-
 .../src/onboarding/welcomePage.logic.test.ts  | 25 +++++++--
 apps/web/src/onboarding/welcomePage.logic.ts  | 14 +++--
 docs/user/welcome-page.md                     |  7 +--
 5 files changed, 74 insertions(+), 32 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index e66e670486f02..c6fae2c38ed1d 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -17,6 +17,7 @@ import {
 } from "@t3tools/client-runtime/state/runtime";
 import {
   AgentSessionSource,
+  AuthAccessReadScope,
   AuthAccessWriteScope,
   AuthProvidersManageScope,
   AuthRelayReadScope,
@@ -66,6 +67,7 @@ import {
   cliTerminalStep,
   codexNeedsSetup,
   groupWelcomeAgents,
+  terminalCommand,
   welcomeAgentState,
   welcomePhonePath,
 } from "../../onboarding/welcomePage.logic";
@@ -134,12 +136,14 @@ export function WelcomePage({
   // The same access Settings → Sharing & access checks.
   const canReadRelay = useEnvironmentScope(environmentId, AuthRelayReadScope);
   const canWriteRelay = useEnvironmentScope(environmentId, AuthRelayWriteScope);
-  const canPair = useEnvironmentScope(environmentId, AuthAccessWriteScope);
+  // Creating a pairing code needs write access, and showing it needs read access.
+  const canReadAccess = useEnvironmentScope(environmentId, AuthAccessReadScope);
+  const canWriteAccess = useEnvironmentScope(environmentId, AuthAccessWriteScope);
   const phonePath = welcomePhonePath({
     isPrimary,
     cloud: hasCloudPublicConfig(),
     canShare: canReadRelay && canWriteRelay,
-    canPair,
+    canPair: canReadAccess && canWriteAccess,
     policy: useManagedPolicy(environmentId),
   });
   const scans = useProjectScans([environmentId]);
@@ -433,13 +437,12 @@ function AgentsSection({
   // Codex's card also offers ChatGPT sign-in, which still works when the CLI check failed.
   // Codex setup stays mounted by instance while its status changes, so a sign-in that
   // starts after an install is not lost when the agent moves between groups. It closes once
-  // Codex is signed in; anything left, such as a broken version, shows on its row.
+  // Codex is signed in or cannot use it; anything left, such as a broken version, shows on its row.
   const codexSetupProvider =
     providers?.find(
       (provider) =>
         provider.instanceId === codexSetupId &&
-        stateOf(provider) !== "ready" &&
-        provider.auth.status !== "authenticated",
+        (codexNeedsSetup(provider, serverConfig?.settings) || stateOf(provider) === "checking"),
     ) ?? null;
 
   const openTerminal = (provider: ServerProvider) => {
@@ -454,16 +457,17 @@ function AgentsSection({
       driver: provider.driver,
       providerInstanceId: provider.instanceId,
       cwd: serverConfig.cwd,
-      command: provider.installed
-        ? resolveOnboardingProviderLoginCommand(
-            provider,
-            serverConfig.settings,
-            serverConfig.environment.platform.os,
-          )
-        : resolveOnboardingProviderInstallCommand(
-            provider.driver,
-            serverConfig.environment.platform.os,
-          ),
+      command:
+        terminalCommand(provider) === "signIn"
+          ? resolveOnboardingProviderLoginCommand(
+              provider,
+              serverConfig.settings,
+              serverConfig.environment.platform.os,
+            )
+          : resolveOnboardingProviderInstallCommand(
+              provider.driver,
+              serverConfig.environment.platform.os,
+            ),
       keybindings: serverConfig.keybindings,
     });
   };
@@ -540,7 +544,7 @@ function AgentsSection({
       return (
         <TerminalAction
           name={name}
-          signIn={state === "signIn"}
+          command={terminalCommand(provider)}
           disabled={
             terminalSession?.providerInstanceId === provider.instanceId ||
             serverConfig === null ||
@@ -550,12 +554,13 @@ function AgentsSection({
         />
       );
     }
-    const label = state === "signIn" ? "Sign in" : state === "attention" ? "Details" : "Set up";
+    const actionLabel =
+      state === "signIn" ? "Sign in" : state === "attention" ? "Details" : "Set up";
     return (
       <Button
         size="xs"
         variant="outline"
-        aria-label={`${label}: ${name}`}
+        aria-label={`${actionLabel}: ${name}`}
         render={
           <Link
             to="/settings/providers"
@@ -563,7 +568,7 @@ function AgentsSection({
           />
         }
       >
-        {label}
+        {actionLabel}
       </Button>
     );
   };
@@ -1040,6 +1045,7 @@ function OnboardingCodexSetup({
   readonly onUseCliChange: (useCli: boolean) => void;
 }) {
   const canManageProviders = useEnvironmentScope(environmentId, AuthProvidersManageScope);
+  const canOperateTerminal = useEnvironmentScope(environmentId, AuthTerminalOperateScope);
   const persistProviderInstance = usePersistEnvironmentProviderInstanceMutation(environmentId);
   const instanceId = provider.instanceId;
   const instance = serverConfig.settings.providerInstances[instanceId] ?? {
@@ -1082,6 +1088,7 @@ function OnboardingCodexSetup({
       mode={mode}
       enabled={provider.enabled}
       readOnly={!canManageProviders}
+      existingCliDisabled={!canOperateTerminal}
       displayName={agentName(provider)}
       onModeChange={changeMode}
     />
@@ -1090,16 +1097,16 @@ function OnboardingCodexSetup({
 
 function TerminalAction({
   name,
-  signIn,
+  command,
   disabled,
   onClick,
 }: {
   readonly name: string;
-  readonly signIn: boolean;
+  readonly command: ReturnType<typeof terminalCommand>;
   readonly disabled: boolean;
   readonly onClick: () => void;
 }) {
-  const label = signIn ? "Sign in" : "Install";
+  const label = command === "signIn" ? "Sign in" : command === "update" ? "Update" : "Install";
   return (
     <Button
       size="xs"
diff --git a/apps/web/src/components/settings/CodexSetupSection.tsx b/apps/web/src/components/settings/CodexSetupSection.tsx
index f4dd3da002865..5194012863e89 100644
--- a/apps/web/src/components/settings/CodexSetupSection.tsx
+++ b/apps/web/src/components/settings/CodexSetupSection.tsx
@@ -95,6 +95,8 @@ interface CodexSetupSectionProps {
   readonly mode: "managed" | "existing";
   readonly enabled: boolean;
   readonly readOnly?: boolean;
+  // Onboarding's "Use existing CLI" opens a terminal, which this session may not be allowed.
+  readonly existingCliDisabled?: boolean;
   readonly presentation?: "settings" | "onboarding";
   readonly onModeChange: (mode: "managed" | "existing") => void;
   readonly autoStart?: boolean;
@@ -172,7 +174,12 @@ export function CodexSetupSection(props: CodexSetupSectionProps) {
         }
         secondaryControl={
           !existingAuthenticated && !existingReady && !existingChecking ? (
-            <Button size="sm" variant="ghost-muted" onClick={() => props.onModeChange("existing")}>
+            <Button
+              size="sm"
+              variant="ghost-muted"
+              disabled={props.existingCliDisabled}
+              onClick={() => props.onModeChange("existing")}
+            >
               Use existing CLI
             </Button>
           ) : null
diff --git a/apps/web/src/onboarding/welcomePage.logic.test.ts b/apps/web/src/onboarding/welcomePage.logic.test.ts
index aba15e8a9e5bf..af43d3d17ab5d 100644
--- a/apps/web/src/onboarding/welcomePage.logic.test.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.test.ts
@@ -12,6 +12,7 @@ import {
   cliTerminalStep,
   codexNeedsSetup,
   groupWelcomeAgents,
+  terminalCommand,
   welcomePhonePath,
 } from "./welcomePage.logic";
 
@@ -152,22 +153,40 @@ describe("cliTerminalStep", () => {
     expect(step({ auth: { status: "unauthenticated" } })).toBe("open");
     // A check that timed out still gets the sign-in command.
     expect(step({ status: "error", auth: { status: "unknown" } })).toBe("open");
-    // Signed in with a broken version: the update its row offers fixes it, not another sign-in.
+    // A broken version opens the installer, signed in, signed out, or too old to check.
     const broken = {
       status: "broken",
       message: "Update Codex.",
       recommendedVersion: null,
       recommendedRange: null,
     } as const;
-    expect(step({ compatibilityAdvisory: broken })).toBe("done");
-    // Signed out, it still needs the sign-in first.
+    expect(step({ compatibilityAdvisory: broken })).toBe("open");
     expect(step({ compatibilityAdvisory: broken, auth: { status: "unauthenticated" } })).toBe(
       "open",
     );
+    expect(
+      step({ compatibilityAdvisory: broken, status: "error", auth: { status: "unknown" } }),
+    ).toBe("open");
     expect(step()).toBe("done");
   });
 });
 
+describe("terminalCommand", () => {
+  it("installs a missing or broken CLI and signs in to any other", () => {
+    const broken = {
+      status: "broken",
+      message: "Update Claude Code.",
+      recommendedVersion: null,
+      recommendedRange: null,
+    } as const;
+    expect(terminalCommand(provider("Claude", { installed: false }))).toBe("install");
+    expect(terminalCommand(provider("Claude", { compatibilityAdvisory: broken }))).toBe("update");
+    expect(terminalCommand(provider("Claude", { auth: { status: "unauthenticated" } }))).toBe(
+      "signIn",
+    );
+  });
+});
+
 describe("codexNeedsSetup", () => {
   it("opens the setup card only while Codex is not signed in", () => {
     const setup = (overrides: Partial<ServerProvider>) =>
diff --git a/apps/web/src/onboarding/welcomePage.logic.ts b/apps/web/src/onboarding/welcomePage.logic.ts
index ba735d6422716..c269f5d046516 100644
--- a/apps/web/src/onboarding/welcomePage.logic.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.ts
@@ -81,9 +81,8 @@ export function cliTerminalStep(
   if (provider.setup?.canAuthenticate === true) return "wait";
   const state = welcomeAgentState(provider, settings);
   if (state === "checking") return "wait";
-  // Signed in with a broken version: the row offers the update, and signing in again would not help.
-  if (state === "attention" && provider.compatibilityAdvisory?.status === "broken") return "done";
-  // The terminal shows the command first, so it also helps a CLI whose check failed.
+  // The terminal shows the command first, so it also helps a CLI whose check failed. A broken
+  // version gets the installer, which brings the current one (`terminalCommand`).
   const fixable =
     state === "install" ||
     state === "signIn" ||
@@ -91,6 +90,15 @@ export function cliTerminalStep(
   return fixable ? "open" : "done";
 }
 
+/**
+ * What an agent's setup terminal runs: the vendor installer for a missing CLI or a version the
+ * server knows is broken, else the CLI's sign-in.
+ */
+export function terminalCommand(provider: ServerProvider) {
+  if (!provider.installed) return "install";
+  return provider.compatibilityAdvisory?.status === "broken" ? "update" : "signIn";
+}
+
 /**
  * Whether Codex's row opens its setup card, which offers ChatGPT sign-in or the CLI. A signed-in
  * Codex gets the plain Install or Details action instead, since the card has nothing left for it.
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 5926acca42d6a..9d8e7222ee2c5 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -28,11 +28,12 @@ is found, it reads **Set up an agent** and opens by itself:
 
 - **Turn on** enables an agent that is off on this computer, including one only
   some projects use. T3 Code then checks whether it is installed and signed in.
-- For Claude Code, **Install** or **Sign in** opens a terminal with the correct
-  command ready to run. Install uses the vendor's own installer, which keeps
+- For Claude Code, **Install**, **Update**, or **Sign in** opens a terminal with
+  the correct command ready to run. **Update** appears when the server knows the
+  installed version does not work with T3 Code. Install uses the vendor's own installer, which keeps
   **Update now** working in Settings.
 - For Codex, **Set up** offers sign-in with your ChatGPT account or your own
-  Codex CLI. **Use existing CLI** opens the terminal to install or sign in, and
+  Codex CLI. **Use existing CLI** opens the terminal to install, update, or sign in, and
   **Continue with ChatGPT** stays available until Codex is signed in.
 - Other agents, and agents that could not load, open their page in
   **Settings → Providers**.

From 8932e44c4edd2513fbe5ea2d63b13973e29ddd99 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 21:20:28 -0800
Subject: [PATCH 12/22] fix(web): Welcome page updates a broken CLI through
 Settings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- A CLI the server marks broken gets Update on its row, signed in or not,
  which opens it in Settings → Providers, where the update matches how it was
  installed (npm, Homebrew, a pinned binary path). The page no longer runs the
  vendor installer for it, and Codex's setup card no longer opens for it.
- "Use existing CLI" opens no terminal for a signed-in or broken CLI, and the
  ChatGPT card's button also needs terminal access.
- A closed Codex card stays closed; a note says when this connection cannot
  manage agents; the import choice is kept in page state, so a failed storage
  write cannot undo it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       | 22 +++++
 .../src/components/onboarding/WelcomePage.tsx | 98 ++++++++++++-------
 .../components/settings/CodexSetupSection.tsx |  3 +-
 .../src/onboarding/welcomePage.logic.test.ts  | 39 ++++----
 apps/web/src/onboarding/welcomePage.logic.ts  | 29 +++---
 docs/user/welcome-page.md                     |  9 +-
 6 files changed, 123 insertions(+), 77 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index 6484d24521690..3d9f2a698820e 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -591,6 +591,28 @@ it("keeps saved picks when Start comes before the project list loads", async ()
   expect(localStorage.getItem(welcomeImportSelectionKey(primaryId))).toBe(saved);
 });
 
+it("offers Update for a signed-in agent whose version is broken, and keeps Start off", async () => {
+  using _now = setup();
+  appAtomRegistry.set(state.providers as Atom.Writable<ReadonlyArray<ServerProvider>>, [
+    {
+      ...readyClaude,
+      compatibilityAdvisory: {
+        status: "broken",
+        message: "Update Claude Code to 2.0 or later.",
+        recommendedVersion: "2.0.0",
+        recommendedRange: null,
+      },
+    },
+  ]);
+  await using _screen = await mountWelcome();
+  await vi.waitFor(() => expect(pageText()).toContain("Update Claude Code to 2.0 or later."));
+  const update = [...document.querySelectorAll("a")].find(
+    (element) => element.textContent?.trim() === "Update",
+  );
+  expect(update?.getAttribute("href")).toContain("/settings/providers");
+  expect(button("Import 2 projects and start").disabled).toBe(true);
+});
+
 it("starts without importing when this connection cannot import projects", async () => {
   using _now = setup();
   setGrant(primaryId, false);
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index c6fae2c38ed1d..6227a00685d2f 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -67,7 +67,7 @@ import {
   cliTerminalStep,
   codexNeedsSetup,
   groupWelcomeAgents,
-  terminalCommand,
+  isBrokenVersion,
   welcomeAgentState,
   welcomePhonePath,
 } from "../../onboarding/welcomePage.logic";
@@ -147,11 +147,17 @@ export function WelcomePage({
     policy: useManagedPolicy(environmentId),
   });
   const scans = useProjectScans([environmentId]);
-  const [importSelection, setImportSelection] = useLocalStorage(
+  const [storedSelection, storeSelection] = useLocalStorage(
     welcomeImportSelectionKey(environmentId),
     null,
     StoredWelcomeImportSelection,
   );
+  // The page keeps its own copy, so a failed write (a full quota) cannot undo a choice.
+  const [importSelection, setImportSelectionState] = useState(storedSelection);
+  const setImportSelection = (next: WelcomeImportSelection | null) => {
+    setImportSelectionState(next);
+    storeSelection(next);
+  };
   const [isImporting, setIsImporting] = useState(false);
   // True from Start until the landing; leaving earlier would drop the import or the landing.
   const holdPageRef = useRef(false);
@@ -432,7 +438,11 @@ function AgentsSection({
   const stateOf = (provider: ServerProvider) => welcomeAgentState(provider, serverConfig?.settings);
   const needsInstallOrSignIn = (provider: ServerProvider) => {
     const state = stateOf(provider);
-    return isInstallableDriver(provider.driver) && (state === "install" || state === "signIn");
+    return (
+      isInstallableDriver(provider.driver) &&
+      !isBrokenVersion(provider) &&
+      (state === "install" || state === "signIn")
+    );
   };
   // Codex's card also offers ChatGPT sign-in, which still works when the CLI check failed.
   // Codex setup stays mounted by instance while its status changes, so a sign-in that
@@ -444,6 +454,10 @@ function AgentsSection({
         provider.instanceId === codexSetupId &&
         (codexNeedsSetup(provider, serverConfig?.settings) || stateOf(provider) === "checking"),
     ) ?? null;
+  // Once the card closes, a later status change does not reopen it and move the page.
+  if (codexSetupId !== null && providers != null && codexSetupProvider === null) {
+    setCodexSetupId(null);
+  }
 
   const openTerminal = (provider: ServerProvider) => {
     if (
@@ -457,17 +471,16 @@ function AgentsSection({
       driver: provider.driver,
       providerInstanceId: provider.instanceId,
       cwd: serverConfig.cwd,
-      command:
-        terminalCommand(provider) === "signIn"
-          ? resolveOnboardingProviderLoginCommand(
-              provider,
-              serverConfig.settings,
-              serverConfig.environment.platform.os,
-            )
-          : resolveOnboardingProviderInstallCommand(
-              provider.driver,
-              serverConfig.environment.platform.os,
-            ),
+      command: provider.installed
+        ? resolveOnboardingProviderLoginCommand(
+            provider,
+            serverConfig.settings,
+            serverConfig.environment.platform.os,
+          )
+        : resolveOnboardingProviderInstallCommand(
+            provider.driver,
+            serverConfig.environment.platform.os,
+          ),
       keybindings: serverConfig.keybindings,
     });
   };
@@ -513,6 +526,21 @@ function AgentsSection({
   const actionFor = (provider: ServerProvider) => {
     const state = stateOf(provider);
     const name = agentName(provider);
+    const settingsAction = (actionLabel: string) => (
+      <Button
+        size="xs"
+        variant="outline"
+        aria-label={`${actionLabel}: ${name}`}
+        render={
+          <Link
+            to="/settings/providers"
+            search={{ environmentId, instanceId: provider.instanceId }}
+          />
+        }
+      >
+        {actionLabel}
+      </Button>
+    );
     if (state === "disabled") {
       return (
         <Button
@@ -526,6 +554,8 @@ function AgentsSection({
         </Button>
       );
     }
+    // Settings updates a broken CLI the way it was installed, including a custom binary path.
+    if (isBrokenVersion(provider)) return settingsAction("Update");
     if (serverConfig !== null && codexNeedsSetup(provider, serverConfig.settings)) {
       const open = codexSetupId === provider.instanceId;
       return (
@@ -544,7 +574,7 @@ function AgentsSection({
       return (
         <TerminalAction
           name={name}
-          command={terminalCommand(provider)}
+          signIn={state === "signIn"}
           disabled={
             terminalSession?.providerInstanceId === provider.instanceId ||
             serverConfig === null ||
@@ -554,22 +584,8 @@ function AgentsSection({
         />
       );
     }
-    const actionLabel =
-      state === "signIn" ? "Sign in" : state === "attention" ? "Details" : "Set up";
-    return (
-      <Button
-        size="xs"
-        variant="outline"
-        aria-label={`${actionLabel}: ${name}`}
-        render={
-          <Link
-            to="/settings/providers"
-            search={{ environmentId, instanceId: provider.instanceId }}
-          />
-        }
-      >
-        {actionLabel}
-      </Button>
+    return settingsAction(
+      state === "signIn" ? "Sign in" : state === "attention" ? "Details" : "Set up",
     );
   };
 
@@ -605,6 +621,11 @@ function AgentsSection({
           This connection cannot control terminals.
         </p>
       ) : null}
+      {!canManageProviders &&
+      (acpAllowed ||
+        [...found, ...available].some((provider) => stateOf(provider) === "disabled")) ? (
+        <p className="mt-2 text-sm text-muted-foreground">This connection cannot manage agents.</p>
+      ) : null}
       <Collapsible
         open={showMore}
         onOpenChange={setMoreOpen}
@@ -1097,16 +1118,16 @@ function OnboardingCodexSetup({
 
 function TerminalAction({
   name,
-  command,
+  signIn,
   disabled,
   onClick,
 }: {
   readonly name: string;
-  readonly command: ReturnType<typeof terminalCommand>;
+  readonly signIn: boolean;
   readonly disabled: boolean;
   readonly onClick: () => void;
 }) {
-  const label = command === "signIn" ? "Sign in" : command === "update" ? "Update" : "Install";
+  const label = signIn ? "Sign in" : "Install";
   return (
     <Button
       size="xs"
@@ -1135,6 +1156,9 @@ function AgentCard({
 }) {
   const name = agentName(provider);
   // Claude Code and Codex tiles show Install or Set up; other agents that are on say why not.
+  const brokenMessage = isBrokenVersion(provider)
+    ? (provider.compatibilityAdvisory?.message ?? null)
+    : null;
   const detail =
     state === "install"
       ? isInstallableDriver(provider.driver)
@@ -1144,12 +1168,10 @@ function AgentCard({
         ? null
         : state === "attention"
           ? (provider.unavailableReason ??
-            (provider.compatibilityAdvisory?.status === "broken"
-              ? provider.compatibilityAdvisory.message
-              : null) ??
+            brokenMessage ??
             provider.message ??
             getProviderSummary(provider).headline)
-          : getProviderSummary(provider).headline;
+          : (brokenMessage ?? getProviderSummary(provider).headline);
   return (
     <div
       className={cn(
diff --git a/apps/web/src/components/settings/CodexSetupSection.tsx b/apps/web/src/components/settings/CodexSetupSection.tsx
index 5194012863e89..dea5f40dfea33 100644
--- a/apps/web/src/components/settings/CodexSetupSection.tsx
+++ b/apps/web/src/components/settings/CodexSetupSection.tsx
@@ -265,6 +265,7 @@ function ManagedCodexSetup({
   autoStart,
   onAutoStartConsumed,
   allowExistingCli = true,
+  existingCliDisabled,
   presentation,
   displayName,
   onSignInCancelled,
@@ -916,7 +917,7 @@ function ManagedCodexSetup({
               <Button
                 size="sm"
                 variant="ghost-muted"
-                disabled={readOnly || busy}
+                disabled={readOnly || busy || existingCliDisabled}
                 onClick={() => onModeChange("existing")}
               >
                 Use existing CLI
diff --git a/apps/web/src/onboarding/welcomePage.logic.test.ts b/apps/web/src/onboarding/welcomePage.logic.test.ts
index af43d3d17ab5d..c30cf75eae072 100644
--- a/apps/web/src/onboarding/welcomePage.logic.test.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.test.ts
@@ -12,7 +12,6 @@ import {
   cliTerminalStep,
   codexNeedsSetup,
   groupWelcomeAgents,
-  terminalCommand,
   welcomePhonePath,
 } from "./welcomePage.logic";
 
@@ -153,40 +152,26 @@ describe("cliTerminalStep", () => {
     expect(step({ auth: { status: "unauthenticated" } })).toBe("open");
     // A check that timed out still gets the sign-in command.
     expect(step({ status: "error", auth: { status: "unknown" } })).toBe("open");
-    // A broken version opens the installer, signed in, signed out, or too old to check.
+    // A broken version is updated from its row in Settings, signed in, signed out, or unchecked.
     const broken = {
       status: "broken",
       message: "Update Codex.",
       recommendedVersion: null,
       recommendedRange: null,
     } as const;
-    expect(step({ compatibilityAdvisory: broken })).toBe("open");
+    expect(step({ compatibilityAdvisory: broken })).toBe("done");
     expect(step({ compatibilityAdvisory: broken, auth: { status: "unauthenticated" } })).toBe(
-      "open",
+      "done",
     );
     expect(
       step({ compatibilityAdvisory: broken, status: "error", auth: { status: "unknown" } }),
-    ).toBe("open");
+    ).toBe("done");
+    // Signed in but needing a look for another reason: a sign-in would not help.
+    expect(step({ status: "warning" })).toBe("done");
     expect(step()).toBe("done");
   });
 });
 
-describe("terminalCommand", () => {
-  it("installs a missing or broken CLI and signs in to any other", () => {
-    const broken = {
-      status: "broken",
-      message: "Update Claude Code.",
-      recommendedVersion: null,
-      recommendedRange: null,
-    } as const;
-    expect(terminalCommand(provider("Claude", { installed: false }))).toBe("install");
-    expect(terminalCommand(provider("Claude", { compatibilityAdvisory: broken }))).toBe("update");
-    expect(terminalCommand(provider("Claude", { auth: { status: "unauthenticated" } }))).toBe(
-      "signIn",
-    );
-  });
-});
-
 describe("codexNeedsSetup", () => {
   it("opens the setup card only while Codex is not signed in", () => {
     const setup = (overrides: Partial<ServerProvider>) =>
@@ -198,6 +183,18 @@ describe("codexNeedsSetup", () => {
     expect(setup({ status: "error", auth: { status: "unknown" } })).toBe(true);
     // Signed in from its home files but the binary is gone: Install, not the card.
     expect(setup({ installed: false, status: "error" })).toBe(false);
+    // A broken version gets Update on its row.
+    expect(
+      setup({
+        auth: { status: "unauthenticated" },
+        compatibilityAdvisory: {
+          status: "broken",
+          message: null,
+          recommendedVersion: null,
+          recommendedRange: null,
+        },
+      }),
+    ).toBe(false);
     expect(setup({})).toBe(false);
     const claude = provider("Claude", { auth: { status: "unauthenticated" } });
     expect(codexNeedsSetup(claude, undefined)).toBe(false);
diff --git a/apps/web/src/onboarding/welcomePage.logic.ts b/apps/web/src/onboarding/welcomePage.logic.ts
index c269f5d046516..dc7c9ac64d7db 100644
--- a/apps/web/src/onboarding/welcomePage.logic.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.ts
@@ -70,6 +70,11 @@ export function groupWelcomeAgents(
   return { checking, readyCount, found: found.map((entry) => entry.provider), available };
 }
 
+/** A CLI the server knows is too old or otherwise broken for T3 Code; Settings updates it. */
+export function isBrokenVersion(provider: ServerProvider) {
+  return provider.installed && provider.compatibilityAdvisory?.status === "broken";
+}
+
 /**
  * What "Use existing CLI" does next for Codex: wait for the CLI's own check, open its terminal,
  * or stop. Only the ChatGPT sign-in runtime reports `setup.canAuthenticate`.
@@ -81,8 +86,9 @@ export function cliTerminalStep(
   if (provider.setup?.canAuthenticate === true) return "wait";
   const state = welcomeAgentState(provider, settings);
   if (state === "checking") return "wait";
-  // The terminal shows the command first, so it also helps a CLI whose check failed. A broken
-  // version gets the installer, which brings the current one (`terminalCommand`).
+  // A broken version is updated from its row, and a signed-in CLI needs no terminal.
+  if (isBrokenVersion(provider) || provider.auth.status === "authenticated") return "done";
+  // The terminal shows the command first, so it also helps a CLI whose check failed.
   const fixable =
     state === "install" ||
     state === "signIn" ||
@@ -90,24 +96,21 @@ export function cliTerminalStep(
   return fixable ? "open" : "done";
 }
 
-/**
- * What an agent's setup terminal runs: the vendor installer for a missing CLI or a version the
- * server knows is broken, else the CLI's sign-in.
- */
-export function terminalCommand(provider: ServerProvider) {
-  if (!provider.installed) return "install";
-  return provider.compatibilityAdvisory?.status === "broken" ? "update" : "signIn";
-}
-
 /**
  * Whether Codex's row opens its setup card, which offers ChatGPT sign-in or the CLI. A signed-in
- * Codex gets the plain Install or Details action instead, since the card has nothing left for it.
+ * or broken Codex gets its plain row action instead, since the card has nothing left for it.
  */
 export function codexNeedsSetup(
   provider: ServerProvider,
   settings: ComputerSettings | null | undefined,
 ) {
-  if (provider.driver !== "codex" || provider.auth.status === "authenticated") return false;
+  if (
+    provider.driver !== "codex" ||
+    provider.auth.status === "authenticated" ||
+    isBrokenVersion(provider)
+  ) {
+    return false;
+  }
   const state = welcomeAgentState(provider, settings);
   return (
     state === "install" ||
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 9d8e7222ee2c5..314ebbbd0de20 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -28,13 +28,14 @@ is found, it reads **Set up an agent** and opens by itself:
 
 - **Turn on** enables an agent that is off on this computer, including one only
   some projects use. T3 Code then checks whether it is installed and signed in.
-- For Claude Code, **Install**, **Update**, or **Sign in** opens a terminal with
-  the correct command ready to run. **Update** appears when the server knows the
-  installed version does not work with T3 Code. Install uses the vendor's own installer, which keeps
+- For Claude Code, **Install** or **Sign in** opens a terminal with the correct
+  command ready to run. Install uses the vendor's own installer, which keeps
   **Update now** working in Settings.
 - For Codex, **Set up** offers sign-in with your ChatGPT account or your own
-  Codex CLI. **Use existing CLI** opens the terminal to install, update, or sign in, and
+  Codex CLI. **Use existing CLI** opens the terminal to install or sign in, and
   **Continue with ChatGPT** stays available until Codex is signed in.
+- When T3 Code knows an installed version does not work with it, **Update** opens
+  the agent in **Settings → Providers**, which updates it the way it was installed.
 - Other agents, and agents that could not load, open their page in
   **Settings → Providers**.
 - **Browse** opens the ACP Registry for more agents.

From bc46a73a11fb9e7c5e7fe8a8be46d52f3c70d703 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 21:31:13 -0800
Subject: [PATCH 13/22] fix(web): Welcome page follows finished agent checks
 and rescans after Browse

- "Add more agents" follows the finished checks until the user opens or closes
  it, so a wrong first status (Pi reports installed before its check) cannot
  leave it closed with nothing found.
- Adding an agent through Browse rescans project history, as Turn on does.
- "Use existing CLI" opens the installer for a signed-in Codex whose binary is
  gone; the Codex card closes only when its instance is listed and done.
- The "cannot manage agents" note also covers Codex setup; docs say Settings
  shows the version to use and updates it when it can.
- Tests cover a full storage quota during an opt-out and the agent list rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       | 38 +++++++++++++++++++
 .../src/components/onboarding/WelcomePage.tsx | 28 +++++++++-----
 .../src/onboarding/welcomePage.logic.test.ts  |  2 +
 apps/web/src/onboarding/welcomePage.logic.ts  |  5 ++-
 docs/user/welcome-page.md                     |  3 +-
 5 files changed, 64 insertions(+), 12 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index 3d9f2a698820e..34082e31547c3 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -613,6 +613,44 @@ it("offers Update for a signed-in agent whose version is broken, and keeps Start
   expect(button("Import 2 projects and start").disabled).toBe(true);
 });
 
+it("keeps an import opt-out on the page when storage cannot save it", async () => {
+  using _now = setup();
+  await using _screen = await mountWelcome();
+  using _full = vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+    throw new DOMException("The quota has been exceeded.", "QuotaExceededError");
+  });
+  const importProjects = document.querySelector<HTMLElement>('[role="checkbox"]');
+  await act(async () => importProjects?.click());
+
+  await click("Start");
+  await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
+  expect(state.createProject).not.toHaveBeenCalled();
+});
+
+it("opens the list of agents to add once the checks find none, even after a wrong first status", async () => {
+  using _now = setup();
+  const pi = {
+    ...readyClaude,
+    instanceId: ProviderInstanceId.make("pi"),
+    driver: ProviderDriverKind.make("pi"),
+  };
+  // Pi's first status says installed before its check runs.
+  appAtomRegistry.set(state.providers as Atom.Writable<ReadonlyArray<ServerProvider>>, [
+    { ...pi, status: "warning", auth: { status: "unknown" } },
+  ]);
+  await using _screen = await mountWelcome();
+  await act(async () =>
+    appAtomRegistry.set(state.providers as Atom.Writable<ReadonlyArray<ServerProvider>>, [
+      { ...pi, installed: false, status: "error", auth: { status: "unknown" } },
+    ]),
+  );
+  const fold = () =>
+    [...document.querySelectorAll("button")].find((element) =>
+      element.textContent?.startsWith("Set up an agent"),
+    );
+  await vi.waitFor(() => expect(fold()?.getAttribute("aria-expanded")).toBe("true"));
+});
+
 it("starts without importing when this connection cannot import projects", async () => {
   using _now = setup();
   setGrant(primaryId, false);
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index 6227a00685d2f..4047fc63984e7 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -431,9 +431,9 @@ function AgentsSection({
     void refreshProviders({ environmentId, input: {} });
   }, [environmentId, refreshProviders]);
 
-  // Decided once, when an agent is found or every check ends: with nothing found, adding one is the task.
-  if (moreOpen === null && (found.length > 0 || !checking)) setMoreOpen(found.length === 0);
-  const showMore = moreOpen === true;
+  // Until the user opens or closes it, the list follows the finished checks: with nothing found,
+  // adding an agent is the task. A first status can be wrong, so this is not decided early.
+  const showMore = moreOpen ?? (!checking && found.length === 0);
   const acpAllowed = isManagedDriverAllowed(serverConfig?.managedPolicy, ACP_REGISTRY_DRIVER_KIND);
   const stateOf = (provider: ServerProvider) => welcomeAgentState(provider, serverConfig?.settings);
   const needsInstallOrSignIn = (provider: ServerProvider) => {
@@ -454,10 +454,13 @@ function AgentsSection({
         provider.instanceId === codexSetupId &&
         (codexNeedsSetup(provider, serverConfig?.settings) || stateOf(provider) === "checking"),
     ) ?? null;
-  // Once the card closes, a later status change does not reopen it and move the page.
-  if (codexSetupId !== null && providers != null && codexSetupProvider === null) {
-    setCodexSetupId(null);
-  }
+  // Once the card closes, a later status change does not reopen it and move the page. A list
+  // that briefly lacks the instance does not count.
+  const trackedCodex =
+    codexSetupId === null
+      ? undefined
+      : providers?.find((provider) => provider.instanceId === codexSetupId);
+  if (trackedCodex !== undefined && codexSetupProvider === null) setCodexSetupId(null);
 
   const openTerminal = (provider: ServerProvider) => {
     if (
@@ -623,7 +626,10 @@ function AgentsSection({
       ) : null}
       {!canManageProviders &&
       (acpAllowed ||
-        [...found, ...available].some((provider) => stateOf(provider) === "disabled")) ? (
+        [...found, ...available].some(
+          (provider) =>
+            stateOf(provider) === "disabled" || codexNeedsSetup(provider, serverConfig?.settings),
+        )) ? (
         <p className="mt-2 text-sm text-muted-foreground">This connection cannot manage agents.</p>
       ) : null}
       <Collapsible
@@ -706,7 +712,11 @@ function AgentsSection({
           environmentLabel={label}
           showMoreProviders
           onOpenChange={setAddingProvider}
-          onCreated={() => void refreshProviders({ environmentId, input: {} })}
+          onCreated={() => {
+            void refreshProviders({ environmentId, input: {} });
+            // A new Claude Code, Codex, or Pi instance can bring more history to import.
+            onImportSourceEnabled();
+          }}
         />
       ) : null}
     </WelcomeSection>
diff --git a/apps/web/src/onboarding/welcomePage.logic.test.ts b/apps/web/src/onboarding/welcomePage.logic.test.ts
index c30cf75eae072..4a89d5ece430a 100644
--- a/apps/web/src/onboarding/welcomePage.logic.test.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.test.ts
@@ -168,6 +168,8 @@ describe("cliTerminalStep", () => {
     ).toBe("done");
     // Signed in but needing a look for another reason: a sign-in would not help.
     expect(step({ status: "warning" })).toBe("done");
+    // Signed in from its home files with the binary gone: the installer.
+    expect(step({ installed: false, status: "error" })).toBe("open");
     expect(step()).toBe("done");
   });
 });
diff --git a/apps/web/src/onboarding/welcomePage.logic.ts b/apps/web/src/onboarding/welcomePage.logic.ts
index dc7c9ac64d7db..99746b488e682 100644
--- a/apps/web/src/onboarding/welcomePage.logic.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.ts
@@ -86,8 +86,9 @@ export function cliTerminalStep(
   if (provider.setup?.canAuthenticate === true) return "wait";
   const state = welcomeAgentState(provider, settings);
   if (state === "checking") return "wait";
-  // A broken version is updated from its row, and a signed-in CLI needs no terminal.
-  if (isBrokenVersion(provider) || provider.auth.status === "authenticated") return "done";
+  // A broken version is updated from its row, and an installed, signed-in CLI needs no terminal.
+  if (isBrokenVersion(provider)) return "done";
+  if (provider.installed && provider.auth.status === "authenticated") return "done";
   // The terminal shows the command first, so it also helps a CLI whose check failed.
   const fixable =
     state === "install" ||
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 314ebbbd0de20..490bc38ca2555 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -35,7 +35,8 @@ is found, it reads **Set up an agent** and opens by itself:
   Codex CLI. **Use existing CLI** opens the terminal to install or sign in, and
   **Continue with ChatGPT** stays available until Codex is signed in.
 - When T3 Code knows an installed version does not work with it, **Update** opens
-  the agent in **Settings → Providers**, which updates it the way it was installed.
+  the agent in **Settings → Providers**, which shows the version to use and updates it
+  when it can.
 - Other agents, and agents that could not load, open their page in
   **Settings → Providers**.
 - **Browse** opens the ACP Registry for more agents.

From e61c3b190baab5b8efa9e92edf58c7becc758834 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 21:42:06 -0800
Subject: [PATCH 14/22] fix(web): Welcome page keeps the agent list and Codex
 card steady during checks

- "Add more agents" opens once the finished checks find nothing and never
  closes by itself, so turning an agent on in it does not collapse it.
- The Codex setup card keeps Codex's last status while a rebuild briefly drops
  the instance, so a ChatGPT sign-in in progress is not lost
  (codexCardProvider, with a table test).
- The add dialog reports the created driver, including a ChatGPT account, so
  the page rescans history only for Claude Code, Codex, and Pi.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       |  8 ++++
 .../src/components/onboarding/WelcomePage.tsx | 38 ++++++++++---------
 .../settings/AddProviderInstanceDialog.tsx    |  5 ++-
 .../src/onboarding/welcomePage.logic.test.ts  | 23 +++++++++++
 apps/web/src/onboarding/welcomePage.logic.ts  | 23 +++++++++++
 5 files changed, 77 insertions(+), 20 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index 34082e31547c3..236e0c80f3ff5 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -649,6 +649,14 @@ it("opens the list of agents to add once the checks find none, even after a wron
       element.textContent?.startsWith("Set up an agent"),
     );
   await vi.waitFor(() => expect(fold()?.getAttribute("aria-expanded")).toBe("true"));
+
+  // Turning an agent on starts a new check; the open list stays where the user is working.
+  await act(async () =>
+    appAtomRegistry.set(state.providers as Atom.Writable<ReadonlyArray<ServerProvider>>, [
+      { ...pi, installed: false, status: "warning", auth: { status: "unknown" } },
+    ]),
+  );
+  expect(fold()?.getAttribute("aria-expanded")).toBe("true");
 });
 
 it("starts without importing when this connection cannot import projects", async () => {
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index 4047fc63984e7..ea4a441ef18fa 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -65,6 +65,7 @@ import {
 } from "../../onboarding/providerReadiness.logic";
 import {
   cliTerminalStep,
+  codexCardProvider,
   codexNeedsSetup,
   groupWelcomeAgents,
   isBrokenVersion,
@@ -431,9 +432,10 @@ function AgentsSection({
     void refreshProviders({ environmentId, input: {} });
   }, [environmentId, refreshProviders]);
 
-  // Until the user opens or closes it, the list follows the finished checks: with nothing found,
-  // adding an agent is the task. A first status can be wrong, so this is not decided early.
-  const showMore = moreOpen ?? (!checking && found.length === 0);
+  // Opened once the finished checks find nothing, since adding an agent is then the task. A first
+  // status can be wrong, so this waits for the checks, and a later check never closes it.
+  if (moreOpen === null && !checking && found.length === 0) setMoreOpen(true);
+  const showMore = moreOpen ?? false;
   const acpAllowed = isManagedDriverAllowed(serverConfig?.managedPolicy, ACP_REGISTRY_DRIVER_KIND);
   const stateOf = (provider: ServerProvider) => welcomeAgentState(provider, serverConfig?.settings);
   const needsInstallOrSignIn = (provider: ServerProvider) => {
@@ -445,22 +447,22 @@ function AgentsSection({
     );
   };
   // Codex's card also offers ChatGPT sign-in, which still works when the CLI check failed.
-  // Codex setup stays mounted by instance while its status changes, so a sign-in that
-  // starts after an install is not lost when the agent moves between groups. It closes once
-  // Codex is signed in or cannot use it; anything left, such as a broken version, shows on its row.
-  const codexSetupProvider =
-    providers?.find(
-      (provider) =>
-        provider.instanceId === codexSetupId &&
-        (codexNeedsSetup(provider, serverConfig?.settings) || stateOf(provider) === "checking"),
-    ) ?? null;
-  // Once the card closes, a later status change does not reopen it and move the page. A list
-  // that briefly lacks the instance does not count.
-  const trackedCodex =
+  // Codex setup stays mounted by instance while its status changes, so a sign-in that starts
+  // after an install is not lost when the agent moves between groups or briefly leaves the list.
+  const [lastCodex, setLastCodex] = useState<ServerProvider | null>(null);
+  const listedCodex =
     codexSetupId === null
       ? undefined
       : providers?.find((provider) => provider.instanceId === codexSetupId);
-  if (trackedCodex !== undefined && codexSetupProvider === null) setCodexSetupId(null);
+  if (listedCodex !== undefined && listedCodex !== lastCodex) setLastCodex(listedCodex);
+  const codexSetupProvider = codexCardProvider({
+    providers,
+    instanceId: codexSetupId,
+    last: lastCodex,
+    settings: serverConfig?.settings,
+  });
+  // Once the card closes, a later status change does not reopen it and move the page.
+  if (listedCodex !== undefined && codexSetupProvider === null) setCodexSetupId(null);
 
   const openTerminal = (provider: ServerProvider) => {
     if (
@@ -712,10 +714,10 @@ function AgentsSection({
           environmentLabel={label}
           showMoreProviders
           onOpenChange={setAddingProvider}
-          onCreated={() => {
+          onCreated={(_instanceId, driver) => {
             void refreshProviders({ environmentId, input: {} });
             // A new Claude Code, Codex, or Pi instance can bring more history to import.
-            onImportSourceEnabled();
+            if (isImportSource(driver)) onImportSourceEnabled();
           }}
         />
       ) : null}
diff --git a/apps/web/src/components/settings/AddProviderInstanceDialog.tsx b/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
index 6a0cb5201cda9..e5074e4a9bfd1 100644
--- a/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
+++ b/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
@@ -140,7 +140,7 @@ interface AddProviderInstanceDialogProps {
   readonly environmentId: EnvironmentId;
   readonly environmentLabel: string;
   readonly onOpenChange: (open: boolean) => void;
-  readonly onCreated?: (instanceId: ProviderInstanceId) => void;
+  readonly onCreated?: (instanceId: ProviderInstanceId, driver: ProviderDriverKind) => void;
   /** Opens with "Show more" expanded, so the ACP Registry search is in view. */
   readonly showMoreProviders?: boolean;
 }
@@ -408,7 +408,7 @@ export function AddProviderInstanceDialog({
       });
       return;
     }
-    onCreated?.(brandedId);
+    onCreated?.(brandedId, driver);
     if (isAcpRegistry && !isLocalAcp) {
       setCreatedInstanceId(brandedId);
       setIsSaving(false);
@@ -428,6 +428,7 @@ export function AddProviderInstanceDialog({
       <AddManagedCodexAccountDialog
         environmentId={environmentId}
         onClose={() => onOpenChange(false)}
+        onAccountCreated={(instanceId) => onCreated?.(instanceId, ProviderDriverKind.make("codex"))}
       />
     );
   }
diff --git a/apps/web/src/onboarding/welcomePage.logic.test.ts b/apps/web/src/onboarding/welcomePage.logic.test.ts
index 4a89d5ece430a..4b31fa9a5e6f0 100644
--- a/apps/web/src/onboarding/welcomePage.logic.test.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.test.ts
@@ -10,6 +10,7 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   cliTerminalStep,
+  codexCardProvider,
   codexNeedsSetup,
   groupWelcomeAgents,
   welcomePhonePath,
@@ -203,6 +204,28 @@ describe("codexNeedsSetup", () => {
   });
 });
 
+describe("codexCardProvider", () => {
+  it("keeps the card on Codex's last status while a rebuild drops it, and closes once signed in", () => {
+    const signedOut = provider("Codex", { auth: { status: "unauthenticated" } });
+    const card = (providers: ReadonlyArray<ServerProvider>, last: ServerProvider | null = null) =>
+      codexCardProvider({ providers, instanceId: signedOut.instanceId, last, settings: undefined });
+
+    expect(card([signedOut])).toBe(signedOut);
+    // The instance is missing for one update while it is rebuilt.
+    expect(card([], signedOut)).toBe(signedOut);
+    expect(card([], provider("Other"))).toBeNull();
+    expect(card([provider("Codex")])).toBeNull();
+    expect(
+      codexCardProvider({
+        providers: [signedOut],
+        instanceId: null,
+        last: null,
+        settings: undefined,
+      }),
+    ).toBeNull();
+  });
+});
+
 describe("welcomePhonePath", () => {
   it("offers T3 Connect or a pairing code only for the primary computer and only when allowed", () => {
     const policy = (limits: ManagedPolicySummary["limits"]): ManagedPolicySummary => ({
diff --git a/apps/web/src/onboarding/welcomePage.logic.ts b/apps/web/src/onboarding/welcomePage.logic.ts
index 99746b488e682..7a4f7ff01ba94 100644
--- a/apps/web/src/onboarding/welcomePage.logic.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.ts
@@ -3,6 +3,7 @@ import {
   managedCapabilityDenial,
   type ManagedPolicySummary,
   ProviderDriverKind,
+  type ProviderInstanceId,
   resolveProjectProviderInstanceEnabled,
   type ServerProvider,
   type ServerSettings,
@@ -145,3 +146,25 @@ export function welcomePhonePath(input: {
   }
   return input.canPair ? "pairing" : null;
 }
+
+/**
+ * The Codex instance the setup card shows, or null when the card is closed. A rebuild briefly
+ * drops an instance from the list, so the card keeps its last status meanwhile instead of
+ * unmounting and losing a sign-in in progress.
+ */
+export function codexCardProvider(input: {
+  readonly providers: ReadonlyArray<ServerProvider> | null | undefined;
+  readonly instanceId: ProviderInstanceId | null;
+  readonly last: ServerProvider | null;
+  readonly settings: ComputerSettings | null | undefined;
+}) {
+  if (input.instanceId === null) return null;
+  const provider =
+    input.providers?.find((candidate) => candidate.instanceId === input.instanceId) ??
+    (input.last?.instanceId === input.instanceId ? input.last : undefined);
+  if (provider === undefined) return null;
+  const open =
+    codexNeedsSetup(provider, input.settings) ||
+    welcomeAgentState(provider, input.settings) === "checking";
+  return open ? provider : null;
+}

From a70992766bf1efd604b5a0302937078491fae8be Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 21:49:02 -0800
Subject: [PATCH 15/22] fix(web): adding a ChatGPT account keeps its sign-in
 step

- AddCodexAccountDialog's onAccountCreated only reports the new account; the
  dialog still runs its own ChatGPT sign-in. The deleted wizard was the only
  caller that wanted it to close first, so Settings and Browse on the Welcome
  page sign in as on main. The dialog test passes the callback and still
  expects the sign-in step.
- Telling new projects from existing ones reads the project list once
  (isNewOnboardingProject) instead of once per candidate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/components/onboarding/WelcomePage.tsx |  5 +-
 .../AddCodexAccountDialog.browser.test.tsx    | 14 ++++-
 .../settings/AddCodexAccountDialog.tsx        |  9 +--
 .../onboarding/projectImport.logic.test.ts    | 59 ++++++++++---------
 .../web/src/onboarding/projectImport.logic.ts | 29 ++++++++-
 5 files changed, 77 insertions(+), 39 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index ea4a441ef18fa..b09883c57084e 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -55,6 +55,7 @@ import {
   partitionOnboardingProjects,
   onboardingProjectKey,
   resolveOnboardingLandingProject,
+  isNewOnboardingProject,
   resolveOnboardingProjectId,
   type OnboardingProjectGroup,
   splitOnboardingProjectPath,
@@ -1440,8 +1441,8 @@ function useProjectImport({
   // Projects already in T3 Code stay in the list, but reopening the page does not import their
   // history again unless the user picks them. The scan can be 30 s old, so the live list decides.
   const projects = useProjects();
-  const isNew = (candidate: ImportCandidate) =>
-    resolveOnboardingProjectId(projects, candidate.environmentId, candidate) === null;
+  const isNewProject = isNewOnboardingProject(projects);
+  const isNew = (candidate: ImportCandidate) => isNewProject(candidate.environmentId, candidate);
   const recent = recentActive.filter(isNew);
   const recentKeys = new Set(recent.map((candidate) => candidate.key));
   const knownKeys = new Set(importSelection?.knownKeys);
diff --git a/apps/web/src/components/settings/AddCodexAccountDialog.browser.test.tsx b/apps/web/src/components/settings/AddCodexAccountDialog.browser.test.tsx
index 8204299ba3d84..9539988f4afe0 100644
--- a/apps/web/src/components/settings/AddCodexAccountDialog.browser.test.tsx
+++ b/apps/web/src/components/settings/AddCodexAccountDialog.browser.test.tsx
@@ -74,7 +74,13 @@ function createdInstanceId(): ProviderInstanceId {
   return ProviderInstanceId.make(Object.keys(call[0].input.patch.providerInstances)[0]!);
 }
 
-function Owner({ onClose }: { readonly onClose: () => void }) {
+function Owner({
+  onClose,
+  onAccountCreated,
+}: {
+  readonly onClose: () => void;
+  readonly onAccountCreated: (instanceId: ProviderInstanceId) => void;
+}) {
   const [shown, setShown] = useState(true);
   return shown ? (
     <AddCodexAccountDialog
@@ -83,6 +89,7 @@ function Owner({ onClose }: { readonly onClose: () => void }) {
         onClose();
         setShown(false);
       }}
+      onAccountCreated={onAccountCreated}
       renderSetup={() => <p>Sign in to ChatGPT</p>}
     />
   ) : null;
@@ -93,6 +100,7 @@ describe("AddCodexAccountDialog", () => {
     const atom = Atom.make<ReadonlyArray<ServerProvider> | null>([]).pipe(Atom.keepAlive);
     providersAtom.current = atom;
     const onClose = vi.fn();
+    const onAccountCreated = vi.fn();
     // A long exit transition that the test finishes by hand, so the close is
     // observable mid-animation without waiting on real time.
     const style = document.createElement("style");
@@ -102,13 +110,15 @@ describe("AddCodexAccountDialog", () => {
     using _style = { [Symbol.dispose]: () => style.remove() };
     await using _screen = await render(
       <AppAtomRegistryProvider>
-        <Owner onClose={onClose} />
+        <Owner onClose={onClose} onAccountCreated={onAccountCreated} />
       </AppAtomRegistryProvider>,
     );
 
     await userEvent.click(page.getByRole("button", { name: "Continue" }));
     const instanceId = createdInstanceId();
+    expect(onAccountCreated).toHaveBeenCalledWith(instanceId, expect.any(String));
     await act(() => registry.set(atom, [codexProvider(instanceId, { status: "unauthenticated" })]));
+    // Telling the owner about the account does not skip the dialog's own sign-in.
     await expect.element(page.getByText("Sign in to ChatGPT")).toBeVisible();
 
     await act(() =>
diff --git a/apps/web/src/components/settings/AddCodexAccountDialog.tsx b/apps/web/src/components/settings/AddCodexAccountDialog.tsx
index a95bb6dfb5e85..bc43009864c31 100644
--- a/apps/web/src/components/settings/AddCodexAccountDialog.tsx
+++ b/apps/web/src/components/settings/AddCodexAccountDialog.tsx
@@ -31,6 +31,7 @@ export function AddCodexAccountDialog({
 }: {
   readonly environmentId: EnvironmentId;
   readonly onClose: () => void;
+  // Told when the account is created; the dialog then runs its own sign-in.
   readonly onAccountCreated?:
     | ((instanceId: ProviderInstanceId, displayName: string) => void)
     | undefined;
@@ -71,12 +72,8 @@ export function AddCodexAccountDialog({
       },
     });
     if (result._tag === "Success") {
-      if (onAccountCreated) {
-        onAccountCreated(id, displayName);
-        onClose();
-      } else {
-        setInstanceId(id);
-      }
+      onAccountCreated?.(id, displayName);
+      setInstanceId(id);
     }
     setPending(false);
   };
diff --git a/apps/web/src/onboarding/projectImport.logic.test.ts b/apps/web/src/onboarding/projectImport.logic.test.ts
index 36766215fc2aa..10cb0d731ee75 100644
--- a/apps/web/src/onboarding/projectImport.logic.test.ts
+++ b/apps/web/src/onboarding/projectImport.logic.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   groupOnboardingProjects,
+  isNewOnboardingProject,
   partitionOnboardingProjects,
   onboardingProjectKey,
   resolveOnboardingLandingProject,
@@ -141,6 +142,7 @@ describe("resolveOnboardingProjectId", () => {
   const localProjectId = ProjectId.make("local-project");
 
   it("uses the scanned project ID when the client still has an older project at that root", () => {
+    const scanned = candidate("/projects/repo", { projectId: localProjectId });
     expect(
       resolveOnboardingProjectId(
         [
@@ -151,46 +153,47 @@ describe("resolveOnboardingProjectId", () => {
           },
         ],
         localEnvironmentId,
-        candidate("/projects/repo", { projectId: localProjectId }),
+        scanned,
       ),
     ).toBe(localProjectId);
+    expect(isNewOnboardingProject([])(localEnvironmentId, scanned)).toBe(false);
   });
 
   it("finds an existing project by normalized root in the target environment", () => {
+    const projects = [
+      {
+        id: ProjectId.make("remote-project"),
+        environmentId: remoteEnvironmentId,
+        workspaceRoot: "C:\\Work\\Repo",
+      },
+      {
+        id: localProjectId,
+        environmentId: localEnvironmentId,
+        workspaceRoot: "C:\\Work\\Repo\\",
+      },
+    ];
     expect(
-      resolveOnboardingProjectId(
-        [
-          {
-            id: ProjectId.make("remote-project"),
-            environmentId: remoteEnvironmentId,
-            workspaceRoot: "C:\\Work\\Repo",
-          },
-          {
-            id: localProjectId,
-            environmentId: localEnvironmentId,
-            workspaceRoot: "C:\\Work\\Repo\\",
-          },
-        ],
-        localEnvironmentId,
-        candidate("c:/work/repo"),
-      ),
+      resolveOnboardingProjectId(projects, localEnvironmentId, candidate("c:/work/repo")),
     ).toBe(localProjectId);
+    expect(isNewOnboardingProject(projects)(localEnvironmentId, candidate("c:/work/repo"))).toBe(
+      false,
+    );
   });
 
   it("does not reuse a project from another environment", () => {
+    const projects = [
+      {
+        id: ProjectId.make("remote-project"),
+        environmentId: remoteEnvironmentId,
+        workspaceRoot: "/projects/repo",
+      },
+    ];
     expect(
-      resolveOnboardingProjectId(
-        [
-          {
-            id: ProjectId.make("remote-project"),
-            environmentId: remoteEnvironmentId,
-            workspaceRoot: "/projects/repo",
-          },
-        ],
-        localEnvironmentId,
-        candidate("/projects/repo"),
-      ),
+      resolveOnboardingProjectId(projects, localEnvironmentId, candidate("/projects/repo")),
     ).toBeNull();
+    expect(isNewOnboardingProject(projects)(localEnvironmentId, candidate("/projects/repo"))).toBe(
+      true,
+    );
   });
 });
 
diff --git a/apps/web/src/onboarding/projectImport.logic.ts b/apps/web/src/onboarding/projectImport.logic.ts
index bb87d24ce6d56..2ed9609938a65 100644
--- a/apps/web/src/onboarding/projectImport.logic.ts
+++ b/apps/web/src/onboarding/projectImport.logic.ts
@@ -1,4 +1,7 @@
-import { findProjectByPath } from "@t3tools/client-runtime/state/projects";
+import {
+  findProjectByPath,
+  normalizeProjectPathForComparison,
+} from "@t3tools/client-runtime/state/projects";
 import type { AgentSessionProjectCandidate, EnvironmentId, ProjectId } from "@t3tools/contracts";
 
 const RECENT_PROJECT_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
@@ -101,6 +104,30 @@ export function resolveOnboardingProjectId(
   return null;
 }
 
+/**
+ * Whether a candidate is not a project yet, by the same rules as `resolveOnboardingProjectId`.
+ * It reads the project list once, so a long candidate list costs one pass, not one per candidate.
+ */
+export function isNewOnboardingProject(
+  projects: ReadonlyArray<{
+    readonly environmentId: EnvironmentId;
+    readonly workspaceRoot: string;
+  }>,
+) {
+  const rootKey = (environmentId: EnvironmentId, path: string) =>
+    `${environmentId}\u0000${normalizeProjectPathForComparison(path)}`;
+  const roots = new Set(
+    projects.map((project) => rootKey(project.environmentId, project.workspaceRoot)),
+  );
+  return (
+    environmentId: EnvironmentId,
+    candidate: Pick<AgentSessionProjectCandidate, "path" | "projectId">,
+  ) =>
+    candidate.projectId === undefined &&
+    (normalizeProjectPathForComparison(candidate.path).length === 0 ||
+      !roots.has(rootKey(environmentId, candidate.path)));
+}
+
 export function resolveOnboardingLandingProject<T>(
   selection: ReadonlyArray<string>,
   projectsWithImportedHistory: ReadonlyMap<string, T>,

From 7f34192682f3f0d5889ec01967c2484c734c1aa9 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 21:57:55 -0800
Subject: [PATCH 16/22] perf(web): normalize each candidate path once when
 finding new projects

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/web/src/onboarding/projectImport.logic.ts | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/onboarding/projectImport.logic.ts b/apps/web/src/onboarding/projectImport.logic.ts
index 2ed9609938a65..1be9c7b824b2a 100644
--- a/apps/web/src/onboarding/projectImport.logic.ts
+++ b/apps/web/src/onboarding/projectImport.logic.ts
@@ -114,18 +114,20 @@ export function isNewOnboardingProject(
     readonly workspaceRoot: string;
   }>,
 ) {
-  const rootKey = (environmentId: EnvironmentId, path: string) =>
-    `${environmentId}\u0000${normalizeProjectPathForComparison(path)}`;
   const roots = new Set(
-    projects.map((project) => rootKey(project.environmentId, project.workspaceRoot)),
+    projects.map(
+      (project) =>
+        `${project.environmentId}\u0000${normalizeProjectPathForComparison(project.workspaceRoot)}`,
+    ),
   );
   return (
     environmentId: EnvironmentId,
     candidate: Pick<AgentSessionProjectCandidate, "path" | "projectId">,
-  ) =>
-    candidate.projectId === undefined &&
-    (normalizeProjectPathForComparison(candidate.path).length === 0 ||
-      !roots.has(rootKey(environmentId, candidate.path)));
+  ) => {
+    if (candidate.projectId !== undefined) return false;
+    const path = normalizeProjectPathForComparison(candidate.path);
+    return path.length === 0 || !roots.has(`${environmentId}\u0000${path}`);
+  };
 }
 
 export function resolveOnboardingLandingProject<T>(

From d8b3afc1c40bb092a2075312bf1fc4c396b23375 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 22:11:31 -0800
Subject: [PATCH 17/22] fix(web): Turn on also clears an old config-level off
 switch

Older settings can keep `enabled: false` inside an instance's `config`,
which still turns the agent off after Turn on set only the top-level flag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/components/onboarding/WelcomePage.tsx    |  3 ++-
 .../web/src/onboarding/welcomePage.logic.test.ts | 12 ++++++++++++
 apps/web/src/onboarding/welcomePage.logic.ts     | 16 ++++++++++++++++
 3 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index b09883c57084e..b974d7e820a0a 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -70,6 +70,7 @@ import {
   codexNeedsSetup,
   groupWelcomeAgents,
   isBrokenVersion,
+  turnedOnInstance,
   welcomeAgentState,
   welcomePhonePath,
 } from "../../onboarding/welcomePage.logic";
@@ -511,7 +512,7 @@ function AgentsSection({
     const result = await persistProviderInstance({
       operation: "upsert",
       instanceId: provider.instanceId,
-      instance: { ...instance, enabled: true },
+      instance: turnedOnInstance(instance),
     });
     if (result._tag === "Failure") {
       if (!isAtomCommandInterrupted(result)) {
diff --git a/apps/web/src/onboarding/welcomePage.logic.test.ts b/apps/web/src/onboarding/welcomePage.logic.test.ts
index 4b31fa9a5e6f0..dbf429b9c3282 100644
--- a/apps/web/src/onboarding/welcomePage.logic.test.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.test.ts
@@ -1,6 +1,7 @@
 import {
   type ManagedPolicySummary,
   ProjectId,
+  resolveProviderInstanceEnabled,
   ProviderDriverKind,
   ProviderInstanceId,
   type ServerProvider,
@@ -13,6 +14,7 @@ import {
   codexCardProvider,
   codexNeedsSetup,
   groupWelcomeAgents,
+  turnedOnInstance,
   welcomePhonePath,
 } from "./welcomePage.logic";
 
@@ -175,6 +177,16 @@ describe("cliTerminalStep", () => {
   });
 });
 
+describe("turnedOnInstance", () => {
+  it("turns an agent on even when older settings keep it off inside its config", () => {
+    const pi = ProviderDriverKind.make("pi");
+    expect(resolveProviderInstanceEnabled(turnedOnInstance({ driver: pi }))).toBe(true);
+    const migrated = turnedOnInstance({ driver: pi, config: { enabled: false, binaryPath: "pi" } });
+    expect(resolveProviderInstanceEnabled(migrated)).toBe(true);
+    expect(migrated.config).toEqual({ enabled: true, binaryPath: "pi" });
+  });
+});
+
 describe("codexNeedsSetup", () => {
   it("opens the setup card only while Codex is not signed in", () => {
     const setup = (overrides: Partial<ServerProvider>) =>
diff --git a/apps/web/src/onboarding/welcomePage.logic.ts b/apps/web/src/onboarding/welcomePage.logic.ts
index 7a4f7ff01ba94..fa330c9a8b979 100644
--- a/apps/web/src/onboarding/welcomePage.logic.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.ts
@@ -2,6 +2,7 @@ import {
   isProviderAvailable,
   managedCapabilityDenial,
   type ManagedPolicySummary,
+  type ProviderInstanceConfig,
   ProviderDriverKind,
   type ProviderInstanceId,
   resolveProjectProviderInstanceEnabled,
@@ -71,6 +72,21 @@ export function groupWelcomeAgents(
   return { checking, readyCount, found: found.map((entry) => entry.provider), available };
 }
 
+/** Older settings can also keep `enabled: false` inside `config`, which still turns the agent off. */
+export function turnedOnInstance(instance: ProviderInstanceConfig): ProviderInstanceConfig {
+  const { config } = instance;
+  const configOff =
+    typeof config === "object" &&
+    config !== null &&
+    "enabled" in config &&
+    config.enabled === false;
+  return {
+    ...instance,
+    enabled: true,
+    ...(configOff ? { config: { ...config, enabled: true } } : {}),
+  };
+}
+
 /** A CLI the server knows is too old or otherwise broken for T3 Code; Settings updates it. */
 export function isBrokenVersion(provider: ServerProvider) {
   return provider.installed && provider.compatibilityAdvisory?.status === "broken";

From 285229f3490f6fa6ac669495b62397f5010f7b4d Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Sun, 8 Nov 2026 23:18:58 -0800
Subject: [PATCH 18/22] feat(web): calmer Welcome page with one phone QR code

Two store QR codes side by side were hard to scan, and every row sat in
its own box. Each part of the page is now one band with its label on the
left and borderless rows that share an icon column. The phone shows one
QR code for t3.codes/mobile, which redirects to the store that matches
the phone, next to two numbered steps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/marketing/vercel.ts                      |  18 +
 apps/web/src/branding.ts                      |   2 +
 .../src/components/onboarding/WelcomePage.tsx | 485 +++++++++---------
 .../settings/MobileAppSettingsRow.tsx         |   4 +-
 docs/user/welcome-page.md                     |  15 +-
 5 files changed, 270 insertions(+), 254 deletions(-)

diff --git a/apps/marketing/vercel.ts b/apps/marketing/vercel.ts
index 4d9782ef3329d..dd911ce0b7ce1 100644
--- a/apps/marketing/vercel.ts
+++ b/apps/marketing/vercel.ts
@@ -32,5 +32,23 @@ export const config: VercelConfig = {
       destination: "https://app.t3.codes",
       permanent: true,
     },
+    // One QR code in the desktop app serves both stores. iPadOS reports a Mac, so it gets /download.
+    {
+      source: "/mobile",
+      has: [{ type: "header", key: "user-agent", value: ".*(iPhone|iPad|iPod).*" }],
+      destination: "https://apps.apple.com/us/app/t3-code-remote-claude-more/id6787819824",
+      permanent: false,
+    },
+    {
+      source: "/mobile",
+      has: [{ type: "header", key: "user-agent", value: ".*Android.*" }],
+      destination: "https://play.google.com/store/apps/details?id=com.t3tools.t3code",
+      permanent: false,
+    },
+    {
+      source: "/mobile",
+      destination: "/download",
+      permanent: false,
+    },
   ],
 };
diff --git a/apps/web/src/branding.ts b/apps/web/src/branding.ts
index 05b4fa6a8f9da..6ac2d1f397a47 100644
--- a/apps/web/src/branding.ts
+++ b/apps/web/src/branding.ts
@@ -26,3 +26,5 @@ export const APP_DISPLAY_NAME =
   formatAppDisplayName({ baseName: APP_BASE_NAME, stageLabel: APP_STAGE_LABEL });
 export const APP_VERSION = import.meta.env.APP_VERSION || "0.0.0";
 export const DESKTOP_DOWNLOAD_URL = "https://t3.codes/download";
+// Redirects to the App Store or Google Play to match the phone that opens it.
+export const MOBILE_APP_URL = "https://t3.codes/mobile";
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index b974d7e820a0a..271e495fe9152 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -35,12 +35,14 @@ import {
   CheckIcon,
   ChevronDownIcon,
   ChevronRightIcon,
+  PlusIcon,
   SmartphoneIcon,
   TerminalIcon,
 } from "lucide-react";
 import { useEffect, useEffectEvent, useRef, useState, type ReactNode } from "react";
 
 import { TYPOGRAPHY_ADVANCED_STORAGE_KEY } from "../../appearanceFonts";
+import { MOBILE_APP_URL } from "../../branding";
 import { isElectron } from "../../env";
 import { useLocalStorage } from "../../hooks/useLocalStorage";
 import { usePersistEnvironmentProviderInstanceMutation } from "../../hooks/useSettings";
@@ -99,7 +101,6 @@ import { AddProviderInstanceDialog } from "../settings/AddProviderInstanceDialog
 import { useDesktopCliCommand } from "../settings/CliCommandSettingsRow";
 import { CodexSetupSection } from "../settings/CodexSetupSection";
 import { readCodexSetupMode } from "../settings/CodexSetupSection.logic";
-import { MOBILE_APP_STORES } from "../settings/MobileAppSettingsRow";
 import { TerminalViewport } from "../ThreadTerminalDrawer";
 import { ProviderInstanceIcon } from "../chat/ProviderInstanceIcon";
 import { ACPRegistryIcon } from "../Icons";
@@ -274,29 +275,30 @@ export function WelcomePage({
         {/* The desktop window only moves where CSS opts in, so keep a titlebar strip. */}
         {isElectron ? <WorkspacePageHeader electron /> : null}
         <div className="min-h-0 flex-1 overflow-y-auto scrollbar-gutter-both">
-          <div className="mx-auto w-full max-w-2xl px-6 pt-12 pb-10 sm:pt-16">
+          <div className="mx-auto w-full max-w-3xl px-6 pt-12 pb-10 sm:pt-20">
             <h1 className="text-2xl font-semibold tracking-tight text-foreground">
               Welcome to T3 Code
             </h1>
-            <p className="mt-2 text-sm text-muted-foreground">
-              Setting up <span className="font-medium text-foreground">{label}</span>. You can
-              change any of this later in Settings.
+            <p className="mt-1.5 text-sm text-muted-foreground">
+              Setting up <span className="text-foreground">{label}</span>.
             </p>
-            <AgentsSection
-              environmentId={environmentId}
-              label={label}
-              isPrimary={isPrimary}
-              onImportSourceEnabled={() => scans[0]?.refresh()}
-            />
-            <ProjectsSection
-              scan={scans[0]}
-              projectImport={projectImport}
-              isImporting={isImporting}
-            />
-            {phonePath === null ? null : (
-              <PhoneSection environmentId={environmentId} path={phonePath} />
-            )}
-            <div className="mt-8 flex flex-wrap items-center justify-between gap-3 border-t border-border/70 pt-6">
+            <div className="mt-10 border-t border-border/60">
+              <AgentsSection
+                environmentId={environmentId}
+                label={label}
+                isPrimary={isPrimary}
+                onImportSourceEnabled={() => scans[0]?.refresh()}
+              />
+              <ProjectsSection
+                scan={scans[0]}
+                projectImport={projectImport}
+                isImporting={isImporting}
+              />
+              {phonePath === null ? null : (
+                <PhoneSection environmentId={environmentId} path={phonePath} />
+              )}
+            </div>
+            <div className="mt-6 flex flex-wrap items-center justify-between gap-3">
               {agentReady ? (
                 <span />
               ) : (
@@ -332,7 +334,7 @@ export function WelcomePage({
 function TelemetryNotice({ environmentId }: { readonly environmentId: EnvironmentId }) {
   const telemetryOff = managedTelemetryOffMessage(useManagedPolicy(environmentId));
   return (
-    <p className="mt-6 text-xs leading-relaxed text-muted-foreground">
+    <p className="mt-10 max-w-prose text-xs leading-relaxed text-muted-foreground">
       {telemetryOff ?? "T3 Code collects anonymous usage data to help us improve it."} To read more
       about how your data is used{telemetryOff === undefined ? " and how to opt out" : ""}, see our{" "}
       <a
@@ -348,26 +350,31 @@ function TelemetryNotice({ environmentId }: { readonly environmentId: Environmen
   );
 }
 
+// Each part of the page is one band: its label on the left, its rows on the right.
 function WelcomeSection({
   title,
-  status,
   children,
 }: {
   readonly title: string;
-  readonly status?: ReactNode;
   readonly children: ReactNode;
 }) {
   return (
-    <section className="mt-8">
-      <div className="mb-3 flex items-baseline justify-between gap-3">
-        <h2 className="text-sm font-semibold text-foreground">{title}</h2>
-        {status ? <span className="text-xs text-muted-foreground">{status}</span> : null}
-      </div>
-      {children}
+    <section className="grid gap-x-10 border-b border-border/60 py-4 sm:grid-cols-[6rem_minmax(0,1fr)]">
+      <h2 className="text-sm leading-10 text-muted-foreground">{title}</h2>
+      <div className="min-w-0">{children}</div>
     </section>
   );
 }
 
+// Rows share one icon column, so names, checkboxes, and steps line up down the page.
+function RowIcon({ children }: { readonly children: ReactNode }) {
+  return (
+    <span className="flex size-5 shrink-0 items-center justify-center text-muted-foreground">
+      {children}
+    </span>
+  );
+}
+
 const INSTALLABLE_DRIVERS = ["codex", "claudeAgent"] as const;
 type OnboardingAgentDriver = (typeof INSTALLABLE_DRIVERS)[number];
 const isInstallableDriver = (driver: string): driver is OnboardingAgentDriver =>
@@ -415,8 +422,7 @@ function AgentsSection({
   // The project scan only reads agents that are on, so turning one on can find more history.
   readonly onImportSourceEnabled: () => void;
 }) {
-  const { providers, serverConfig, checking, readyCount, found, available } =
-    useWelcomeAgents(environmentId);
+  const { providers, serverConfig, checking, found, available } = useWelcomeAgents(environmentId);
   const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
     reportFailure: false,
   });
@@ -596,94 +602,88 @@ function AgentsSection({
     );
   };
 
-  return (
-    <WelcomeSection
-      title="Agents"
-      status={
-        readyCount > 0
-          ? `${readyCount} ready on ${label}`
-          : checking
-            ? `Checking ${label}…`
-            : `None ready on ${label} yet`
-      }
-    >
-      {found.length > 0 ? (
-        <div className="space-y-1.5">
-          {found.map((provider) => (
-            <AgentCard
-              key={provider.instanceId}
-              provider={provider}
-              state={stateOf(provider)}
-              action={actionFor(provider)}
-            />
-          ))}
-        </div>
-      ) : null}
-      {!canOperateTerminal &&
+  const notes = [
+    !canOperateTerminal &&
+    [...found, ...available].some(
+      (provider) =>
+        needsInstallOrSignIn(provider) || codexNeedsSetup(provider, serverConfig?.settings),
+    )
+      ? "This connection cannot control terminals."
+      : null,
+    !canManageProviders &&
+    (acpAllowed ||
       [...found, ...available].some(
         (provider) =>
-          needsInstallOrSignIn(provider) || codexNeedsSetup(provider, serverConfig?.settings),
-      ) ? (
-        <p className="mt-2 text-sm text-muted-foreground">
-          This connection cannot control terminals.
-        </p>
-      ) : null}
-      {!canManageProviders &&
-      (acpAllowed ||
-        [...found, ...available].some(
-          (provider) =>
-            stateOf(provider) === "disabled" || codexNeedsSetup(provider, serverConfig?.settings),
-        )) ? (
-        <p className="mt-2 text-sm text-muted-foreground">This connection cannot manage agents.</p>
+          stateOf(provider) === "disabled" || codexNeedsSetup(provider, serverConfig?.settings),
+      ))
+      ? "This connection cannot manage agents."
+      : null,
+  ].filter((note) => note !== null);
+
+  return (
+    <WelcomeSection title="Agents">
+      {found.map((provider) => (
+        <AgentRow
+          key={provider.instanceId}
+          provider={provider}
+          state={stateOf(provider)}
+          action={actionFor(provider)}
+        />
+      ))}
+      {checking && found.length === 0 ? (
+        <p className="text-sm leading-10 text-muted-foreground">Checking {label}…</p>
       ) : null}
-      <Collapsible
-        open={showMore}
-        onOpenChange={setMoreOpen}
-        className={found.length > 0 ? "mt-2" : undefined}
-      >
-        <CollapsibleTrigger className="group flex w-full items-center gap-3 rounded-lg px-1 py-2 text-left outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring">
-          <span className="text-sm font-medium text-foreground">
+      {notes.map((note) => (
+        <p key={note} className="pl-8 text-xs text-muted-foreground">
+          {note}
+        </p>
+      ))}
+      <Collapsible open={showMore} onOpenChange={setMoreOpen}>
+        <CollapsibleTrigger className="group flex min-h-10 w-full items-center gap-3 rounded-md text-left outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset">
+          <RowIcon>
+            <PlusIcon className="size-4" />
+          </RowIcon>
+          <span
+            className={cn(
+              "text-sm group-hover:text-foreground",
+              found.length > 0 ? "text-muted-foreground" : "text-foreground",
+            )}
+          >
             {found.length > 0 ? "Add more agents" : "Set up an agent"}
           </span>
-          <AgentLogoStack providers={available} />
-          {acpAllowed ? (
-            <span className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
-              <ACPRegistryIcon className="size-3.5" />
-              ACP Registry
-            </span>
-          ) : null}
+          {showMore ? null : <AgentLogoStack providers={available} acp={acpAllowed} />}
           <ChevronDownIcon className="ml-auto size-4 text-muted-foreground group-data-panel-open:rotate-180" />
         </CollapsibleTrigger>
         <CollapsiblePanel>
-          <div className="space-y-1.5 pt-1">
-            <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-2">
-              {available.map((provider) => (
-                <AgentCard
-                  key={provider.instanceId}
-                  provider={provider}
-                  state={stateOf(provider)}
-                  compact
-                  action={actionFor(provider)}
-                />
-              ))}
-            </div>
-            {acpAllowed ? (
-              <div className="flex items-center justify-between gap-3 rounded-lg border border-dashed border-border px-4 py-3">
-                <span className="inline-flex items-center gap-2 text-sm text-muted-foreground">
-                  <ACPRegistryIcon className="size-4" />
-                  More agents in the ACP Registry
-                </span>
-                <Button
-                  size="xs"
-                  variant="outline"
-                  disabled={!canManageProviders}
-                  onClick={() => setAddingProvider(true)}
-                >
-                  Browse
-                </Button>
-              </div>
-            ) : null}
+          <div className="grid grid-cols-1 gap-x-8 sm:grid-cols-2">
+            {available.map((provider) => (
+              <AgentRow
+                key={provider.instanceId}
+                provider={provider}
+                state={stateOf(provider)}
+                compact
+                action={actionFor(provider)}
+              />
+            ))}
           </div>
+          {acpAllowed ? (
+            <div className="flex min-h-9 items-center gap-3">
+              <RowIcon>
+                <ACPRegistryIcon className="size-4" />
+              </RowIcon>
+              <span className="min-w-0 flex-1 text-sm text-muted-foreground">
+                More agents in the ACP Registry
+              </span>
+              <Button
+                size="xs"
+                variant="outline"
+                disabled={!canManageProviders}
+                onClick={() => setAddingProvider(true)}
+              >
+                Browse
+              </Button>
+            </div>
+          ) : null}
         </CollapsiblePanel>
       </Collapsible>
       {codexSetupProvider !== null && serverConfig !== null ? (
@@ -727,25 +727,26 @@ function AgentsSection({
   );
 }
 
-function AgentLogoStack({ providers }: { readonly providers: ReadonlyArray<ServerProvider> }) {
-  if (providers.length === 0) return null;
+// A quiet preview of what the fold holds; the names are inside it.
+function AgentLogoStack({
+  providers,
+  acp,
+}: {
+  readonly providers: ReadonlyArray<ServerProvider>;
+  readonly acp: boolean;
+}) {
+  if (providers.length === 0 && !acp) return null;
   return (
-    <span className="flex items-center" aria-hidden>
-      {providers.slice(0, 5).map((provider, index) => (
-        <span
+    <span className="flex items-center gap-2 opacity-60 grayscale" aria-hidden>
+      {providers.slice(0, 6).map((provider) => (
+        <ProviderInstanceIcon
           key={provider.instanceId}
-          className={cn(
-            "grid size-7 place-items-center rounded-full border border-border bg-background",
-            index > 0 && "-ml-1.5",
-          )}
-        >
-          <ProviderInstanceIcon
-            driverKind={provider.driver}
-            displayName={agentName(provider)}
-            iconClassName="size-3.5"
-          />
-        </span>
+          driverKind={provider.driver}
+          displayName={agentName(provider)}
+          iconClassName="size-3.5"
+        />
       ))}
+      {acp ? <ACPRegistryIcon className="size-3.5" /> : null}
     </span>
   );
 }
@@ -774,7 +775,7 @@ function ProjectsSection({
   if (scan.isPending && candidates.length === 0) {
     return (
       <WelcomeSection title="Projects">
-        <p className="text-sm text-muted-foreground">
+        <p className="text-sm leading-10 text-muted-foreground">
           Looking for projects in your {IMPORT_SOURCES_LABEL} history…
         </p>
       </WelcomeSection>
@@ -790,7 +791,7 @@ function ProjectsSection({
       <WelcomeSection title="Projects">
         <div
           role="alert"
-          className="flex items-center justify-between gap-3 text-sm text-muted-foreground"
+          className="flex min-h-10 items-center justify-between gap-3 text-sm text-muted-foreground"
         >
           <span>Could not check projects. {scan.error}</span>
           {retry}
@@ -801,7 +802,7 @@ function ProjectsSection({
   if (candidates.length === 0) {
     return scan.data?.truncated ? (
       <WelcomeSection title="Projects">
-        <p className="text-xs text-muted-foreground" role="status">
+        <p className="text-xs leading-10 text-muted-foreground" role="status">
           {SCAN_LIMIT_MESSAGE}
         </p>
       </WelcomeSection>
@@ -819,21 +820,28 @@ function ProjectsSection({
     selected.length < candidates.length &&
     !(selected.length === defaultKeys.length && defaultKeys.every((key) => selectedKeys.has(key)));
   return (
-    <WelcomeSection title="Projects" status={`From your ${IMPORT_SOURCES_LABEL} history`}>
-      <div className="flex items-center gap-3 rounded-lg border border-border bg-background px-4 py-3">
+    <WelcomeSection title="Projects">
+      <div className="flex min-h-10 items-center gap-3 py-1">
         <label className="flex min-w-0 flex-1 items-center gap-3">
-          <Checkbox
-            checked={canWrite && selected.length > 0}
-            indeterminate={canWrite && partial}
-            disabled={isImporting || !canWrite}
-            onCheckedChange={(checked) =>
-              setSelectedKeys(new Set(checked ? defaultKeys : []), { optedOut: !checked })
-            }
-          />
-          <span className="min-w-0 flex-1 text-sm text-foreground">
-            {canWrite && selected.length > 0
-              ? `Import ${selected.length} ${selected.length === 1 ? "project" : "projects"} and their threads`
-              : "Import projects and their threads"}
+          <RowIcon>
+            <Checkbox
+              checked={canWrite && selected.length > 0}
+              indeterminate={canWrite && partial}
+              disabled={isImporting || !canWrite}
+              onCheckedChange={(checked) =>
+                setSelectedKeys(new Set(checked ? defaultKeys : []), { optedOut: !checked })
+              }
+            />
+          </RowIcon>
+          <span className="min-w-0 flex-1">
+            <span className="block text-sm font-medium text-foreground">
+              {canWrite && selected.length > 0
+                ? `Import ${selected.length} ${selected.length === 1 ? "project" : "projects"} and their threads`
+                : "Import projects and their threads"}
+            </span>
+            <span className="block text-xs text-muted-foreground">
+              From your {IMPORT_SOURCES_LABEL} history
+            </span>
           </span>
         </label>
         {canWrite ? (
@@ -849,8 +857,9 @@ function ProjectsSection({
         ) : null}
       </div>
       {reviewing && canWrite ? (
-        <fieldset className="mt-2 min-w-0" disabled={isImporting}>
-          <div className="flex items-center justify-between gap-3 px-1 text-xs text-muted-foreground">
+        // The negative margin lines the list's checkboxes up with the one above it.
+        <fieldset className="-mx-1.5 mt-1 min-w-0" disabled={isImporting}>
+          <div className="flex items-center justify-between gap-3 px-2 text-xs text-muted-foreground">
             <span role="status">
               {selected.length} of {candidates.length} selected
             </span>
@@ -885,21 +894,21 @@ function ProjectsSection({
         </fieldset>
       ) : null}
       {scan.data?.truncated ? (
-        <p className="mt-2 text-xs text-muted-foreground" role="status">
+        <p className="pl-8 text-xs text-muted-foreground" role="status">
           {SCAN_LIMIT_MESSAGE}
         </p>
       ) : null}
       {scan.error !== null ? (
         <div
           role="alert"
-          className="mt-2 flex items-center justify-between gap-3 text-sm text-muted-foreground"
+          className="flex items-center justify-between gap-3 pl-8 text-sm text-muted-foreground"
         >
           <span>Could not check projects again. {scan.error}</span>
           {retry}
         </div>
       ) : null}
       {visibleImportError ? (
-        <p className="mt-2 text-sm text-destructive">{visibleImportError}</p>
+        <p className="pt-1 pl-8 text-sm text-destructive">{visibleImportError}</p>
       ) : null}
     </WelcomeSection>
   );
@@ -914,12 +923,14 @@ function PhoneSection({
 }) {
   const [open, setOpen] = useState(false);
   return (
-    <WelcomeSection title="Phone" status="Optional">
+    <WelcomeSection title="Phone">
       <Collapsible open={open} onOpenChange={setOpen}>
-        <div className="flex items-center gap-3 rounded-lg border border-border bg-background px-4 py-3">
-          <SmartphoneIcon className="size-4 shrink-0 text-muted-foreground" />
-          <span className="min-w-0 flex-1 text-sm text-foreground">
-            Use T3 Code from your phone
+        <div className="flex min-h-10 items-center gap-3 py-1">
+          <RowIcon>
+            <SmartphoneIcon className="size-4" />
+          </RowIcon>
+          <span className="min-w-0 flex-1 text-sm font-medium text-foreground">
+            Use T3 Code on your phone
           </span>
           <CollapsibleTrigger render={<Button variant="ghost-muted" size="xs" />}>
             {open ? "Hide" : "Set up"}
@@ -927,45 +938,33 @@ function PhoneSection({
           </CollapsibleTrigger>
         </div>
         <CollapsiblePanel>
-          <div className="mt-2 grid grid-cols-1 gap-2 sm:grid-cols-2">
-            <div className="flex items-center gap-4 rounded-lg border border-border bg-background p-3.5">
-              {MOBILE_APP_STORES.map(({ store, url, Icon }) => (
-                <div key={store} className="flex flex-col items-center gap-1.5">
-                  <div className="rounded-md bg-white p-1">
-                    <QRCodeSvg
-                      value={url}
-                      size={76}
-                      level="M"
-                      marginSize={1}
-                      title={`${store} link`}
-                    />
-                  </div>
-                  <span className="inline-flex items-center gap-1 text-2xs text-muted-foreground">
-                    <Icon className="size-3" />
-                    {store}
-                  </span>
-                </div>
-              ))}
-              <span className="text-sm text-muted-foreground">Scan to get the app.</span>
-            </div>
-            <div className="flex flex-col justify-center gap-2 rounded-lg border border-border bg-background p-3.5">
-              {path === "connect" ? (
-                <PhoneConnectLink environmentId={environmentId} />
-              ) : (
-                <>
-                  <span className="text-sm text-muted-foreground">
-                    Then pair the app with this computer.
-                  </span>
-                  <Button
-                    variant="outline"
-                    size="sm"
-                    className="self-start"
-                    render={<Link to="/settings/access" />}
-                  >
-                    Show pairing code
-                  </Button>
-                </>
-              )}
+          <div className="flex items-center gap-8 pt-2 pb-3 pl-8">
+            <ol className="min-w-0 flex-1 space-y-5">
+              <PhoneStep step={1}>
+                <p className="text-sm text-foreground">Scan with your phone to get the app.</p>
+              </PhoneStep>
+              <PhoneStep step={2}>
+                {path === "connect" ? (
+                  <PhoneConnectLink environmentId={environmentId} />
+                ) : (
+                  <>
+                    <p className="text-sm text-foreground">Pair the app with this computer.</p>
+                    <Button variant="outline" size="xs" render={<Link to="/settings/access" />}>
+                      Show pairing code
+                    </Button>
+                  </>
+                )}
+              </PhoneStep>
+            </ol>
+            {/* One code for both stores: the link opens the store that matches the phone. */}
+            <div className="shrink-0 rounded-lg bg-white p-1.5">
+              <QRCodeSvg
+                value={MOBILE_APP_URL}
+                size={124}
+                level="M"
+                marginSize={2}
+                title="T3 Code app for iPhone and Android"
+              />
             </div>
           </div>
         </CollapsiblePanel>
@@ -974,6 +973,15 @@ function PhoneSection({
   );
 }
 
+function PhoneStep({ step, children }: { readonly step: number; readonly children: ReactNode }) {
+  return (
+    <li className="flex gap-3">
+      <span className="w-3 shrink-0 text-sm text-muted-foreground tabular-nums">{step}</span>
+      <div className="flex min-w-0 flex-col items-start gap-2">{children}</div>
+    </li>
+  );
+}
+
 function PhoneConnectLink({ environmentId }: { readonly environmentId: EnvironmentId }) {
   const { isLoaded, isSignedIn, userId } = useAuth({ treatPendingAsSignedOut: false });
   const { openAuthPrompt } = useT3ConnectAuthPrompt();
@@ -995,71 +1003,56 @@ function PhoneConnectLink({ environmentId }: { readonly environmentId: Environme
     link.managedTunnelActive !== false;
   // The server checks the tunnel on its own; until it has, the result is unknown.
   const reachability = shared ? link.reachability?.status : undefined;
+  const settingsLink = (label: string) => (
+    <Button variant="outline" size="xs" render={<Link to="/settings/access" />}>
+      {label}
+    </Button>
+  );
   if (isSignedIn && link === null && linkState.isPending) {
-    return <span className="text-sm text-muted-foreground">Checking T3 Connect…</span>;
+    return <p className="text-sm text-muted-foreground">Checking T3 Connect…</p>;
   }
   if (isSignedIn && linkState.error !== null) {
     return (
       <>
-        <span className="text-sm text-muted-foreground">Could not check T3 Connect.</span>
-        <Button
-          variant="outline"
-          size="sm"
-          className="self-start"
-          render={<Link to="/settings/access" />}
-        >
-          Check T3 Connect
-        </Button>
+        <p className="text-sm text-foreground">Could not check T3 Connect.</p>
+        {settingsLink("Check T3 Connect")}
       </>
     );
   }
   if (isSignedIn && reachability === "reachable") {
     return (
-      <span className="inline-flex items-center gap-1.5 text-sm text-foreground">
-        <CheckIcon className="size-4 shrink-0 text-success-foreground" />
+      <p className="flex gap-1.5 text-sm text-foreground">
+        <CheckIcon className="mt-0.5 size-4 shrink-0 text-success-foreground" />
         Your phone can reach this computer. Sign in to the app with the same account.
-      </span>
+      </p>
     );
   }
   if (isSignedIn && shared && reachability === undefined) {
     return (
-      <span className="text-sm text-muted-foreground">
+      <p className="text-sm text-foreground">
         T3 Connect is on for this computer. Sign in to the app with the same account.
-      </span>
+      </p>
     );
   }
   if (isSignedIn) {
     // Signing in alone does not share this computer, for example after "Not now".
     return (
       <>
-        <span className="text-sm text-muted-foreground">
+        <p className="text-sm text-foreground">
           {shared
             ? "T3 Connect is on, but the app cannot reach this computer."
             : "Signed in. Share this computer so the app can reach it."}
-        </span>
-        <Button
-          variant="outline"
-          size="sm"
-          className="self-start"
-          render={<Link to="/settings/access" />}
-        >
-          {shared ? "Check T3 Connect" : "Set up T3 Connect"}
-        </Button>
+        </p>
+        {settingsLink(shared ? "Check T3 Connect" : "Set up T3 Connect")}
       </>
     );
   }
   return (
     <>
-      <span className="text-sm text-muted-foreground">
-        Then sign in here and in the app with the same account.
-      </span>
-      <Button
-        variant="outline"
-        size="sm"
-        className="self-start"
-        disabled={!isLoaded}
-        onClick={openAuthPrompt}
-      >
+      <p className="text-sm text-foreground">
+        Sign in to T3 Connect here, then in the app with the same account.
+      </p>
+      <Button variant="outline" size="xs" disabled={!isLoaded} onClick={openAuthPrompt}>
         Sign in to T3 Connect
       </Button>
     </>
@@ -1156,7 +1149,7 @@ function TerminalAction({
   );
 }
 
-function AgentCard({
+function AgentRow({
   provider,
   state,
   action,
@@ -1165,7 +1158,7 @@ function AgentCard({
   readonly provider: ServerProvider;
   readonly state: ReturnType<typeof welcomeAgentState>;
   readonly action?: ReactNode;
-  // A tile for the "Add more agents" grid: the button carries the state, so no detail line.
+  // A row in the "Add more agents" grid: the button carries the state, so no detail line.
   readonly compact?: boolean;
 }) {
   const name = agentName(provider);
@@ -1187,21 +1180,20 @@ function AgentCard({
             getProviderSummary(provider).headline)
           : (brokenMessage ?? getProviderSummary(provider).headline);
   return (
-    <div
-      className={cn(
-        "flex items-center gap-3 rounded-lg border border-border bg-background",
-        compact ? "px-3 py-2.5" : "px-4 py-4",
-      )}
-    >
-      <ProviderInstanceIcon
-        driverKind={provider.driver}
-        displayName={name}
-        iconClassName="size-5"
-      />
+    <div className={cn("flex items-center gap-3", compact ? "min-h-9" : "min-h-10 py-1")}>
+      <RowIcon>
+        <ProviderInstanceIcon
+          driverKind={provider.driver}
+          displayName={name}
+          iconClassName={compact ? "size-4" : "size-[18px]"}
+        />
+      </RowIcon>
       <div className="min-w-0 flex-1">
-        <span className="block truncate text-sm font-medium text-foreground">{name}</span>
+        <span className={cn("block truncate text-sm text-foreground", !compact && "font-medium")}>
+          {name}
+        </span>
         {detail ? (
-          <p className="mt-0.5 line-clamp-2 text-xs leading-relaxed break-words text-muted-foreground">
+          <p className="line-clamp-2 text-xs leading-relaxed break-words text-muted-foreground">
             {detail}
           </p>
         ) : null}
@@ -1887,8 +1879,11 @@ function CliPathSetup() {
   const setup = state?.pathSetup;
   if (!setup) return null;
   return (
-    <div className="mt-5 flex items-center justify-between gap-3">
-      <p className="text-sm text-muted-foreground">
+    <div className="flex min-h-10 items-center gap-3">
+      <RowIcon>
+        <TerminalIcon className="size-4" />
+      </RowIcon>
+      <p className="min-w-0 flex-1 text-sm text-muted-foreground">
         {setup.added ? (
           <>
             Added to {setup.file}. Open a new terminal to use <code className="font-mono">t3</code>.
@@ -1901,7 +1896,7 @@ function CliPathSetup() {
         )}
       </p>
       {setup.added ? null : (
-        <Button size="sm" variant="outline" disabled={busy} onClick={() => run("addToPath")}>
+        <Button size="xs" variant="outline" disabled={busy} onClick={() => run("addToPath")}>
           Add to PATH
         </Button>
       )}
diff --git a/apps/web/src/components/settings/MobileAppSettingsRow.tsx b/apps/web/src/components/settings/MobileAppSettingsRow.tsx
index 61f84dfcd7acf..62f4332a40cc8 100644
--- a/apps/web/src/components/settings/MobileAppSettingsRow.tsx
+++ b/apps/web/src/components/settings/MobileAppSettingsRow.tsx
@@ -5,7 +5,7 @@ import { QRCodeSvg } from "../ui/qr-code";
 import { SettingsRow } from "./settingsLayout";
 import { searchableSetting } from "./settingsSearch";
 
-export const MOBILE_APP_STORES = [
+const stores = [
   {
     label: "iPhone and iPad",
     store: "App Store",
@@ -27,7 +27,7 @@ export function MobileAppSettingsRow() {
       description="Connect to your server from your phone or tablet."
       control={
         <div className="flex items-center gap-2">
-          {MOBILE_APP_STORES.map(({ label, store, url, Icon }) => (
+          {stores.map(({ label, store, url, Icon }) => (
             <Popover key={store}>
               <PopoverTrigger render={<Button size="sm" variant="outline" />}>
                 <Icon />
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 490bc38ca2555..8f26deedcd8a6 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -53,13 +53,14 @@ without one. Checked projects are still imported.
 
 ## Phone
 
-Select **Set up** to show QR codes for the App Store and Google Play. Then select
-**Sign in to T3 Connect** and allow this computer when T3 Code asks, so the app can
-reach it. Sign in to the app with the same account. If you are signed in but this
-computer is not shared yet, select **Set up T3 Connect**. If T3 Connect is on but
-the app cannot reach this computer, select **Check T3 Connect** to see why. On
-builds without T3 Connect, or when your organization turns it off, pair the app
-from **Settings → Sharing & access**.
+Select **Set up** and scan the code with your phone. It opens the App Store on an
+iPhone and Google Play on Android. Then select **Sign in to T3 Connect** and allow
+this computer when T3 Code asks, so the app can reach it. Sign in to the app with
+the same account. If you are signed in but this computer is not shared yet, select
+**Set up T3 Connect**. If T3 Connect is on but the app cannot reach this computer,
+select **Check T3 Connect** to see why. On builds without T3 Connect, or when your
+organization turns it off, select **Show pairing code** to pair the app from
+**Settings → Sharing & access**.
 
 ## Projects
 

From 1925b7d5ba3fcec8fb0c9e028ade2579323ef221 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Mon, 9 Nov 2026 02:31:42 -0800
Subject: [PATCH 19/22] feat(web): Welcome page drops the empty sidebar and
 quiets the usage notice

Setup starts with an empty workspace, so the thread sidebar and its toggle
added nothing on /welcome. The shell keeps its commands there, and the
sidebar shortcut no longer saves a toggle the page cannot show. The usage
data notice is now one short line of fine print at the foot of the page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/web/src/components/AppSidebarLayout.tsx  | 100 ++++++++++--------
 .../src/components/onboarding/WelcomePage.tsx |  10 +-
 apps/web/src/routes/__root.tsx                |   3 +-
 3 files changed, 64 insertions(+), 49 deletions(-)

diff --git a/apps/web/src/components/AppSidebarLayout.tsx b/apps/web/src/components/AppSidebarLayout.tsx
index bdcd278dc8f2c..f9cb8c5170cf9 100644
--- a/apps/web/src/components/AppSidebarLayout.tsx
+++ b/apps/web/src/components/AppSidebarLayout.tsx
@@ -312,7 +312,7 @@ function registerAppShellCommands(router: AnyRouter, shellElement: Element): ()
   };
 }
 
-function SidebarControl() {
+function SidebarControl({ showSidebar }: { readonly showSidebar: boolean }) {
   const router = useRouter();
   const usagePageOpen = useLocation({ select: (location) => location.pathname === "/usage" });
   const keybindings = useAtomValue(primaryServerKeybindingsAtom);
@@ -326,6 +326,8 @@ function SidebarControl() {
 
   // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- window keydown listener that toggles the sidebar on its shortcut
   useEffect(() => {
+    // A hidden sidebar would still save the toggle, so the shortcut does nothing without one.
+    if (!showSidebar) return;
     const onKeyDown = (event: KeyboardEvent) => {
       if (event.defaultPrevented) return;
       if (
@@ -362,7 +364,7 @@ function SidebarControl() {
       window.removeEventListener("keydown", onKeyDown, true);
       unsubscribe?.();
     };
-  }, [keybindings, toggleSidebar, usagePageOpen]);
+  }, [keybindings, showSidebar, toggleSidebar, usagePageOpen]);
 
   // The control lives as long as the shell, so it carries the shell's commands. Created
   // once so re-renders never re-register them.
@@ -380,28 +382,36 @@ function SidebarControl() {
       )}
       data-sidebar-control=""
     >
-      <Tooltip>
-        <TooltipTrigger
-          render={
-            <SidebarTrigger
-              variant={isSidebarVisible && stageBackdropVariant ? "media-navigation" : "ghost"}
-              className={cn(
-                "pointer-events-auto",
-                isSidebarVisible && stageBackdropVariant && "relative top-auto translate-y-0",
-              )}
-              aria-label="Toggle main sidebar"
-            />
-          }
-        />
-        <TooltipPopup side="bottom">
-          Toggle main sidebar{shortcutLabel ? ` (${shortcutLabel})` : ""}
-        </TooltipPopup>
-      </Tooltip>
+      {showSidebar ? (
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <SidebarTrigger
+                variant={isSidebarVisible && stageBackdropVariant ? "media-navigation" : "ghost"}
+                className={cn(
+                  "pointer-events-auto",
+                  isSidebarVisible && stageBackdropVariant && "relative top-auto translate-y-0",
+                )}
+                aria-label="Toggle main sidebar"
+              />
+            }
+          />
+          <TooltipPopup side="bottom">
+            Toggle main sidebar{shortcutLabel ? ` (${shortcutLabel})` : ""}
+          </TooltipPopup>
+        </Tooltip>
+      ) : null}
     </div>
   );
 }
 
-export function AppSidebarLayout({ children }: { children: ReactNode }) {
+export function AppSidebarLayout({
+  children,
+  showSidebar = true,
+}: {
+  children: ReactNode;
+  showSidebar?: boolean;
+}) {
   const sidebarArea = workspaceAreaProps("sidebar", 0, "Threads");
   const [sidebarRouteReveal] = useState<SidebarRouteReveal>(() => ({
     observedKey: null,
@@ -450,31 +460,35 @@ export function AppSidebarLayout({ children }: { children: ReactNode }) {
         storageKey="chat_thread_sidebar_open"
         style={sidebarProviderStyle}
       >
-        <SidebarBrandWidthProbe isElectron={isElectron} onWidthChange={setBrandWidth} />
-        <Sidebar
-          side="left"
-          collapsible="offcanvas"
-          data-app-sidebar=""
-          {...sidebarArea}
-          role="navigation"
-          aria-label="Threads"
-          resizable={{
-            maxWidth: sidebarMaximumWidth,
-            minWidth: sidebarMinimumWidth,
-            shouldAcceptWidth: ({ currentWidth, nextWidth, wrapper }) =>
-              nextWidth <= currentWidth ||
-              wrapper.clientWidth - nextWidth >= THREAD_MAIN_CONTENT_MIN_WIDTH,
-            storageKey: THREAD_SIDEBAR_WIDTH_STORAGE_KEY,
-            onResize: setSidebarWidth,
-          }}
-          style={windowControlsInsetStyle}
-        >
-          <ThreadSidebar routeReveal={sidebarRouteReveal} />
-          <SidebarRail onDoubleClick={resetSidebarWidth} />
-        </Sidebar>
+        {showSidebar ? (
+          <>
+            <SidebarBrandWidthProbe isElectron={isElectron} onWidthChange={setBrandWidth} />
+            <Sidebar
+              side="left"
+              collapsible="offcanvas"
+              data-app-sidebar=""
+              {...sidebarArea}
+              role="navigation"
+              aria-label="Threads"
+              resizable={{
+                maxWidth: sidebarMaximumWidth,
+                minWidth: sidebarMinimumWidth,
+                shouldAcceptWidth: ({ currentWidth, nextWidth, wrapper }) =>
+                  nextWidth <= currentWidth ||
+                  wrapper.clientWidth - nextWidth >= THREAD_MAIN_CONTENT_MIN_WIDTH,
+                storageKey: THREAD_SIDEBAR_WIDTH_STORAGE_KEY,
+                onResize: setSidebarWidth,
+              }}
+              style={windowControlsInsetStyle}
+            >
+              <ThreadSidebar routeReveal={sidebarRouteReveal} />
+              <SidebarRail onDoubleClick={resetSidebarWidth} />
+            </Sidebar>
+          </>
+        ) : null}
         {children}
         <BackgroundThreadAnnouncer />
-        <SidebarControl />
+        <SidebarControl showSidebar={showSidebar} />
         {isElectron ? <HistorySwipeNavigation /> : null}
       </SidebarProvider>
     </PanelAnimationSuppressionProvider>
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index 271e495fe9152..f3620b755f030 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -275,7 +275,7 @@ export function WelcomePage({
         {/* The desktop window only moves where CSS opts in, so keep a titlebar strip. */}
         {isElectron ? <WorkspacePageHeader electron /> : null}
         <div className="min-h-0 flex-1 overflow-y-auto scrollbar-gutter-both">
-          <div className="mx-auto w-full max-w-3xl px-6 pt-12 pb-10 sm:pt-20">
+          <div className="mx-auto flex min-h-full w-full max-w-3xl flex-col px-6 pt-12 pb-8 sm:pt-20">
             <h1 className="text-2xl font-semibold tracking-tight text-foreground">
               Welcome to T3 Code
             </h1>
@@ -334,11 +334,11 @@ export function WelcomePage({
 function TelemetryNotice({ environmentId }: { readonly environmentId: EnvironmentId }) {
   const telemetryOff = managedTelemetryOffMessage(useManagedPolicy(environmentId));
   return (
-    <p className="mt-10 max-w-prose text-xs leading-relaxed text-muted-foreground">
-      {telemetryOff ?? "T3 Code collects anonymous usage data to help us improve it."} To read more
-      about how your data is used{telemetryOff === undefined ? " and how to opt out" : ""}, see our{" "}
+    <p className="mt-auto pt-12 text-2xs leading-relaxed text-muted-foreground/70">
+      {telemetryOff ?? "T3 Code collects anonymous usage data to improve the app."}{" "}
+      {telemetryOff === undefined ? "To opt out, see the" : "See the"}{" "}
       <a
-        className="underline underline-offset-2 hover:text-foreground"
+        className="underline decoration-current/40 underline-offset-2 hover:text-muted-foreground"
         href={PRIVACY_POLICY_URL}
         target="_blank"
         rel="noreferrer noopener"
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 6322e00991f6e..b982a7a76a85c 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -193,7 +193,8 @@ function RootRouteBranch() {
   );
   const appShell = (
     <CommandPalette>
-      <AppSidebarLayout>
+      {/* Setup starts with an empty workspace, so the Welcome page has no thread list. */}
+      <AppSidebarLayout showSidebar={!isWelcome}>
         <Outlet />
       </AppSidebarLayout>
     </CommandPalette>

From 395bb3b18ba7872978bb37c786ccd8b03e810837 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Mon, 9 Nov 2026 02:47:57 -0800
Subject: [PATCH 20/22] feat(web): Welcome page connects the phone by sign-in
 only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The phone step offered a pairing code whenever T3 Connect was missing.
Signing in to the same account is the easier flow, so the page now offers
only that. Without T3 Connect it leaves the phone out, and pairing stays
in Settings → Sharing & access.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/components/onboarding/WelcomePage.tsx | 33 +++----------------
 .../src/onboarding/welcomePage.logic.test.ts  | 26 +++++++--------
 apps/web/src/onboarding/welcomePage.logic.ts  | 20 ++++-------
 docs/user/welcome-page.md                     |  6 ++--
 4 files changed, 27 insertions(+), 58 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index f3620b755f030..8340170b31175 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -17,8 +17,6 @@ import {
 } from "@t3tools/client-runtime/state/runtime";
 import {
   AgentSessionSource,
-  AuthAccessReadScope,
-  AuthAccessWriteScope,
   AuthProvidersManageScope,
   AuthRelayReadScope,
   AuthRelayWriteScope,
@@ -74,7 +72,7 @@ import {
   isBrokenVersion,
   turnedOnInstance,
   welcomeAgentState,
-  welcomePhonePath,
+  welcomeOffersPhone,
 } from "../../onboarding/welcomePage.logic";
 import {
   StoredWelcomeImportSelection,
@@ -140,14 +138,10 @@ export function WelcomePage({
   // The same access Settings → Sharing & access checks.
   const canReadRelay = useEnvironmentScope(environmentId, AuthRelayReadScope);
   const canWriteRelay = useEnvironmentScope(environmentId, AuthRelayWriteScope);
-  // Creating a pairing code needs write access, and showing it needs read access.
-  const canReadAccess = useEnvironmentScope(environmentId, AuthAccessReadScope);
-  const canWriteAccess = useEnvironmentScope(environmentId, AuthAccessWriteScope);
-  const phonePath = welcomePhonePath({
+  const showPhone = welcomeOffersPhone({
     isPrimary,
     cloud: hasCloudPublicConfig(),
     canShare: canReadRelay && canWriteRelay,
-    canPair: canReadAccess && canWriteAccess,
     policy: useManagedPolicy(environmentId),
   });
   const scans = useProjectScans([environmentId]);
@@ -294,9 +288,7 @@ export function WelcomePage({
                 projectImport={projectImport}
                 isImporting={isImporting}
               />
-              {phonePath === null ? null : (
-                <PhoneSection environmentId={environmentId} path={phonePath} />
-              )}
+              {showPhone ? <PhoneSection environmentId={environmentId} /> : null}
             </div>
             <div className="mt-6 flex flex-wrap items-center justify-between gap-3">
               {agentReady ? (
@@ -914,13 +906,7 @@ function ProjectsSection({
   );
 }
 
-function PhoneSection({
-  environmentId,
-  path,
-}: {
-  readonly environmentId: EnvironmentId;
-  readonly path: "connect" | "pairing";
-}) {
+function PhoneSection({ environmentId }: { readonly environmentId: EnvironmentId }) {
   const [open, setOpen] = useState(false);
   return (
     <WelcomeSection title="Phone">
@@ -944,16 +930,7 @@ function PhoneSection({
                 <p className="text-sm text-foreground">Scan with your phone to get the app.</p>
               </PhoneStep>
               <PhoneStep step={2}>
-                {path === "connect" ? (
-                  <PhoneConnectLink environmentId={environmentId} />
-                ) : (
-                  <>
-                    <p className="text-sm text-foreground">Pair the app with this computer.</p>
-                    <Button variant="outline" size="xs" render={<Link to="/settings/access" />}>
-                      Show pairing code
-                    </Button>
-                  </>
-                )}
+                <PhoneConnectLink environmentId={environmentId} />
               </PhoneStep>
             </ol>
             {/* One code for both stores: the link opens the store that matches the phone. */}
diff --git a/apps/web/src/onboarding/welcomePage.logic.test.ts b/apps/web/src/onboarding/welcomePage.logic.test.ts
index dbf429b9c3282..d2e8600692945 100644
--- a/apps/web/src/onboarding/welcomePage.logic.test.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.test.ts
@@ -15,7 +15,7 @@ import {
   codexNeedsSetup,
   groupWelcomeAgents,
   turnedOnInstance,
-  welcomePhonePath,
+  welcomeOffersPhone,
 } from "./welcomePage.logic";
 
 function provider(name: string, overrides: Partial<ServerProvider> = {}): ServerProvider {
@@ -238,30 +238,28 @@ describe("codexCardProvider", () => {
   });
 });
 
-describe("welcomePhonePath", () => {
-  it("offers T3 Connect or a pairing code only for the primary computer and only when allowed", () => {
+describe("welcomeOffersPhone", () => {
+  it("offers the phone only through T3 Connect on the primary computer, and only when allowed", () => {
     const policy = (limits: ManagedPolicySummary["limits"]): ManagedPolicySummary => ({
       organization: "Acme",
       lockedSettings: [],
       ...(limits === undefined ? {} : { limits }),
     });
-    const path = (input: Partial<Parameters<typeof welcomePhonePath>[0]>) =>
-      welcomePhonePath({
+    const offers = (input: Partial<Parameters<typeof welcomeOffersPhone>[0]>) =>
+      welcomeOffersPhone({
         isPrimary: true,
         cloud: true,
         canShare: true,
-        canPair: true,
         policy: undefined,
         ...input,
       });
 
-    expect(path({})).toBe("connect");
-    expect(path({ cloud: false })).toBe("pairing");
-    expect(path({ canShare: false })).toBe("pairing");
-    // Without access to share or to create a pairing code, the phone has no way in.
-    expect(path({ canShare: false, canPair: false })).toBeNull();
-    expect(path({ policy: policy({ connect: false }) })).toBe("pairing");
-    expect(path({ policy: policy({ clients: ["desktop"] }) })).toBeNull();
-    expect(path({ isPrimary: false })).toBeNull();
+    expect(offers({})).toBe(true);
+    // There is no pairing-code fallback; without T3 Connect the page leaves the phone out.
+    expect(offers({ cloud: false })).toBe(false);
+    expect(offers({ canShare: false })).toBe(false);
+    expect(offers({ policy: policy({ connect: false }) })).toBe(false);
+    expect(offers({ policy: policy({ clients: ["desktop"] }) })).toBe(false);
+    expect(offers({ isPrimary: false })).toBe(false);
   });
 });
diff --git a/apps/web/src/onboarding/welcomePage.logic.ts b/apps/web/src/onboarding/welcomePage.logic.ts
index fa330c9a8b979..acde259ad0d5d 100644
--- a/apps/web/src/onboarding/welcomePage.logic.ts
+++ b/apps/web/src/onboarding/welcomePage.logic.ts
@@ -138,29 +138,23 @@ export function codexNeedsSetup(
 }
 
 /**
- * How the Welcome page offers the phone: T3 Connect sign-in, a pairing code, or not at all.
- * Both act on the primary computer, so another computer gets neither.
+ * The phone joins by signing in to T3 Connect, which shares the primary computer. Another
+ * computer, a build without T3 Connect, or a policy that turns it off gets no Phone section.
  */
-export function welcomePhonePath(input: {
+export function welcomeOffersPhone(input: {
   readonly isPrimary: boolean;
   readonly cloud: boolean;
   // Relay read and write access, which sharing this computer through T3 Connect needs.
   readonly canShare: boolean;
-  // Access to create a pairing code, as in Settings → Sharing & access.
-  readonly canPair: boolean;
   readonly policy: ManagedPolicySummary | undefined;
 }) {
-  if (!input.isPrimary || managedCapabilityDenial(input.policy, "remoteClients") !== undefined) {
-    return null;
-  }
-  if (
+  return (
+    input.isPrimary &&
     input.cloud &&
     input.canShare &&
+    managedCapabilityDenial(input.policy, "remoteClients") === undefined &&
     managedCapabilityDenial(input.policy, "connect") === undefined
-  ) {
-    return "connect";
-  }
-  return input.canPair ? "pairing" : null;
+  );
 }
 
 /**
diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 8f26deedcd8a6..0c1935b89bfe9 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -58,9 +58,9 @@ iPhone and Google Play on Android. Then select **Sign in to T3 Connect** and all
 this computer when T3 Code asks, so the app can reach it. Sign in to the app with
 the same account. If you are signed in but this computer is not shared yet, select
 **Set up T3 Connect**. If T3 Connect is on but the app cannot reach this computer,
-select **Check T3 Connect** to see why. On builds without T3 Connect, or when your
-organization turns it off, select **Show pairing code** to pair the app from
-**Settings → Sharing & access**.
+select **Check T3 Connect** to see why. The page leaves the phone out on builds
+without T3 Connect, or when your organization turns it off. You can still pair the
+app with a code from **Settings → Sharing & access**.
 
 ## Projects
 

From 0afca2a16bf37ce678e38541b61394259f91b4da Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Mon, 9 Nov 2026 04:05:47 -0800
Subject: [PATCH 21/22] fix(web): a retried Welcome import still counts threads
 it already imported

A second Start after a failed setup save skipped the finished projects
and reset the thread count, so the success toast showed too few threads
or none. The page now keeps the count per project. Also drops a test
assertion that only checked callback wiring.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../WelcomePage.import.browser.test.tsx       |  8 +++++
 .../src/components/onboarding/WelcomePage.tsx | 33 ++++++++++---------
 .../AddCodexAccountDialog.browser.test.tsx    |  1 -
 3 files changed, 26 insertions(+), 16 deletions(-)

diff --git a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
index 236e0c80f3ff5..d8099e3907bfb 100644
--- a/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.import.browser.test.tsx
@@ -152,6 +152,7 @@ vi.mock(import("../../state/use-atom-command"), async (original) => ({
 
 import { welcomeImportSelectionKey } from "../../onboarding/welcomeState";
 import { appAtomRegistry } from "../../rpc/atomRegistry";
+import { toastManager } from "../ui/toast";
 import { WelcomePage } from "./WelcomePage";
 
 const primaryId = EnvironmentId.make("primary");
@@ -382,6 +383,7 @@ it("finishes setup without landing when the imported project never reaches the c
   state.waitForProject.mockRejectedValue(new Error("The project did not appear."));
   state.completeOnboarding.mockRejectedValueOnce(new Error("offline"));
   await using _screen = await mountWelcome();
+  using toastAdd = vi.spyOn(toastManager, "add");
 
   await click("Import 1 project and start");
   await vi.waitFor(() => expect(state.completeOnboarding).toHaveBeenCalledOnce());
@@ -392,6 +394,12 @@ it("finishes setup without landing when the imported project never reaches the c
   await click("Import 1 project and start");
   await vi.waitFor(() => expect(state.onDone).toHaveBeenCalledOnce());
   expect(state.onDone).toHaveBeenCalledWith(undefined);
+  // The retry skips the project it already imported, but still counts its thread.
+  await vi.waitFor(() =>
+    expect(toastAdd).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "success", title: "Imported 1 thread" }),
+    ),
+  );
 });
 
 it("waits for a ready agent to start, and Start without an agent still finishes setup", async () => {
diff --git a/apps/web/src/components/onboarding/WelcomePage.tsx b/apps/web/src/components/onboarding/WelcomePage.tsx
index 8340170b31175..48171ccf94457 100644
--- a/apps/web/src/components/onboarding/WelcomePage.tsx
+++ b/apps/web/src/components/onboarding/WelcomePage.tsx
@@ -1382,7 +1382,8 @@ function useProjectImport({
   const createProject = useAtomCommand(projectEnvironment.create, { reportFailure: false });
   const importThreads = useAtomCommand(agentSessionImport, { reportFailure: false });
   const importWarningRef = useRef("");
-  const importedThreadCountRef = useRef(0);
+  // Per project, so a retry that skips finished projects still counts their threads.
+  const importedThreadsRef = useRef(new Map<string, number>());
   const importedProjectsRef = useRef(new Map<string, ScopedProjectRef>());
   const projectsWithImportedHistoryRef = useRef(new Map<string, ScopedProjectRef>());
   const lastImportSelectionRef = useRef<ReadonlyArray<string>>([]);
@@ -1438,6 +1439,12 @@ function useProjectImport({
   );
   const visibleImportError = canWrite && canImport ? "" : IMPORT_PERMISSION_MESSAGE;
 
+  const importedThreadTotal = () =>
+    lastImportSelectionRef.current.reduce(
+      (total, key) => total + (importedThreadsRef.current.get(key) ?? 0),
+      0,
+    );
+
   const finishAfterImport = () => {
     const projectRef = resolveOnboardingLandingProject(
       lastImportSelectionRef.current,
@@ -1447,11 +1454,9 @@ function useProjectImport({
     // Busy until setup is saved, so Start cannot run the import again meanwhile.
     setIsImporting(true);
     if (projectRef === undefined) {
-      void onDone(undefined, importWarningRef.current, importedThreadCountRef.current).then(
-        (completed) => {
-          if (!completed) setIsImporting(false);
-        },
-      );
+      void onDone(undefined, importWarningRef.current, importedThreadTotal()).then((completed) => {
+        if (!completed) setIsImporting(false);
+      });
       return;
     }
     holdPageRef.current = true;
@@ -1468,11 +1473,7 @@ function useProjectImport({
           holdPageRef.current = false;
           return;
         }
-        const completed = await onDone(
-          landing,
-          importWarningRef.current,
-          importedThreadCountRef.current,
-        );
+        const completed = await onDone(landing, importWarningRef.current, importedThreadTotal());
         if (!completed) setIsImporting(false);
       });
   };
@@ -1491,16 +1492,15 @@ function useProjectImport({
     }
     setIsImporting(true);
     importWarningRef.current = "";
-    importedThreadCountRef.current = 0;
     lastImportSelectionRef.current = selection.map((candidate) => candidate.key);
     const importGeneration = importGenerationRef.current;
+    const importedThreads = importedThreadsRef.current;
     const importedProjects = importedProjectsRef.current;
     const projectAttempts = projectAttemptsRef.current;
     let importedProjectsCount =
       importedProjects.size > 0
         ? selection.filter((candidate) => importedProjects.has(candidate.key)).length
         : 0;
-    let importedThreadCount = 0;
     let skippedThreadCount = 0;
     const refreshEnvironments = new Set<EnvironmentId>();
     // Resolves false when the run stopped early: a newer run, an unmount, or lost access.
@@ -1556,7 +1556,10 @@ function useProjectImport({
         });
         if (importGeneration !== importGenerationRef.current) return false;
         if (threadImportResult._tag === "Success") {
-          importedThreadCount += threadImportResult.value.importedCount;
+          importedThreads.set(
+            candidate.key,
+            (importedThreads.get(candidate.key) ?? 0) + threadImportResult.value.importedCount,
+          );
           skippedThreadCount += threadImportResult.value.skippedCount;
           if (threadImportResult.value.importedCount > 0) {
             projectsWithImportedHistoryRef.current.set(
@@ -1584,7 +1587,7 @@ function useProjectImport({
       if (refreshEnvironments.has(scan.environmentId)) scan.refresh();
     }
     setIsImporting(false);
-    importedThreadCountRef.current = importedThreadCount;
+    const importedThreadCount = importedThreadTotal();
     if (importedProjectsCount < selection.length) {
       if (importedThreadCount > 0 && skippedThreadCount > 0) {
         importWarningRef.current = `Imported ${importedThreadCount} ${importedThreadCount === 1 ? "thread" : "threads"}. ${skippedThreadCount} ${skippedThreadCount === 1 ? "thread" : "threads"} could not be imported.`;
diff --git a/apps/web/src/components/settings/AddCodexAccountDialog.browser.test.tsx b/apps/web/src/components/settings/AddCodexAccountDialog.browser.test.tsx
index 9539988f4afe0..c7c223c656e37 100644
--- a/apps/web/src/components/settings/AddCodexAccountDialog.browser.test.tsx
+++ b/apps/web/src/components/settings/AddCodexAccountDialog.browser.test.tsx
@@ -116,7 +116,6 @@ describe("AddCodexAccountDialog", () => {
 
     await userEvent.click(page.getByRole("button", { name: "Continue" }));
     const instanceId = createdInstanceId();
-    expect(onAccountCreated).toHaveBeenCalledWith(instanceId, expect.any(String));
     await act(() => registry.set(atom, [codexProvider(instanceId, { status: "unauthenticated" })]));
     // Telling the owner about the account does not skip the dialog's own sign-in.
     await expect.element(page.getByText("Sign in to ChatGPT")).toBeVisible();

From f997129386506484c955b166bf53de89f4ff1e04 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@theo.li>
Date: Mon, 9 Nov 2026 04:18:04 -0800
Subject: [PATCH 22/22] docs(web): the import record limit applies to each
 conversation

The import reads at most 100,000 records per conversation, and it skips a
larger one on every attempt. The guide listed that limit with the
per-attempt limits, which suggested opening the page again would continue it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/user/welcome-page.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/user/welcome-page.md b/docs/user/welcome-page.md
index 0c1935b89bfe9..f280ace079147 100644
--- a/docs/user/welcome-page.md
+++ b/docs/user/welcome-page.md
@@ -97,14 +97,14 @@ same user turn. Ambiguous legacy or response-only context stays in the imported
 conversation so T3 Code does not remove user text. It reads one conversation at
 a time and skips files larger than 4 GiB. It also skips a conversation when the
 message text and metadata it keeps need more than 32 MiB of memory. Tool output
-does not count toward that limit. It ignores malformed records and skips
-unreadable or unparseable conversations.
-
-Each import attempt reads up to 100 conversation files and 4 GiB per project,
-with up to 100,000 input records. To continue a large batch, open the Welcome page again
-and pick the project in **Review all**.
-Completed conversations are not imported again. You can continue without the
-remaining history.
+does not count toward that limit. It skips a conversation with more than 100,000
+records every time, so opening the page again does not import it. It ignores
+malformed records and skips unreadable or unparseable conversations.
+
+Each import attempt reads up to 100 conversation files and 4 GiB per project. To
+continue a large batch, open the Welcome page again and pick the project in
+**Review all**. Completed conversations are not imported again. You can continue
+without the remaining history.
 
 You can start without importing. While an import runs, T3 Code stays on the
 Welcome page. If you quit, open the Welcome page again from **Settings → About**; the