From cf730a04f5c80dfbd759d502412a42f3fbba1861 Mon Sep 17 00:00:00 2001
From: Omkar Tripathi <38633467+triggeredcode@users.noreply.github.com>
Date: Thu, 22 Oct 2026 00:21:58 +0530
Subject: [PATCH] feat(onboarding): verify and resume AI setup

---
 apps/desktop/e2e/onboarding.spec.ts           |   2 +-
 apps/desktop/src/onboarding/FirstRun.test.tsx | 137 +++++++++++++++++
 apps/desktop/src/onboarding/FirstRun.tsx      | 115 ++++++++++++--
 .../desktop/src/onboarding/activation.test.ts |  95 ++++++++++++
 apps/desktop/src/onboarding/activation.ts     | 143 ++++++++++++++++++
 .../src/settings/ProviderSettings.test.tsx    |  56 +++++++
 .../desktop/src/settings/ProviderSettings.tsx |  35 ++++-
 apps/desktop/src/styles.css                   |  36 +++++
 8 files changed, 600 insertions(+), 19 deletions(-)
 create mode 100644 apps/desktop/src/onboarding/activation.test.ts
 create mode 100644 apps/desktop/src/onboarding/activation.ts

diff --git a/apps/desktop/e2e/onboarding.spec.ts b/apps/desktop/e2e/onboarding.spec.ts
index 644a640..df8d1d8 100644
--- a/apps/desktop/e2e/onboarding.spec.ts
+++ b/apps/desktop/e2e/onboarding.spec.ts
@@ -30,7 +30,7 @@ test("a first run explains setup and points out the workspace", async () => {
 
     await expect(window.getByRole("heading", { name: "Connect an AI provider" })).toBeVisible();
     await expect(window.getByText("LM Studio or Ollama", { exact: false })).toBeVisible();
-    await window.getByRole("button", { name: "Continue" }).click();
+    await window.getByRole("button", { name: "Continue without AI" }).click();
 
     await expect(
       window.getByRole("heading", { name: "Everything happens around one page" }),
diff --git a/apps/desktop/src/onboarding/FirstRun.test.tsx b/apps/desktop/src/onboarding/FirstRun.test.tsx
index 7a41696..ccaaf3a 100644
--- a/apps/desktop/src/onboarding/FirstRun.test.tsx
+++ b/apps/desktop/src/onboarding/FirstRun.test.tsx
@@ -5,6 +5,7 @@ import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { PublicSettings } from "../../electron/ipc/types";
+import { decideProvider, loadActivationProgress, rememberSetupStep } from "./activation";
 import { FirstRun } from "./FirstRun";
 
 const settings: PublicSettings = {
@@ -45,6 +46,7 @@ afterEach(() => {
   container?.remove();
   root = undefined;
   container = undefined;
+  localStorage.clear();
 });
 
 describe("FirstRun", () => {
@@ -93,4 +95,139 @@ describe("FirstRun", () => {
     });
     expect(finish).toHaveBeenCalledWith(false);
   });
+
+  it("makes continuing without AI explicit and remembers that choice", async () => {
+    Object.defineProperty(window, "lucid", {
+      configurable: true,
+      value: {
+        credentials: {
+          status: vi.fn().mockResolvedValue({
+            present: false,
+            storage: "none",
+            securePersistenceAvailable: true,
+          }),
+        },
+        settings: {
+          save: vi.fn().mockResolvedValue({ ok: true, settings }),
+        },
+      },
+    });
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    const view = container;
+
+    await act(async () => {
+      root?.render(<FirstRun settings={settings} onSettingsChange={vi.fn()} onFinish={vi.fn()} />);
+      await Promise.resolve();
+    });
+    await act(async () => {
+      [...view.querySelectorAll("button")]
+        .find((button) => button.textContent === "Set up Lucid")
+        ?.click();
+      await Promise.resolve();
+    });
+
+    const normalContinue = [...container.querySelectorAll("button")].find(
+      (button) => button.textContent === "Continue",
+    );
+    expect(normalContinue?.disabled).toBe(true);
+    await act(async () => {
+      [...view.querySelectorAll("button")]
+        .find((button) => button.textContent === "Continue without AI")
+        ?.click();
+      await Promise.resolve();
+    });
+
+    expect(container.querySelector("h1")?.textContent).toBe("Everything happens around one page");
+    expect(loadActivationProgress().provider).toBe("skipped");
+  });
+
+  it("continues after the selected provider and model are verified", async () => {
+    Object.defineProperty(window, "lucid", {
+      configurable: true,
+      value: {
+        credentials: {
+          status: vi.fn().mockResolvedValue({
+            present: false,
+            storage: "none",
+            securePersistenceAvailable: true,
+          }),
+        },
+        settings: {
+          save: vi.fn().mockResolvedValue({ ok: true, settings }),
+        },
+        providers: {
+          test: vi.fn().mockResolvedValue({
+            ok: true,
+            message: "Connected to LM Studio. 1 model available.",
+            models: ["qwen/qwen3.8-27b"],
+          }),
+          models: vi.fn(),
+        },
+      },
+    });
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    const view = container;
+
+    await act(async () => {
+      root?.render(<FirstRun settings={settings} onSettingsChange={vi.fn()} onFinish={vi.fn()} />);
+      await Promise.resolve();
+    });
+    await act(async () => {
+      [...view.querySelectorAll("button")]
+        .find((button) => button.textContent === "Set up Lucid")
+        ?.click();
+      await Promise.resolve();
+    });
+    await act(async () => {
+      [...view.querySelectorAll("button")]
+        .find((button) => button.textContent === "Test connection")
+        ?.click();
+      await Promise.resolve();
+    });
+
+    expect(
+      container.querySelector('.onboarding-readiness[data-state="ready"]')?.textContent,
+    ).toContain("AI ready");
+    const normalContinue = [...container.querySelectorAll("button")].find(
+      (button) => button.textContent === "Continue",
+    );
+    expect(normalContinue?.disabled).toBe(false);
+    expect(loadActivationProgress().provider).toBe("ready");
+  });
+
+  it("resumes an unfinished verified setup after a restart", async () => {
+    const ready = decideProvider(loadActivationProgress(), "ready");
+    rememberSetupStep(ready, 1);
+    Object.defineProperty(window, "lucid", {
+      configurable: true,
+      value: {
+        credentials: {
+          status: vi.fn().mockResolvedValue({
+            present: false,
+            storage: "none",
+            securePersistenceAvailable: true,
+          }),
+        },
+      },
+    });
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(<FirstRun settings={settings} onSettingsChange={vi.fn()} onFinish={vi.fn()} />);
+      await Promise.resolve();
+    });
+
+    expect(container.querySelector("h1")?.textContent).toBe("Connect an AI provider");
+    expect(container.querySelector('.onboarding-readiness[data-state="ready"]')).not.toBeNull();
+    expect(
+      [...container.querySelectorAll("button")].find((button) => button.textContent === "Continue")
+        ?.disabled,
+    ).toBe(false);
+  });
 });
