diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 1ae71af0..342d542b 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -89,6 +89,7 @@ import {
   type PendingUserInputDraftAnswer,
 } from "../pendingUserInput";
 import {
+  selectEnvironmentState,
   selectProjectsAcrossEnvironments,
   selectThreadsAcrossEnvironments,
   selectWorkspaceProjectsAcrossEnvironments,
@@ -193,6 +194,9 @@ import { ExpandedImageDialog } from "./chat/ExpandedImageDialog";
 import { PullRequestThreadDialog } from "./PullRequestThreadDialog";
 import { MessagesTimeline, type TimelineProposedPlanState } from "./chat/MessagesTimeline";
 import { DraftEmptyState } from "./chat/DraftEmptyState";
+import { FirstRunSetupCard, useFirstRunSetupDismissal } from "./chat/FirstRunSetupCard";
+import { shouldShowFirstRunSetupCard } from "./chat/firstRunSetup";
+import { isHostedStaticApp } from "../hostedPairing";
 import { ProviderModelPicker } from "./chat/ProviderModelPicker";
 import { ChatHeader, type ForkHeaderContext } from "./chat/ChatHeader";
 import type { DesktopPreviewPickedElement } from "@threadlines/contracts";
@@ -3359,6 +3363,80 @@ export default function ChatView(props: ChatViewProps) {
     [activeProviderDriver, activeProviderLabel, providerAuthReconnectPrompt, runProjectScript],
   );
 
+  // --- First-run setup card -------------------------------------------------
+  // A cold install has no threads and no guidance, so the draft thread's empty
+  // state becomes the setup checklist until the user sends something or skips.
+  // Hosted phone/browser sessions are excluded: they have their own pairing
+  // states and no local provider they could sign in to from here.
+  const isHostedStaticSurface = useMemo(() => isHostedStaticApp(), []);
+  const { isDismissed: isFirstRunSetupDismissed, dismiss: dismissFirstRunSetupForEnvironment } =
+    useFirstRunSetupDismissal(draftThread?.environmentId ?? environmentId);
+  const hasUserMessagedThread = useStore((state) => {
+    const environmentState = selectEnvironmentState(state, environmentId);
+    return environmentState.threadIds.some(
+      (candidateThreadId) =>
+        environmentState.sidebarThreadSummaryById[candidateThreadId]?.latestUserMessageAt != null,
+    );
+  });
+  const isEnvironmentBootstrapComplete = useStore(
+    (state) => selectEnvironmentState(state, environmentId).bootstrapComplete,
+  );
+  const showFirstRunSetupCard = shouldShowFirstRunSetupCard({
+    isHostedStatic: isHostedStaticSurface,
+    isDraftThread: isLocalDraftThread && draftThread !== undefined,
+    isGeneralChat: isGeneralChatThread,
+    bootstrapComplete: isEnvironmentBootstrapComplete,
+    hasUserMessagedThread,
+    isDismissed: isFirstRunSetupDismissed,
+  });
+  const firstRunWorkspaceProjects = useMemo(
+    () => allProjects.filter((project) => project.kind !== "general-chat"),
+    [allProjects],
+  );
+  // A reloaded draft thread has no project bound yet (`activeProject` is
+  // null until the first send), but the bootstrapped workspace project is
+  // already in the project list; the card must not claim "No folder yet"
+  // while the sidebar shows one. General Chat can't be the active project
+  // here because the card never renders on General Chat drafts.
+  const firstRunProject = activeProject ?? firstRunWorkspaceProjects[0] ?? null;
+  const firstRunSetupEmptyState = useMemo(() => {
+    if (!showFirstRunSetupCard) {
+      return undefined;
+    }
+    return (
+      <FirstRunSetupCard
+        providers={providerInstanceEntries}
+        projectName={firstRunProject?.name ?? null}
+        projectCwd={firstRunProject?.cwd ?? null}
+        projectEnvironmentId={firstRunProject?.environmentId ?? environmentId}
+        isOnlyWorkspaceProject={firstRunWorkspaceProjects.length === 1}
+        onSignIn={(row) => {
+          if (!row.signInCommand) return;
+          void runProviderAuthReconnect({
+            provider: row.driverKind,
+            command: row.signInCommand,
+            message: `${row.name} is not signed in.`,
+          });
+        }}
+        onChooseProject={() => useCommandPaletteStore.getState().openAddProject()}
+        onSkip={dismissFirstRunSetupForEnvironment}
+        onStart={() => {
+          dismissFirstRunSetupForEnvironment();
+          scheduleComposerFocus();
+        }}
+      />
+    );
+  }, [
+    dismissFirstRunSetupForEnvironment,
+    environmentId,
+    firstRunProject,
+    firstRunWorkspaceProjects.length,
+    providerInstanceEntries,
+    runProviderAuthReconnect,
+    scheduleComposerFocus,
+    showFirstRunSetupCard,
+  ]);
+
   const runMcpAuthReconnect = useCallback(
     async (action: McpAuthReconnectAction) => {
       if (action.provider !== CODEX_PROVIDER_DRIVER) {
@@ -4436,6 +4514,12 @@ export default function ChatView(props: ChatViewProps) {
       return;
     }
 
+    // Sending is completing setup: the card has served its purpose and must
+    // not reappear behind the conversation the user just started.
+    if (showFirstRunSetupCard) {
+      dismissFirstRunSetupForEnvironment();
+    }
+
     sendInFlightRef.current = true;
     if (!isSteeringFollowUp) {
       beginLocalDispatch({ preparingWorktree: Boolean(baseBranchForWorktree) });
@@ -5156,9 +5240,13 @@ export default function ChatView(props: ChatViewProps) {
   const providerStatusNotice = useProviderStatusNotice({
     status: activeProviderStatus,
     activeTurnInProgress,
+    // The held-send notice and the setup card each already state this
+    // provider's problem with the actions that fix it; a second ambient row
+    // saying it again is the stacking noise the dock exists to end.
     suppressed:
-      providerSendPreflight !== null &&
-      providerSendPreflight.instanceId === activeProviderStatus?.instanceId,
+      showFirstRunSetupCard ||
+      (providerSendPreflight !== null &&
+        providerSendPreflight.instanceId === activeProviderStatus?.instanceId),
   });
   const sessionStartupNotice = useSessionStartupNotice({
     isSessionStarting,
@@ -6368,7 +6456,7 @@ export default function ChatView(props: ChatViewProps) {
             {/* Messages — LegendList handles virtualization and scrolling internally */}
             <MessagesTimeline
               key={activeThread.id}
-              emptyState={draftTimelineEmptyState}
+              emptyState={firstRunSetupEmptyState ?? draftTimelineEmptyState}
               isWorking={isWorking}
               activeStatusLabel={activeStatusLabel}
               activeTurnInProgress={isWorking || !latestTurnSettled}
diff --git a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts
index 1b79926f..7eaa2784 100644
--- a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts
+++ b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts
@@ -302,7 +302,7 @@ describe("provider update launch notification logic", () => {
       phase: "initial",
       type: "warning",
       title: "Updates available",
-      description: "Codex and Claude can be updated.",
+      description: "Codex v1.1.0 and Claude v2.1.197 can be updated.",
     });
   });
 
@@ -315,7 +315,9 @@ describe("provider update launch notification logic", () => {
       oneClickProviders: [],
     });
 
-    expect(view.description).toBe("Codex and Cursor can be updated from provider settings.");
+    expect(view.description).toBe(
+      "Codex v1.1.0 and Cursor v1.1.0 can be updated from provider settings.",
+    );
   });
 
   it("uses server update state for running progress", () => {
diff --git a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
index 840dfc48..572b1836 100644
--- a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
+++ b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
@@ -235,6 +235,22 @@ export function formatProviderList(providers: ReadonlyArray<Pick<ServerProvider,
   return `${names.slice(0, -1).join(", ")}, and ${names[names.length - 1]}`;
 }
 
+/**
+ * Like `formatProviderList` but with each provider's target version, so the
+ * multi-provider update card says what it will install without growing past
+ * one line: "Claude v2.1.230 and Codex v0.146.1".
+ */
+export function formatProviderUpdateList(providers: ReadonlyArray<ProviderUpdateCandidate>) {
+  const names = providers.map(
+    (provider) =>
+      `${getProviderDisplayName(provider)} ${formatVersion(provider.versionAdvisory.latestVersion)}`,
+  );
+  if (names.length <= 2) {
+    return names.join(" and ");
+  }
+  return `${names.slice(0, -1).join(", ")}, and ${names[names.length - 1]}`;
+}
+
 export function getProviderUpdateInitialToastView(input: {
   readonly updateProviders: ReadonlyArray<ProviderUpdateCandidate>;
   readonly oneClickProviders: ReadonlyArray<ProviderUpdateCandidate>;
@@ -247,9 +263,9 @@ export function getProviderUpdateInitialToastView(input: {
     description:
       input.oneClickProviders.length > 0
         ? hasMultipleProviders
-          ? `${formatProviderList(input.updateProviders)} can be updated.`
+          ? `${formatProviderUpdateList(input.updateProviders)} can be updated.`
           : "Install the update now or review provider settings."
-        : `${formatProviderList(input.updateProviders)} can be updated from provider settings.`,
+        : `${formatProviderUpdateList(input.updateProviders)} can be updated from provider settings.`,
   };
 }
 
diff --git a/apps/web/src/components/ThreadlinesFigure.tsx b/apps/web/src/components/ThreadlinesFigure.tsx
index 30a4a97d..e4f70fa4 100644
--- a/apps/web/src/components/ThreadlinesFigure.tsx
+++ b/apps/web/src/components/ThreadlinesFigure.tsx
@@ -6,12 +6,28 @@ export function riseDelay(delay: string): React.CSSProperties {
 
 /* Decorative thread graph: branches draw themselves in, commits surface
    left-to-right, and the one still-open branch ends on a live accent node. */
-export function ThreadlinesFigure() {
+export function ThreadlinesFigure({
+  /**
+   * Two-thirds scale with tighter margins, for surfaces that put content
+   * under the figure (the setup card) rather than existing around it.
+   */
+  compact = false,
+}: {
+  compact?: boolean;
+} = {}) {
   return (
-    <div aria-hidden="true" className="no-thread-rise relative mb-7" style={riseDelay("0.05s")}>
+    <div
+      aria-hidden="true"
+      className={compact ? "no-thread-rise relative mb-4" : "no-thread-rise relative mb-7"}
+      style={riseDelay("0.05s")}
+    >
       <div className="pointer-events-none absolute -inset-x-14 -inset-y-8 rounded-full bg-primary-graph/[0.05] blur-2xl dark:bg-primary-graph/[0.07]" />
       <svg
-        className="relative h-auto w-[300px] sm:w-[336px] lg:w-[384px]"
+        className={
+          compact
+            ? "relative h-auto w-[200px] sm:w-[224px]"
+            : "relative h-auto w-[300px] sm:w-[336px] lg:w-[384px]"
+        }
         fill="none"
         viewBox="0 0 360 120"
       >
diff --git a/apps/web/src/components/chat/FirstRunSetupCard.browser.tsx b/apps/web/src/components/chat/FirstRunSetupCard.browser.tsx
new file mode 100644
index 00000000..a5f33ef0
--- /dev/null
+++ b/apps/web/src/components/chat/FirstRunSetupCard.browser.tsx
@@ -0,0 +1,220 @@
+import "../../index.css";
+
+import {
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerProvider,
+} from "@threadlines/contracts";
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+  RouterProvider,
+} from "@tanstack/react-router";
+import { page } from "vite-plus/test/browser";
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
+import { render } from "vitest-browser-react";
+
+import { FirstRunSetupCard } from "./FirstRunSetupCard";
+import type { FirstRunProviderRow, FirstRunSetupProvider } from "./firstRunSetup";
+
+function buildProvider(input: {
+  readonly instanceId: string;
+  readonly driver: string;
+  readonly displayName: string;
+  readonly installed: boolean;
+  readonly version: string | null;
+  readonly auth: ServerProvider["auth"];
+}): FirstRunSetupProvider {
+  const driverKind = ProviderDriverKind.make(input.driver);
+  const snapshot: ServerProvider = {
+    driver: driverKind,
+    instanceId: ProviderInstanceId.make(input.instanceId),
+    displayName: input.displayName,
+    enabled: true,
+    installed: input.installed,
+    version: input.version,
+    status: input.installed ? "ready" : "error",
+    auth: input.auth,
+    checkedAt: new Date("2026-01-01T00:00:00.000Z").toISOString(),
+    models: [],
+    slashCommands: [],
+    skills: [],
+  };
+  return {
+    instanceId: snapshot.instanceId,
+    driverKind,
+    displayName: input.displayName,
+    enabled: true,
+    snapshot,
+  };
+}
+
+const SIGNED_OUT_CODEX = buildProvider({
+  instanceId: "codex",
+  driver: "codex",
+  displayName: "Codex",
+  installed: true,
+  version: "0.146.1",
+  auth: { status: "unauthenticated" },
+});
+
+const MISSING_CLAUDE = buildProvider({
+  instanceId: "claudeAgent",
+  driver: "claudeAgent",
+  displayName: "Claude",
+  installed: false,
+  version: null,
+  auth: { status: "unknown" },
+});
+
+const SIGNED_IN_CLAUDE = buildProvider({
+  instanceId: "claudeAgent",
+  driver: "claudeAgent",
+  displayName: "Claude",
+  installed: true,
+  version: "2.4.0",
+  auth: { status: "authenticated", label: "Claude Max" },
+});
+
+/**
+ * The install-guide action is a router `Link`, so every case mounts through a
+ * throwaway memory router rather than special-casing one test.
+ */
+function renderCard(props: {
+  readonly providers: ReadonlyArray<FirstRunSetupProvider>;
+  readonly projectName: string | null;
+  readonly onSignIn?: (row: FirstRunProviderRow) => void;
+  readonly onChooseProject?: () => void;
+  readonly onSkip?: () => void;
+  readonly onStart?: () => void;
+}) {
+  const rootRoute = createRootRoute({
+    component: () => (
+      <FirstRunSetupCard
+        providers={props.providers}
+        projectName={props.projectName}
+        projectCwd={props.projectName === null ? null : "C:/code/B-git-project"}
+        projectEnvironmentId={null}
+        isOnlyWorkspaceProject
+        onSignIn={props.onSignIn ?? vi.fn()}
+        onChooseProject={props.onChooseProject ?? vi.fn()}
+        onSkip={props.onSkip ?? vi.fn()}
+        onStart={props.onStart ?? vi.fn()}
+      />
+    ),
+  });
+  const indexRoute = createRoute({ getParentRoute: () => rootRoute, path: "/" });
+  const providersRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: "/settings/providers",
+  });
+  const router = createRouter({
+    routeTree: rootRoute.addChildren([indexRoute, providersRoute]),
+    history: createMemoryHistory({ initialEntries: ["/"] }),
+  });
+
+  return render(<RouterProvider router={router} />);
+}
+
+function rowStates(): Record<string, string> {
+  return Object.fromEntries(
+    Array.from(document.querySelectorAll("[data-testid='first-run-setup-row']")).map((row) => [
+      row.getAttribute("data-row-id") ?? "",
+      row.getAttribute("data-row-state") ?? "",
+    ]),
+  );
+}
+
+describe("FirstRunSetupCard", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("gives every provider state its own dot and action, and holds the start button back", async () => {
+    const onSignIn = vi.fn();
+    const screen = await renderCard({
+      providers: [SIGNED_OUT_CODEX, MISSING_CLAUDE],
+      projectName: "B-git-project",
+      onSignIn,
+    });
+
+    expect(rowStates()).toEqual({
+      codex: "needsSignIn",
+      claudeAgent: "notInstalled",
+      project: "ready",
+    });
+
+    const dots = Array.from(document.querySelectorAll("[data-testid='first-run-setup-dot']"));
+    expect(dots.map((dot) => dot.getAttribute("data-row-state"))).toEqual([
+      "needsSignIn",
+      "notInstalled",
+      "ready",
+    ]);
+    // Amber for a fixable sign-in, red for a missing CLI, green for the folder.
+    expect(dots.map((dot) => dot.className)).toEqual([
+      expect.stringContaining("bg-warning"),
+      expect.stringContaining("bg-destructive"),
+      expect.stringContaining("bg-success"),
+    ]);
+
+    await expect
+      .element(page.getByText("B-git-project · the folder you launched from"))
+      .toBeVisible();
+    expect(
+      document.querySelector<HTMLAnchorElement>('a[href="/settings/providers"]')?.textContent,
+    ).toContain("Install guide");
+
+    await page.getByRole("button", { name: "Sign in to Codex" }).click();
+    expect(onSignIn).toHaveBeenCalledTimes(1);
+    expect(onSignIn.mock.calls[0]?.[0]).toMatchObject({
+      name: "Codex",
+      signInCommand: "codex login",
+    });
+
+    await expect.element(page.getByRole("button", { name: "Start first thread" })).toBeDisabled();
+
+    await screen.unmount();
+  });
+
+  it("enables the start action once one agent is signed in and a folder exists", async () => {
+    const onStart = vi.fn();
+    const onSkip = vi.fn();
+    const screen = await renderCard({
+      providers: [SIGNED_OUT_CODEX, SIGNED_IN_CLAUDE],
+      projectName: "B-git-project",
+      onStart,
+      onSkip,
+    });
+
+    expect(rowStates()).toMatchObject({ claudeAgent: "ready" });
+    await expect.element(page.getByText("Signed in · Claude Max")).toBeVisible();
+
+    await page.getByRole("button", { name: "Start first thread" }).click();
+    expect(onStart).toHaveBeenCalledTimes(1);
+
+    await page.getByRole("button", { name: "Skip for now" }).click();
+    expect(onSkip).toHaveBeenCalledTimes(1);
+
+    await screen.unmount();
+  });
+
+  it("asks for a folder, and stays disabled, when no project exists", async () => {
+    const onChooseProject = vi.fn();
+    const screen = await renderCard({
+      providers: [SIGNED_IN_CLAUDE],
+      projectName: null,
+      onChooseProject,
+    });
+
+    expect(rowStates()).toMatchObject({ project: "missing" });
+
+    await page.getByRole("button", { name: "Choose a folder" }).click();
+    expect(onChooseProject).toHaveBeenCalledTimes(1);
+
+    await expect.element(page.getByRole("button", { name: "Start first thread" })).toBeDisabled();
+
+    await screen.unmount();
+  });
+});
diff --git a/apps/web/src/components/chat/FirstRunSetupCard.tsx b/apps/web/src/components/chat/FirstRunSetupCard.tsx
new file mode 100644
index 00000000..0a137b69
--- /dev/null
+++ b/apps/web/src/components/chat/FirstRunSetupCard.tsx
@@ -0,0 +1,296 @@
+/**
+ * The first thing a brand-new install sees, in place of the empty draft
+ * thread's usual "What's next in ...?" prompt.
+ *
+ * It is the same provider data the settings page shows, with the fix action on
+ * the row instead of two clicks away, plus the folder the server bootstrapped
+ * from. Rows are live: provider snapshots stream in over providers-updated
+ * events, so a dot flips from amber to green while the sign-in terminal is
+ * still open, and "Start first thread" enables at the same moment.
+ *
+ * No container: typography, spacing, and hairline dividers on the empty
+ * canvas, matching the rest of the app.
+ *
+ * @module FirstRunSetupCard
+ */
+import type { EnvironmentId } from "@threadlines/contracts";
+import { Link } from "@tanstack/react-router";
+import { useCallback, useMemo, useState, type ReactNode } from "react";
+
+import { cn } from "../../lib/utils";
+import { ProjectFavicon } from "../ProjectFavicon";
+import { riseDelay, ThreadlinesFigure } from "../ThreadlinesFigure";
+import { Button } from "../ui/button";
+import {
+  buildFirstRunSetupDismissalKey,
+  canStartFirstThread,
+  deriveFirstRunProjectRow,
+  deriveFirstRunProviderRows,
+  dismissFirstRunSetup,
+  groupFirstRunProviderRows,
+  isFirstRunSetupDismissed,
+  type FirstRunProviderRow,
+  type FirstRunSetupProvider,
+} from "./firstRunSetup";
+
+/**
+ * Reads the environment's dismissal once and re-reads it after this hook
+ * writes one, so "Skip for now" hides the card in the same tick. Callers that
+ * dismiss on another path (a send) go through the returned `dismiss` too,
+ * which keeps the render in step with storage.
+ */
+export function useFirstRunSetupDismissal(environmentId: EnvironmentId | null | undefined): {
+  readonly isDismissed: boolean;
+  readonly dismiss: () => void;
+} {
+  const dismissalKey = environmentId ? buildFirstRunSetupDismissalKey(environmentId) : null;
+  const [dismissedKeys, setDismissedKeys] = useState<ReadonlyArray<string>>(() =>
+    dismissalKey !== null && isFirstRunSetupDismissed(dismissalKey) ? [dismissalKey] : [],
+  );
+
+  const dismiss = useCallback(() => {
+    if (dismissalKey === null) {
+      return;
+    }
+    dismissFirstRunSetup(dismissalKey);
+    setDismissedKeys((current) =>
+      current.includes(dismissalKey) ? current : [...current, dismissalKey],
+    );
+  }, [dismissalKey]);
+
+  // Re-read storage when the key changes (environment switch) rather than on
+  // every render: this hook lives in the chat view's render path.
+  const isDismissed = useMemo(
+    () =>
+      dismissalKey !== null &&
+      (dismissedKeys.includes(dismissalKey) || isFirstRunSetupDismissed(dismissalKey)),
+    [dismissalKey, dismissedKeys],
+  );
+
+  return { isDismissed, dismiss };
+}
+
+function SetupRow({
+  rowId,
+  state,
+  dotClassName,
+  name,
+  versionLabel,
+  description,
+  action,
+}: {
+  rowId: string;
+  state: string;
+  dotClassName: string;
+  name: string;
+  versionLabel?: string | null;
+  description: ReactNode;
+  action: ReactNode;
+}) {
+  return (
+    <li
+      className="flex items-center gap-3 border-b border-border py-3.5"
+      data-testid="first-run-setup-row"
+      data-row-id={rowId}
+      data-row-state={state}
+    >
+      <span
+        aria-hidden
+        className={cn("size-2 shrink-0 rounded-full", dotClassName)}
+        data-testid="first-run-setup-dot"
+        data-row-state={state}
+      />
+      <span className="w-20 shrink-0 truncate text-sm font-medium text-foreground">{name}</span>
+      {versionLabel ? (
+        <span className="-ml-1.5 shrink-0 font-mono text-[11px] text-muted-foreground/62">
+          {versionLabel}
+        </span>
+      ) : null}
+      <span className="min-w-0 flex-1 text-[13px] text-muted-foreground">{description}</span>
+      <span className="shrink-0">{action}</span>
+    </li>
+  );
+}
+
+function providerRowAction(
+  row: FirstRunProviderRow,
+  onSignIn: (row: FirstRunProviderRow) => void,
+): ReactNode {
+  if (row.state === "ready") {
+    return null;
+  }
+  if (row.state === "needsSignIn" && row.signInCommand) {
+    return (
+      <Button
+        size="xs"
+        aria-label={`Sign in to ${row.name}`}
+        onClick={() => onSignIn(row)}
+        tooltip={`Runs ${row.signInCommand} in this thread's terminal`}
+      >
+        Sign in
+      </Button>
+    );
+  }
+  return (
+    <Button
+      size="xs"
+      variant="outline"
+      aria-label={`Open the ${row.name} install guide`}
+      render={<Link to="/settings/providers" />}
+    >
+      Install guide
+    </Button>
+  );
+}
+
+export interface FirstRunSetupCardProps {
+  /** Enabled and disabled instances alike; disabled ones are filtered out. */
+  readonly providers: ReadonlyArray<FirstRunSetupProvider>;
+  readonly projectName: string | null;
+  readonly projectCwd: string | null;
+  /** Where the project lives; lets the row show its favicon like every other project selector. */
+  readonly projectEnvironmentId: EnvironmentId | null;
+  /** True when this is the workspace's only project, i.e. the launch folder. */
+  readonly isOnlyWorkspaceProject: boolean;
+  readonly onSignIn: (row: FirstRunProviderRow) => void;
+  readonly onChooseProject: () => void;
+  readonly onSkip: () => void;
+  readonly onStart: () => void;
+}
+
+export function FirstRunSetupCard({
+  providers,
+  projectName,
+  projectCwd,
+  projectEnvironmentId,
+  isOnlyWorkspaceProject,
+  onSignIn,
+  onChooseProject,
+  onSkip,
+  onStart,
+}: FirstRunSetupCardProps) {
+  const providerRows = useMemo(() => deriveFirstRunProviderRows(providers), [providers]);
+  const providerRowGroups = useMemo(() => groupFirstRunProviderRows(providerRows), [providerRows]);
+  const projectRow = useMemo(
+    () => deriveFirstRunProjectRow({ projectName, projectCwd, isOnlyWorkspaceProject }),
+    [isOnlyWorkspaceProject, projectCwd, projectName],
+  );
+  const canStart = canStartFirstThread({ providerRows, projectRow });
+  const projectDescription: ReactNode =
+    projectRow.state === "ready" && projectCwd && projectEnvironmentId ? (
+      <span className="inline-flex min-w-0 items-center gap-1.5">
+        <ProjectFavicon cwd={projectCwd} environmentId={projectEnvironmentId} />
+        <span className="min-w-0 truncate">{projectRow.description}</span>
+      </span>
+    ) : (
+      projectRow.description
+    );
+
+  return (
+    <div
+      className="flex w-full max-w-140 flex-col items-center pb-10"
+      data-testid="first-run-setup-card"
+    >
+      <ThreadlinesFigure compact />
+      <h2
+        className="no-thread-rise text-[19px] font-semibold tracking-tight text-foreground"
+        style={riseDelay("0.16s")}
+      >
+        Set up Threadlines
+      </h2>
+      <p
+        className="no-thread-rise mt-1 text-[13.5px] text-muted-foreground"
+        style={riseDelay("0.24s")}
+      >
+        Connect a coding agent and pick a folder. Rows update live as you go.
+      </p>
+
+      <ul className="no-thread-rise mt-6 w-full border-t border-border" style={riseDelay("0.32s")}>
+        {providerRowGroups.visible.map((row) => (
+          <SetupRow
+            key={row.instanceId}
+            rowId={String(row.instanceId)}
+            state={row.state}
+            dotClassName={row.dotClassName}
+            name={row.name}
+            versionLabel={row.versionLabel}
+            description={row.description}
+            action={providerRowAction(row, onSignIn)}
+          />
+        ))}
+        {providerRowGroups.overflow ? (
+          <SetupRow
+            rowId="more-agents"
+            state="overflow"
+            dotClassName="bg-muted-foreground/55"
+            name="More agents"
+            description={`${providerRowGroups.overflow
+              .map((row) => row.name)
+              .join(", ")} · set up from Settings`}
+            action={
+              <Button
+                size="xs"
+                variant="outline"
+                aria-label="Open provider settings for more agents"
+                render={<Link to="/settings/providers" />}
+              >
+                Open Settings
+              </Button>
+            }
+          />
+        ) : null}
+        <SetupRow
+          rowId="project"
+          state={projectRow.state}
+          dotClassName={projectRow.dotClassName}
+          name="Project"
+          description={projectDescription}
+          action={
+            projectRow.state === "ready" ? (
+              <Button
+                size="xs"
+                variant="ghost"
+                className="text-muted-foreground hover:text-foreground"
+                onClick={onChooseProject}
+              >
+                {projectRow.actionLabel}
+              </Button>
+            ) : (
+              <Button size="xs" onClick={onChooseProject}>
+                {projectRow.actionLabel}
+              </Button>
+            )
+          }
+        />
+      </ul>
+
+      <div
+        className="no-thread-rise mt-5 flex w-full flex-wrap items-center justify-between gap-3"
+        style={riseDelay("0.4s")}
+      >
+        <span className="text-xs text-muted-foreground/62">
+          You can start once one agent is signed in.
+        </span>
+        <span className="flex items-center gap-1">
+          <Button
+            size="xs"
+            variant="ghost"
+            className="text-muted-foreground hover:text-foreground"
+            data-testid="first-run-setup-skip"
+            onClick={onSkip}
+          >
+            Skip for now
+          </Button>
+          <Button
+            size="xs"
+            disabled={!canStart}
+            data-testid="first-run-setup-start"
+            onClick={onStart}
+          >
+            Start first thread
+          </Button>
+        </span>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/chat/firstRunSetup.test.ts b/apps/web/src/components/chat/firstRunSetup.test.ts
new file mode 100644
index 00000000..5cb3c834
--- /dev/null
+++ b/apps/web/src/components/chat/firstRunSetup.test.ts
@@ -0,0 +1,227 @@
+import {
+  EnvironmentId,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerProvider,
+} from "@threadlines/contracts";
+import { beforeEach, describe, expect, it } from "vite-plus/test";
+
+import { removeLocalStorageItem } from "../../hooks/useLocalStorage";
+import {
+  buildFirstRunSetupDismissalKey,
+  canStartFirstThread,
+  deriveFirstRunProjectRow,
+  deriveFirstRunProviderRows,
+  dismissFirstRunSetup,
+  FIRST_RUN_SETUP_DISMISSALS_STORAGE_KEY,
+  groupFirstRunProviderRows,
+  isFirstRunSetupDismissed,
+  shouldShowFirstRunSetupCard,
+  type FirstRunSetupProvider,
+} from "./firstRunSetup";
+
+function provider(overrides: {
+  readonly instanceId: string;
+  readonly driver: string;
+  readonly displayName: string;
+  readonly enabled?: boolean;
+  readonly installed?: boolean;
+  readonly version?: string | null;
+  readonly auth?: ServerProvider["auth"];
+  readonly message?: string;
+}): FirstRunSetupProvider {
+  const driverKind = ProviderDriverKind.make(overrides.driver);
+  const snapshot: ServerProvider = {
+    driver: driverKind,
+    instanceId: ProviderInstanceId.make(overrides.instanceId),
+    displayName: overrides.displayName,
+    enabled: overrides.enabled ?? true,
+    installed: overrides.installed ?? true,
+    version: overrides.version ?? null,
+    status: "ready",
+    auth: overrides.auth ?? { status: "authenticated" },
+    checkedAt: new Date("2026-01-01T00:00:00.000Z").toISOString(),
+    slashCommands: [],
+    skills: [],
+    models: [],
+    ...(overrides.message ? { message: overrides.message } : {}),
+  };
+  return {
+    instanceId: snapshot.instanceId,
+    driverKind,
+    displayName: overrides.displayName,
+    enabled: snapshot.enabled,
+    snapshot,
+  };
+}
+
+const signedInCodex = provider({
+  instanceId: "codex",
+  driver: "codex",
+  displayName: "Codex",
+  version: "0.146.1",
+  auth: { status: "authenticated", label: "ChatGPT Plus Subscription" },
+});
+
+const signedOutCodex = provider({
+  instanceId: "codex",
+  driver: "codex",
+  displayName: "Codex",
+  version: "0.146.1",
+  auth: { status: "unauthenticated" },
+});
+
+const missingClaude = provider({
+  instanceId: "claudeAgent",
+  driver: "claudeAgent",
+  displayName: "Claude",
+  installed: false,
+  auth: { status: "unknown" },
+});
+
+const READY_PROJECT_ROW = deriveFirstRunProjectRow({
+  projectName: "B-git-project",
+  projectCwd: "C:/code/B-git-project",
+  isOnlyWorkspaceProject: true,
+});
+const MISSING_PROJECT_ROW = deriveFirstRunProjectRow({
+  projectName: null,
+  projectCwd: null,
+  isOnlyWorkspaceProject: false,
+});
+
+const SHOWN_INPUT = {
+  isHostedStatic: false,
+  isDraftThread: true,
+  isGeneralChat: false,
+  bootstrapComplete: true,
+  hasUserMessagedThread: false,
+  isDismissed: false,
+} as const;
+
+describe("shouldShowFirstRunSetupCard", () => {
+  it("shows on a cold draft thread that has never been messaged", () => {
+    expect(shouldShowFirstRunSetupCard(SHOWN_INPUT)).toBe(true);
+  });
+
+  it("hides once any thread in the environment carries a user message", () => {
+    expect(shouldShowFirstRunSetupCard({ ...SHOWN_INPUT, hasUserMessagedThread: true })).toBe(
+      false,
+    );
+  });
+
+  it("hides once dismissed", () => {
+    expect(shouldShowFirstRunSetupCard({ ...SHOWN_INPUT, isDismissed: true })).toBe(false);
+  });
+
+  it("never renders on hosted phone surfaces, general chat, or a server thread", () => {
+    expect(shouldShowFirstRunSetupCard({ ...SHOWN_INPUT, isHostedStatic: true })).toBe(false);
+    expect(shouldShowFirstRunSetupCard({ ...SHOWN_INPUT, isGeneralChat: true })).toBe(false);
+    expect(shouldShowFirstRunSetupCard({ ...SHOWN_INPUT, isDraftThread: false })).toBe(false);
+  });
+
+  it("waits for the environment bootstrap before deciding", () => {
+    expect(shouldShowFirstRunSetupCard({ ...SHOWN_INPUT, bootstrapComplete: false })).toBe(false);
+  });
+});
+
+describe("first-run setup dismissal", () => {
+  beforeEach(() => {
+    removeLocalStorageItem(FIRST_RUN_SETUP_DISMISSALS_STORAGE_KEY);
+  });
+
+  it("persists per environment", () => {
+    const local = buildFirstRunSetupDismissalKey(EnvironmentId.make("environment-local"));
+    const remote = buildFirstRunSetupDismissalKey(EnvironmentId.make("environment-remote"));
+
+    expect(isFirstRunSetupDismissed(local)).toBe(false);
+
+    dismissFirstRunSetup(local);
+
+    expect(isFirstRunSetupDismissed(local)).toBe(true);
+    expect(isFirstRunSetupDismissed(remote)).toBe(false);
+  });
+});
+
+describe("deriveFirstRunProviderRows", () => {
+  it("routes each provider state to its own dot, copy, and action affordance", () => {
+    const rows = deriveFirstRunProviderRows([signedOutCodex, missingClaude, signedInCodex]);
+
+    expect(rows.map((row) => row.state)).toEqual(["needsSignIn", "notInstalled", "ready"]);
+    expect(rows[0]?.signInCommand).toBe("codex login");
+    expect(rows[0]?.versionLabel).toBe("v0.146.1");
+    expect(rows[0]?.description).toContain("Not authenticated");
+    // Nothing to sign in to yet, so the row must not offer a login command.
+    expect(rows[1]?.signInCommand).toBeNull();
+    expect(rows[1]?.description).toContain("CLI not detected on PATH");
+    expect(rows[2]?.description).toBe("Signed in · ChatGPT Plus Subscription");
+    expect(new Set(rows.map((row) => row.dotClassName)).size).toBe(3);
+  });
+
+  it("leaves out instances the user disabled", () => {
+    const rows = deriveFirstRunProviderRows([{ ...signedInCodex, enabled: false }, missingClaude]);
+
+    expect(rows.map((row) => row.name)).toEqual(["Claude"]);
+  });
+
+  it("orders rows by actionability: sign-in, install, then ready", () => {
+    // Settings order is Claude-first here, but the checklist leads with the
+    // provider that is one browser window from working.
+    const rows = deriveFirstRunProviderRows([missingClaude, signedInCodex, signedOutCodex]);
+
+    expect(rows.map((row) => row.state)).toEqual(["needsSignIn", "notInstalled", "ready"]);
+  });
+
+  it("collapses providers past the visible cap into an overflow group", () => {
+    const rows = deriveFirstRunProviderRows([
+      signedOutCodex,
+      missingClaude,
+      provider({ instanceId: "cursor", driver: "cursor", displayName: "Cursor", installed: false }),
+      provider({ instanceId: "opencode", driver: "opencode", displayName: "OpenCode" }),
+    ]);
+    const groups = groupFirstRunProviderRows(rows);
+
+    expect(groups.visible).toHaveLength(3);
+    // Priority puts the ready OpenCode row last, so it is the one collapsed.
+    expect(groups.overflow?.map((row) => row.name)).toEqual(["OpenCode"]);
+  });
+
+  it("keeps every row visible while at or under the cap", () => {
+    const rows = deriveFirstRunProviderRows([signedOutCodex, missingClaude]);
+
+    expect(groupFirstRunProviderRows(rows)).toEqual({ visible: rows, overflow: null });
+  });
+});
+
+describe("deriveFirstRunProjectRow", () => {
+  it("claims the launch folder only for the workspace's sole project", () => {
+    expect(READY_PROJECT_ROW.description).toBe("B-git-project · the folder you launched from");
+    expect(
+      deriveFirstRunProjectRow({
+        projectName: "other",
+        projectCwd: "C:/code/other",
+        isOnlyWorkspaceProject: false,
+      }).description,
+    ).toBe("other · C:/code/other");
+  });
+
+  it("asks for a folder when there is none", () => {
+    expect(MISSING_PROJECT_ROW.state).toBe("missing");
+    expect(MISSING_PROJECT_ROW.actionLabel).toBe("Choose a folder");
+  });
+});
+
+describe("canStartFirstThread", () => {
+  it("stays disabled until a usable provider and a project both exist", () => {
+    const unusable = deriveFirstRunProviderRows([signedOutCodex, missingClaude]);
+    const usable = deriveFirstRunProviderRows([signedOutCodex, signedInCodex]);
+
+    expect(canStartFirstThread({ providerRows: unusable, projectRow: READY_PROJECT_ROW })).toBe(
+      false,
+    );
+    expect(canStartFirstThread({ providerRows: usable, projectRow: MISSING_PROJECT_ROW })).toBe(
+      false,
+    );
+    expect(canStartFirstThread({ providerRows: usable, projectRow: READY_PROJECT_ROW })).toBe(true);
+  });
+});
diff --git a/apps/web/src/components/chat/firstRunSetup.ts b/apps/web/src/components/chat/firstRunSetup.ts
new file mode 100644
index 00000000..b0092773
--- /dev/null
+++ b/apps/web/src/components/chat/firstRunSetup.ts
@@ -0,0 +1,343 @@
+/**
+ * First-run setup card: what it says, when it shows, and when it stops.
+ *
+ * A brand-new install lands on an empty draft thread with no guidance, even
+ * though the client already holds everything needed to tell the user what is
+ * missing: the provider snapshots Settings renders, and the project the server
+ * bootstrapped from the launch folder. This module turns those into the rows
+ * the card draws, decides whether the card belongs on screen at all, and owns
+ * the per-environment dismissal record.
+ *
+ * Status language is borrowed from the settings page (`getProviderSummary`)
+ * and the availability verdict from the model picker
+ * (`getModelPickerProviderAvailability`), so a provider is never described one
+ * way here and another way two clicks later.
+ *
+ * @module firstRunSetup
+ */
+import type {
+  EnvironmentId,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  ServerProvider,
+} from "@threadlines/contracts";
+import { providerAuthReconnectCommand } from "@threadlines/shared/providerAuth";
+import * as Schema from "effect/Schema";
+
+import {
+  getLocalStorageItemWithLegacyKeys,
+  setLocalStorageItem,
+} from "../../hooks/useLocalStorage";
+import {
+  getProviderSummary,
+  getProviderVersionLabel,
+  PROVIDER_STATUS_STYLES,
+} from "../settings/providerStatus";
+import { getModelPickerProviderAvailability } from "./modelPickerEmptyState";
+
+export const FIRST_RUN_SETUP_DISMISSALS_STORAGE_KEY = "threadlines:first-run-setup-dismissals:v1";
+/**
+ * Empty today: this key was minted after the t3code rename, so nothing
+ * predates it. Kept as the same shape the other dismissal records use so a
+ * future key bump migrates without restructuring the reader.
+ */
+const LEGACY_FIRST_RUN_SETUP_DISMISSALS_STORAGE_KEYS: readonly string[] = [];
+
+const FirstRunSetupDismissalsSchema = Schema.Struct({
+  keys: Schema.Array(Schema.String),
+});
+
+type FirstRunSetupDismissals = typeof FirstRunSetupDismissalsSchema.Type;
+
+export function buildFirstRunSetupDismissalKey(environmentId: EnvironmentId): string {
+  return String(environmentId);
+}
+
+function readFirstRunSetupDismissals(): FirstRunSetupDismissals {
+  try {
+    return (
+      getLocalStorageItemWithLegacyKeys(
+        FIRST_RUN_SETUP_DISMISSALS_STORAGE_KEY,
+        LEGACY_FIRST_RUN_SETUP_DISMISSALS_STORAGE_KEYS,
+        FirstRunSetupDismissalsSchema,
+      ) ?? { keys: [] }
+    );
+  } catch {
+    return { keys: [] };
+  }
+}
+
+function writeFirstRunSetupDismissals(document: FirstRunSetupDismissals): void {
+  try {
+    setLocalStorageItem(
+      FIRST_RUN_SETUP_DISMISSALS_STORAGE_KEY,
+      document,
+      FirstRunSetupDismissalsSchema,
+    );
+  } catch {
+    // Dismissal state is best-effort UI state; a storage failure must not
+    // block the surface the user just asked to leave.
+  }
+}
+
+export function isFirstRunSetupDismissed(dismissalKey: string | null | undefined): boolean {
+  if (!dismissalKey) {
+    return false;
+  }
+  return readFirstRunSetupDismissals().keys.includes(dismissalKey);
+}
+
+export function dismissFirstRunSetup(dismissalKey: string | null | undefined): void {
+  if (!dismissalKey) {
+    return;
+  }
+  const document = readFirstRunSetupDismissals();
+  if (document.keys.includes(dismissalKey)) {
+    return;
+  }
+  writeFirstRunSetupDismissals({ keys: [...document.keys, dismissalKey] });
+}
+
+/**
+ * The card takes over the draft thread's empty state only on a genuine cold
+ * start.
+ *
+ * Every clause is a reason the card would be noise: a hosted phone has its own
+ * pairing surface and no local provider to fix; General Chat has no project
+ * row to speak of; an environment still bootstrapping has not told us whether
+ * it has threads; an environment where someone has already sent a message is
+ * not a first run; and a dismissal is permanent.
+ */
+export function shouldShowFirstRunSetupCard(input: {
+  readonly isHostedStatic: boolean;
+  readonly isDraftThread: boolean;
+  readonly isGeneralChat: boolean;
+  readonly bootstrapComplete: boolean;
+  readonly hasUserMessagedThread: boolean;
+  readonly isDismissed: boolean;
+}): boolean {
+  return (
+    input.isDraftThread &&
+    !input.isHostedStatic &&
+    !input.isGeneralChat &&
+    input.bootstrapComplete &&
+    !input.hasUserMessagedThread &&
+    !input.isDismissed
+  );
+}
+
+/** What the user has to do next about one provider, if anything. */
+export type FirstRunProviderRowState = "ready" | "needsSignIn" | "notInstalled";
+
+/**
+ * The slice of a `ProviderInstanceEntry` a row needs. Declared structurally so
+ * entries pass through unchanged and tests can build a minimal fixture.
+ */
+export interface FirstRunSetupProvider {
+  readonly instanceId: ProviderInstanceId;
+  readonly driverKind: ProviderDriverKind;
+  readonly displayName: string;
+  readonly enabled: boolean;
+  readonly snapshot: ServerProvider;
+}
+
+export interface FirstRunProviderRow {
+  readonly instanceId: ProviderInstanceId;
+  readonly driverKind: ProviderDriverKind;
+  readonly name: string;
+  readonly versionLabel: string | null;
+  readonly description: string;
+  readonly state: FirstRunProviderRowState;
+  readonly dotClassName: string;
+  /**
+   * Terminal login command for this driver. Null when the driver has none, in
+   * which case the row falls back to the install guide rather than offering a
+   * sign-in that cannot run.
+   */
+  readonly signInCommand: string | null;
+}
+
+const PROVIDER_ROW_DOT_CLASS_NAMES: Record<FirstRunProviderRowState, string> = {
+  ready: PROVIDER_STATUS_STYLES.ready.dot,
+  needsSignIn: PROVIDER_STATUS_STYLES.warning.dot,
+  notInstalled: PROVIDER_STATUS_STYLES.error.dot,
+};
+
+function providerRowState(snapshot: ServerProvider): FirstRunProviderRowState {
+  switch (getModelPickerProviderAvailability(snapshot)) {
+    case "available":
+      return "ready";
+    case "notInstalled":
+      return "notInstalled";
+    case "notAuthenticated":
+      return "needsSignIn";
+  }
+}
+
+/**
+ * One line under the provider name. A signed-in provider names the account
+ * plan the snapshot reported and nothing more (we never invent account
+ * details); everything else reuses the settings page's headline and detail so
+ * the two surfaces agree, with an action clause when the server gave no
+ * detail of its own.
+ */
+function providerRowDescription(
+  provider: FirstRunSetupProvider,
+  state: FirstRunProviderRowState,
+): string {
+  if (state === "ready") {
+    const authLabel = provider.snapshot.auth.label ?? provider.snapshot.auth.type ?? null;
+    return authLabel ? `Signed in · ${authLabel}` : "Signed in";
+  }
+
+  const summary = getProviderSummary(provider.snapshot);
+  const detail = firstSentence(summary.detail);
+  if (detail) {
+    return `${summary.headline}. ${detail}`;
+  }
+  return state === "notInstalled"
+    ? `${summary.headline}. Install ${provider.displayName}, then sign in.`
+    : `${summary.headline}. Sign in to use ${provider.displayName} here.`;
+}
+
+/**
+ * Row descriptions stay at roughly two rendered lines (design system), but
+ * provider status details are written for the settings page and can run to a
+ * paragraph with install URLs. The card keeps the diagnosis sentence; the
+ * full recipe is one click away behind the row's action.
+ */
+function firstSentence(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const match = /^.*?\.(?=\s|$)/.exec(trimmed);
+  return match ? match[0] : trimmed;
+}
+
+/**
+ * The card is a checklist, so rows are ordered by how close the provider is
+ * to working: sign-in is one browser window away, an install is a bigger
+ * ask, and a ready provider is just confirmation. Within a state, the
+ * caller's (settings) order is kept.
+ */
+const PROVIDER_ROW_STATE_PRIORITY: Record<FirstRunProviderRowState, number> = {
+  needsSignIn: 0,
+  notInstalled: 1,
+  ready: 2,
+};
+
+/** The card never grows past this many provider rows; the rest collapse. */
+export const MAX_VISIBLE_FIRST_RUN_PROVIDER_ROWS = 3;
+
+export interface FirstRunProviderRowGroups {
+  readonly visible: ReadonlyArray<FirstRunProviderRow>;
+  /**
+   * Providers past the cap, least actionable last. Present only when there
+   * are more providers than visible rows; the card renders them as a single
+   * "More agents" row pointing at Settings so the checklist stays a
+   * checklist no matter how many drivers a build ships.
+   */
+  readonly overflow: ReadonlyArray<FirstRunProviderRow> | null;
+}
+
+export function groupFirstRunProviderRows(
+  rows: ReadonlyArray<FirstRunProviderRow>,
+): FirstRunProviderRowGroups {
+  if (rows.length <= MAX_VISIBLE_FIRST_RUN_PROVIDER_ROWS) {
+    return { visible: rows, overflow: null };
+  }
+  return {
+    visible: rows.slice(0, MAX_VISIBLE_FIRST_RUN_PROVIDER_ROWS),
+    overflow: rows.slice(MAX_VISIBLE_FIRST_RUN_PROVIDER_ROWS),
+  };
+}
+
+/**
+ * One row per enabled provider instance, ordered by actionability (see
+ * `PROVIDER_ROW_STATE_PRIORITY`). Disabled instances are left out: the user
+ * turned them off, so they are not part of getting started.
+ */
+export function deriveFirstRunProviderRows(
+  providers: ReadonlyArray<FirstRunSetupProvider>,
+): ReadonlyArray<FirstRunProviderRow> {
+  return providers
+    .filter((provider) => provider.enabled)
+    .map((provider) => {
+      const state = providerRowState(provider.snapshot);
+      return {
+        instanceId: provider.instanceId,
+        driverKind: provider.driverKind,
+        name: provider.displayName,
+        versionLabel: getProviderVersionLabel(provider.snapshot.version),
+        description: providerRowDescription(provider, state),
+        state,
+        dotClassName: PROVIDER_ROW_DOT_CLASS_NAMES[state],
+        signInCommand:
+          state === "needsSignIn"
+            ? (providerAuthReconnectCommand(provider.driverKind) ?? null)
+            : null,
+      } satisfies FirstRunProviderRow;
+    })
+    .toSorted(
+      (left, right) =>
+        PROVIDER_ROW_STATE_PRIORITY[left.state] - PROVIDER_ROW_STATE_PRIORITY[right.state],
+    );
+}
+
+export type FirstRunProjectRowState = "ready" | "missing";
+
+export interface FirstRunProjectRow {
+  readonly state: FirstRunProjectRowState;
+  readonly description: string;
+  readonly dotClassName: string;
+  readonly actionLabel: string;
+}
+
+/**
+ * The folder row. "The folder you launched from" is only claimed when this is
+ * the workspace's one and only project, which is exactly the shape the
+ * server's launch-folder bootstrap leaves behind; anything else shows the path
+ * instead of asserting something we cannot check from the client.
+ */
+export function deriveFirstRunProjectRow(input: {
+  readonly projectName: string | null | undefined;
+  readonly projectCwd: string | null | undefined;
+  readonly isOnlyWorkspaceProject: boolean;
+}): FirstRunProjectRow {
+  const name = input.projectName?.trim();
+  if (!name) {
+    return {
+      state: "missing",
+      description: "No folder yet. Pick the repository you want to work in.",
+      dotClassName: PROVIDER_STATUS_STYLES.warning.dot,
+      actionLabel: "Choose a folder",
+    };
+  }
+
+  const cwd = input.projectCwd?.trim();
+  return {
+    state: "ready",
+    description: input.isOnlyWorkspaceProject
+      ? `${name} · the folder you launched from`
+      : cwd
+        ? `${name} · ${cwd}`
+        : name,
+    dotClassName: PROVIDER_STATUS_STYLES.ready.dot,
+    actionLabel: "Change",
+  };
+}
+
+/**
+ * "Start first thread" needs a provider that can actually serve a turn and a
+ * folder to serve it in. Anything less would hand the user straight back to
+ * the composer notice they were trying to get past.
+ */
+export function canStartFirstThread(input: {
+  readonly providerRows: ReadonlyArray<FirstRunProviderRow>;
+  readonly projectRow: FirstRunProjectRow;
+}): boolean {
+  return (
+    input.projectRow.state === "ready" && input.providerRows.some((row) => row.state === "ready")
+  );
+}