diff --git a/apps/desktop/src/onboarding/FirstRun.tsx b/apps/desktop/src/onboarding/FirstRun.tsx
index 2bccbff..d0a5935 100644
--- a/apps/desktop/src/onboarding/FirstRun.tsx
+++ b/apps/desktop/src/onboarding/FirstRun.tsx
@@ -1,8 +1,15 @@
 import { useEffect, useRef, useState } from "react";
-import type { AiSettings, PublicSettings, SettingsInput } from "../../electron/ipc/types";
+import type {
+  AiSettings,
+  ProviderConnectionResult,
+  ProviderProfile,
+  PublicSettings,
+  SettingsInput,
+} from "../../electron/ipc/types";
 import { ProviderSettings } from "../settings/ProviderSettings";
 import { saveSettings } from "../settings/settingsStore";
 import { BrandMark } from "../ui/BrandMark";
+import { decideProvider, loadActivationProgress, rememberSetupStep } from "./activation";
 
 interface Props {
   settings: PublicSettings;
@@ -12,6 +19,15 @@ interface Props {
 
 const STEP_NAMES = ["Welcome", "Connect AI", "Your workspace"] as const;
 
+const providerIsReady = (
+  result: ProviderConnectionResult | undefined,
+  profile: ProviderProfile,
+): boolean =>
+  result?.ok === true &&
+  profile.model.trim().length > 0 &&
+  Array.isArray(result.models) &&
+  result.models.includes(profile.model);
+
 const settingsWithAi = (settings: PublicSettings, ai: AiSettings): SettingsInput => {
   const selected = ai.profiles.find((profile) => profile.id === ai.defaultProfileId);
   return {
@@ -30,10 +46,12 @@ const settingsWithAi = (settings: PublicSettings, ai: AiSettings): SettingsInput
 };
 
 export function FirstRun({ settings, onSettingsChange, onFinish }: Props) {
-  const [step, setStep] = useState(0);
+  const [step, setStep] = useState<0 | 1 | 2>(() => loadActivationProgress().setupStep);
   const [ai, setAi] = useState(settings.ai);
   const [working, setWorking] = useState(false);
   const [problem, setProblem] = useState<string>();
+  const [providerConnection, setProviderConnection] = useState<ProviderConnectionResult>();
+  const [activation, setActivation] = useState(loadActivationProgress);
   const heading = useRef<HTMLHeadingElement>(null);
 
   useEffect(() => {
@@ -72,9 +90,26 @@ export function FirstRun({ settings, onSettingsChange, onFinish }: Props) {
 
   const next = async () => {
     if (step === 1 && !(await persistAi())) return;
-    setStep((current) => Math.min(current + 1, STEP_NAMES.length - 1));
+    const nextStep = Math.min(step + 1, STEP_NAMES.length - 1) as 0 | 1 | 2;
+    setStep(nextStep);
+    setActivation((current) => rememberSetupStep(current, nextStep));
+  };
+
+  const continueWithoutAi = async () => {
+    if (!(await persistAi())) return;
+    setActivation((current) => rememberSetupStep(decideProvider(current, "skipped"), 2));
+    setStep(2);
   };
 
+  const providerState =
+    activation.provider === "ready"
+      ? "ready"
+      : providerConnection
+        ? "attention"
+        : activation.provider === "skipped"
+          ? "skipped"
+          : "unchecked";
+
   return (
     <div className="modal-backdrop onboarding-backdrop">
       <section
@@ -153,9 +188,43 @@ export function FirstRun({ settings, onSettingsChange, onFinish }: Props) {
                 lmStudioUrlLocked={settings.llmUrlLocked}
                 onChange={setAi}
                 onPersist={persistAi}
+                onConnectionChange={(result, profile) => {
+                  setProviderConnection(result);
+                  setActivation((current) => {
+                    if (providerIsReady(result, profile)) return decideProvider(current, "ready");
+                    if (current.provider === "ready") return decideProvider(current, "unknown");
+                    return current;
+                  });
+                }}
               />
+              <div
+                className="onboarding-readiness"
+                data-state={providerState}
+                role="status"
+                aria-live="polite"
+              >
+                <i aria-hidden="true" />
+                <span>
+                  <strong>
+                    {providerState === "ready"
+                      ? "AI ready"
+                      : providerState === "skipped"
+                        ? "Continuing without AI"
+                        : providerState === "attention"
+                          ? "Connection needs attention"
+                          : "Check your provider before continuing"}
+                  </strong>
+                  {providerState === "ready"
+                    ? " The selected model was found."
+                    : providerState === "skipped"
+                      ? " You can connect one later in Settings."
+                      : providerState === "attention"
+                        ? " Follow the message above, then test it again."
+                        : " Use Test connection after choosing a model."}
+                </span>
+              </div>
               <p className="onboarding-note">
-                You can continue without AI. Notes, manual editing, import and export still work.
+                AI is optional. Notes, manual editing, import and export still work without it.
               </p>
             </div>
           )}
@@ -217,7 +286,9 @@ export function FirstRun({ settings, onSettingsChange, onFinish }: Props) {
                 className="ghost"
                 disabled={working}
                 onClick={() => {
-                  setStep((current) => current - 1);
+                  const previous = (step - 1) as 0 | 1;
+                  setStep(previous);
+                  setActivation((current) => rememberSetupStep(current, previous));
                 }}
               >
                 Back
@@ -225,19 +296,37 @@ export function FirstRun({ settings, onSettingsChange, onFinish }: Props) {
             )}
             <span />
             {step < STEP_NAMES.length - 1 ? (
-              <button
-                type="button"
-                className="primary"
-                disabled={working}
-                onClick={() => void next()}
-              >
-                {working ? "Saving…" : step === 0 ? "Set up Lucid" : "Continue"}
-              </button>
+              <>
+                {step === 1 && activation.provider !== "ready" && (
+                  <button
+                    type="button"
+                    className="ghost"
+                    disabled={working}
+                    onClick={() => void continueWithoutAi()}
+                  >
+                    Continue without AI
+                  </button>
+                )}
+                <button
+                  type="button"
+                  className="primary"
+                  disabled={
+                    working ||
+                    (step === 1 &&
+                      activation.provider !== "ready" &&
+                      activation.provider !== "skipped")
+                  }
+                  onClick={() => void next()}
+                >
+                  {working ? "Saving…" : step === 0 ? "Set up Lucid" : "Continue"}
+                </button>
+              </>
             ) : (
               <button
                 type="button"
                 className="primary"
                 onClick={() => {
+                  setActivation((current) => rememberSetupStep(current, 0));
                   onFinish(true);
                 }}
               >
diff --git a/apps/desktop/src/onboarding/activation.test.ts b/apps/desktop/src/onboarding/activation.test.ts
new file mode 100644
index 0000000..6cf26ca
--- /dev/null
+++ b/apps/desktop/src/onboarding/activation.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  ACTIVATION_STORAGE_KEY,
+  ACTIVATION_VERSION,
+  decideProvider,
+  finishActivation,
+  loadActivationProgress,
+  recordMilestone,
+  rememberActivationPage,
+  rememberSetupStep,
+} from "./activation";
+
+const memory = (initial?: string) => {
+  const values = new Map<string, string>();
+  if (initial) values.set(ACTIVATION_STORAGE_KEY, initial);
+  return {
+    values,
+    storage: {
+      getItem: (key: string) => values.get(key) ?? null,
+      setItem: (key: string, value: string) => values.set(key, value),
+    },
+  };
+};
+
+describe("first-success activation progress", () => {
+  it("starts safely when no progress has been stored", () => {
+    expect(loadActivationProgress(memory().storage)).toEqual({
+      version: ACTIVATION_VERSION,
+      provider: "unknown",
+      setupStep: 0,
+      milestones: [],
+      finished: false,
+    });
+  });
+
+  it("ignores corrupt, stale and unsupported stored values", () => {
+    expect(loadActivationProgress(memory("not json").storage).provider).toBe("unknown");
+    expect(
+      loadActivationProgress(memory(JSON.stringify({ version: "0", provider: "ready" })).storage)
+        .provider,
+    ).toBe("unknown");
+    expect(
+      loadActivationProgress(
+        memory(
+          JSON.stringify({
+            version: ACTIVATION_VERSION,
+            provider: "maybe",
+            milestones: ["page-created", "invented", "page-created"],
+            pageId: 42,
+            finished: "yes",
+          }),
+        ).storage,
+      ),
+    ).toEqual({
+      version: ACTIVATION_VERSION,
+      provider: "unknown",
+      setupStep: 0,
+      milestones: ["page-created"],
+      finished: false,
+    });
+  });
+
+  it("persists decisions, a page and idempotent milestones", () => {
+    const { storage } = memory();
+    let progress = decideProvider(loadActivationProgress(storage), "ready", storage);
+    progress = rememberSetupStep(progress, 2, storage);
+    progress = rememberActivationPage(progress, "page-1", storage);
+    progress = recordMilestone(progress, "page-created", storage);
+    progress = recordMilestone(progress, "page-created", storage);
+    finishActivation(progress, storage);
+
+    expect(loadActivationProgress(storage)).toEqual({
+      version: ACTIVATION_VERSION,
+      provider: "ready",
+      setupStep: 2,
+      milestones: ["page-created"],
+      pageId: "page-1",
+      finished: true,
+    });
+  });
+
+  it("never blocks the app when storage throws", () => {
+    const storage = {
+      getItem: vi.fn(() => {
+        throw new Error("blocked");
+      }),
+      setItem: vi.fn(() => {
+        throw new Error("blocked");
+      }),
+    };
+    const progress = loadActivationProgress(storage);
+    expect(() => decideProvider(progress, "skipped", storage)).not.toThrow();
+    expect(progress.provider).toBe("unknown");
+  });
+});
diff --git a/apps/desktop/src/onboarding/activation.ts b/apps/desktop/src/onboarding/activation.ts
new file mode 100644
index 0000000..b815f4e
--- /dev/null
+++ b/apps/desktop/src/onboarding/activation.ts
@@ -0,0 +1,143 @@
+export const ACTIVATION_VERSION = "1" as const;
+export const ACTIVATION_STORAGE_KEY = "lucid.firstSuccess";
+
+export type ProviderDecision = "unknown" | "ready" | "skipped";
+export type ActivationMilestone =
+  "page-created" | "content-added" | "command-applied" | "visual-created" | "export-saved";
+
+export interface ActivationProgress {
+  version: typeof ACTIVATION_VERSION;
+  provider: ProviderDecision;
+  setupStep: 0 | 1 | 2;
+  milestones: ActivationMilestone[];
+  pageId?: string | undefined;
+  finished: boolean;
+}
+
+type ActivationStorage = Pick<Storage, "getItem" | "setItem">;
+
+const PROVIDER_DECISIONS = new Set<ProviderDecision>(["unknown", "ready", "skipped"]);
+const MILESTONES = new Set<ActivationMilestone>([
+  "page-created",
+  "content-added",
+  "command-applied",
+  "visual-created",
+  "export-saved",
+]);
+
+const emptyProgress = (): ActivationProgress => ({
+  version: ACTIVATION_VERSION,
+  provider: "unknown",
+  setupStep: 0,
+  milestones: [],
+  finished: false,
+});
+
+const browserStorage = (): ActivationStorage | undefined => {
+  try {
+    return window.localStorage;
+  } catch {
+    return undefined;
+  }
+};
+
+const parseProgress = (value: string | null): ActivationProgress => {
+  if (!value) return emptyProgress();
+  try {
+    const decoded: unknown = JSON.parse(value);
+    if (typeof decoded !== "object" || decoded === null) return emptyProgress();
+    const parsed = decoded as Record<string, unknown>;
+    if (parsed["version"] !== ACTIVATION_VERSION) return emptyProgress();
+    const provider = PROVIDER_DECISIONS.has(parsed["provider"] as ProviderDecision)
+      ? (parsed["provider"] as ProviderDecision)
+      : "unknown";
+    const setupStep =
+      parsed["setupStep"] === 1 || parsed["setupStep"] === 2 ? parsed["setupStep"] : 0;
+    const milestones = Array.isArray(parsed["milestones"])
+      ? [
+          ...new Set(
+            parsed["milestones"].filter((item): item is ActivationMilestone =>
+              MILESTONES.has(item as ActivationMilestone),
+            ),
+          ),
+        ]
+      : [];
+    const pageId =
+      typeof parsed["pageId"] === "string" && parsed["pageId"].length > 0
+        ? parsed["pageId"]
+        : undefined;
+    return {
+      version: ACTIVATION_VERSION,
+      provider,
+      setupStep,
+      milestones,
+      ...(pageId ? { pageId } : {}),
+      finished: parsed["finished"] === true,
+    };
+  } catch {
+    return emptyProgress();
+  }
+};
+
+export function loadActivationProgress(storage = browserStorage()): ActivationProgress {
+  try {
+    return parseProgress(storage?.getItem(ACTIVATION_STORAGE_KEY) ?? null);
+  } catch {
+    return emptyProgress();
+  }
+}
+
+export function saveActivationProgress(
+  progress: ActivationProgress,
+  storage = browserStorage(),
+): ActivationProgress {
+  try {
+    storage?.setItem(ACTIVATION_STORAGE_KEY, JSON.stringify(progress));
+  } catch {
+    // Progress is a convenience. A blocked store must never block Lucid.
+  }
+  return progress;
+}
+
+export function decideProvider(
+  progress: ActivationProgress,
+  provider: ProviderDecision,
+  storage = browserStorage(),
+): ActivationProgress {
+  return saveActivationProgress({ ...progress, provider }, storage);
+}
+
+export function rememberSetupStep(
+  progress: ActivationProgress,
+  setupStep: 0 | 1 | 2,
+  storage = browserStorage(),
+): ActivationProgress {
+  return saveActivationProgress({ ...progress, setupStep }, storage);
+}
+
+export function recordMilestone(
+  progress: ActivationProgress,
+  milestone: ActivationMilestone,
+  storage = browserStorage(),
+): ActivationProgress {
+  if (progress.milestones.includes(milestone)) return progress;
+  return saveActivationProgress(
+    { ...progress, milestones: [...progress.milestones, milestone] },
+    storage,
+  );
+}
+
+export function rememberActivationPage(
+  progress: ActivationProgress,
+  pageId: string,
+  storage = browserStorage(),
+): ActivationProgress {
+  return saveActivationProgress({ ...progress, pageId }, storage);
+}
+
+export function finishActivation(
+  progress: ActivationProgress,
+  storage = browserStorage(),
+): ActivationProgress {
+  return saveActivationProgress({ ...progress, finished: true }, storage);
+}
diff --git a/apps/desktop/src/settings/ProviderSettings.test.tsx b/apps/desktop/src/settings/ProviderSettings.test.tsx
index e55df3d..a36e0db 100644
--- a/apps/desktop/src/settings/ProviderSettings.test.tsx
+++ b/apps/desktop/src/settings/ProviderSettings.test.tsx
@@ -53,6 +53,7 @@ describe("ProviderSettings", () => {
     container = document.createElement("div");
     document.body.append(container);
     root = createRoot(container);
+    const connectionChanged = vi.fn();
 
     await act(async () => {
       root?.render(
@@ -61,6 +62,7 @@ describe("ProviderSettings", () => {
           lmStudioUrlLocked={false}
           onChange={vi.fn()}
           onPersist={vi.fn().mockResolvedValue(true)}
+          onConnectionChange={connectionChanged}
         />,
       );
       await Promise.resolve();
@@ -78,6 +80,60 @@ describe("ProviderSettings", () => {
     expect(container.querySelector('[role="status"]')?.textContent).toBe(
       "The connection check could not finish. Try again.",
     );
+    expect(connectionChanged).toHaveBeenLastCalledWith(
+      { ok: false, message: "The connection check could not finish. Try again." },
+      settings.profiles[0],
+    );
     expect(button?.disabled).toBe(false);
   });
+
+  it("reports a successful model inspection to its parent", async () => {
+    const result = {
+      ok: true,
+      message: "Connected to LM Studio. 1 model available.",
+      models: ["local/model"],
+    };
+    Object.defineProperty(window, "lucid", {
+      configurable: true,
+      value: {
+        credentials: {
+          status: vi.fn().mockResolvedValue({
+            present: false,
+            storage: "none",
+            securePersistenceAvailable: true,
+          }),
+        },
+        providers: {
+          test: vi.fn().mockResolvedValue(result),
+          models: vi.fn(),
+        },
+      },
+    });
+    const connectionChanged = vi.fn();
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(
+        <ProviderSettings
+          value={settings}
+          lmStudioUrlLocked={false}
+          onChange={vi.fn()}
+          onPersist={vi.fn().mockResolvedValue(true)}
+          onConnectionChange={connectionChanged}
+        />,
+      );
+      await Promise.resolve();
+    });
+    const test = [...container.querySelectorAll("button")].find(
+      (candidate) => candidate.textContent === "Test connection",
+    );
+    await act(async () => {
+      test?.click();
+      await Promise.resolve();
+    });
+
+    expect(connectionChanged).toHaveBeenLastCalledWith(result, settings.profiles[0]);
+  });
 });
diff --git a/apps/desktop/src/settings/ProviderSettings.tsx b/apps/desktop/src/settings/ProviderSettings.tsx
index 558d586..ef918ca 100644
--- a/apps/desktop/src/settings/ProviderSettings.tsx
+++ b/apps/desktop/src/settings/ProviderSettings.tsx
@@ -30,9 +30,18 @@ interface Props {
   lmStudioUrlLocked: boolean;
   onChange: (value: AiSettings) => void;
   onPersist: () => Promise<boolean>;
+  /** Lets first-run setup distinguish a verified provider from one that still needs attention. */
+  onConnectionChange?:
+    ((result: ProviderConnectionResult | undefined, profile: ProviderProfile) => void) | undefined;
 }
 
-export function ProviderSettings({ value, lmStudioUrlLocked, onChange, onPersist }: Props) {
+export function ProviderSettings({
+  value,
+  lmStudioUrlLocked,
+  onChange,
+  onPersist,
+  onConnectionChange,
+}: Props) {
   const [activeId, setActiveId] = useState(value.defaultProfileId);
   const [addKind, setAddKind] = useState<AiProviderKind>("ollama");
   const [credential, setCredential] = useState<CredentialStatus>(emptyCredential);
@@ -40,6 +49,8 @@ export function ProviderSettings({ value, lmStudioUrlLocked, onChange, onPersist
   const [busy, setBusy] = useState<"key" | "test" | "models">();
   const [models, setModels] = useState<string[]>([]);
   const secret = useRef<HTMLInputElement>(null);
+  const connectionChange = useRef(onConnectionChange);
+  connectionChange.current = onConnectionChange;
   const active =
     value.profiles.find((profile) => profile.id === activeId) ??
     value.profiles.find((profile) => profile.id === value.defaultProfileId) ??
@@ -47,14 +58,22 @@ export function ProviderSettings({ value, lmStudioUrlLocked, onChange, onPersist
   const provider = AI_PROVIDER_CATALOG.find((candidate) => candidate.kind === active?.kind);
   const credentialId = active ? providerCredentialId(active.id) : "";
   const modelListId = useMemo(() => `provider-models-${active?.id ?? "none"}`, [active?.id]);
+  const connectionSignature = `${active?.id ?? ""}\n${active?.kind ?? ""}\n${active?.baseUrl ?? ""}\n${active?.model ?? ""}`;
+  const previousConnectionSignature = useRef(connectionSignature);
 
   useEffect(() => {
-    setConnection(undefined);
-    setModels([]);
     if (!active) return;
     void window.lucid.credentials.status(providerCredentialId(active.id)).then(setCredential);
   }, [active?.id]);
 
+  useEffect(() => {
+    const changed = previousConnectionSignature.current !== connectionSignature;
+    previousConnectionSignature.current = connectionSignature;
+    setConnection(undefined);
+    setModels([]);
+    if (active && changed) connectionChange.current?.(undefined, active);
+  }, [active, connectionSignature]);
+
   const replace = (change: Partial<ProviderProfile>) => {
     if (!active) return;
     onChange({
@@ -97,6 +116,7 @@ export function ProviderSettings({ value, lmStudioUrlLocked, onChange, onPersist
     if (!entered) return;
     setBusy("key");
     setConnection(undefined);
+    connectionChange.current?.(undefined, active);
     try {
       setCredential(
         await window.lucid.credentials.save({
@@ -117,6 +137,8 @@ export function ProviderSettings({ value, lmStudioUrlLocked, onChange, onPersist
 
   const clearKey = async () => {
     setBusy("key");
+    setConnection(undefined);
+    if (active) connectionChange.current?.(undefined, active);
     try {
       await window.lucid.credentials.delete(credentialId);
       setCredential(await window.lucid.credentials.status(credentialId));
@@ -140,15 +162,18 @@ export function ProviderSettings({ value, lmStudioUrlLocked, onChange, onPersist
           ? await window.lucid.providers.test(active.id)
           : await window.lucid.providers.models(active.id);
       setConnection(result);
+      connectionChange.current?.(result, active);
       if (result.ok && result.models) {
         setModels(result.models);
         if (!active.model && result.models[0]) replace({ model: result.models[0] });
       }
     } catch {
-      setConnection({
+      const result: ProviderConnectionResult = {
         ok: false,
         message: "The connection check could not finish. Try again.",
-      });
+      };
+      setConnection(result);
+      connectionChange.current?.(result, active);
     } finally {
       setBusy(undefined);
     }
diff --git a/apps/desktop/src/styles.css b/apps/desktop/src/styles.css
index 91931d4..a45fb67 100644
--- a/apps/desktop/src/styles.css
+++ b/apps/desktop/src/styles.css
@@ -1951,6 +1951,42 @@ select:focus-visible,
 .onboarding-lead {
   margin-bottom: 0;
 }
+.onboarding-readiness {
+  display: flex;
+  gap: 10px;
+  align-items: flex-start;
+  margin-top: 16px;
+  padding: 11px 12px;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  background: var(--bg-2);
+  color: var(--ink-2);
+  font-size: 12px;
+  line-height: 1.5;
+}
+.onboarding-readiness i {
+  flex: 0 0 auto;
+  width: 8px;
+  height: 8px;
+  margin-top: 5px;
+  border-radius: 50%;
+  background: var(--ink-3);
+}
+.onboarding-readiness[data-state="ready"] {
+  border-color: color-mix(in srgb, var(--ok) 42%, var(--line));
+}
+.onboarding-readiness[data-state="ready"] i {
+  background: var(--ok);
+}
+.onboarding-readiness[data-state="attention"] i {
+  background: var(--danger);
+}
+.onboarding-readiness[data-state="skipped"] i {
+  background: var(--accent);
+}
+.onboarding-readiness strong {
+  color: var(--ink);
+}
 .onboarding-note {
   margin: 18px 0 0;
   padding: 10px 12px;