@agent-native/toolkit 0.207.0-nightly-20261011124220 → 0.207.0

package/src/app/i18n/catalogs/pt-BR.ts

@@ -132,7 +132,7 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.roleOtherInputLabel": "Descreva sua função",
   "onboarding.skipForNow": "Pular por enquanto",
   "onboarding.saveRoleError": "Não foi possível salvar sua função.",
-  "onboarding.builderCreateAccount": "Criar uma conta do Builder.io",
+  "onboarding.builderCreateAccount": "Usar o Builder.io",
   "onboarding.builderSignInWithAccount": "Entrar com uma conta do Builder.io",
   "onboarding.builderActivateDescription":
     "Crie ou reutilize sua conta do Builder.io e ative os créditos gratuitos com um clique.",
@@ -153,8 +153,17 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.builderAccountExistsTitle": "Você já tem uma conta do Builder.io",
   "onboarding.builderAccountExistsDescription":
     "Faça login para usar sua conta.",
+  "onboarding.builderActivationChecking":
+    "Verificando se a criação de uma nova conta está disponível.",
+  "onboarding.builderActivationUnavailable":
+    "A criação de novas contas não está ativada neste app. Você ainda pode conectar uma conta existente.",
+  "onboarding.builderActivationUnavailableInMode":
+    "A ativação de uma nova conta não está disponível neste modo. Você ainda pode conectar uma conta existente.",
+  "onboarding.builderActivationCheckFailed":
+    "Não foi possível verificar se este app pode criar novas contas.",
+
   "onboarding.builderActivationDescription":
-    "Crie ou conecte uma conta do Builder.io com um clique para obter créditos grátis.",
+    "Crie uma nova conta para ativar créditos grátis ou continue com uma conta existente.",
   "onboarding.builderOrgActivationDescription":
     "Criaremos sua conta do Builder.io com um clique para que sua organização possa usá-la.",
   "onboarding.builderCreateAndActivate": "Criar e ativar",
@@ -163,7 +172,7 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.builderTerms": "Termos de Serviço",
   "onboarding.builderPrivacy": "Política de Privacidade",
   "onboarding.builderConsentAnd": "e",
-  "onboarding.builderExistingAccount": "Usar Builder.io",
+  "onboarding.builderExistingAccount": "Tenho uma conta Builder.io",
   "onboarding.builderActivating":
     "Ativando os créditos gratuitos do Builder.io",
   "onboarding.builderConnecting":
@@ -893,6 +902,12 @@ const messages: ToolkitAgentChatTranslation = {
   "secrets.usePersonalKey": "Usar uma chave pessoal",
   "selection.attached": "{{formattedCount}} caracteres da seleção anexados",
   "selection.clear": "Limpar contexto da seleção",
+  "setup.addKeyInSettings": "Adicionar uma chave nas Configurações",
+  "setup.addKeyInSettingsDescription": "Para sua conta ou organização.",
+  "setup.setEnvironmentVariable": "Definir uma variável de ambiente",
+  "setup.setEnvironmentVariableDescription":
+    "Uma chave de provedor para todos neste app.",
+
   "setup.addOwnKeys": "Adicionar suas próprias chaves",
   "setup.builderCredits":
     "O Builder.io inclui créditos gratuitos, ou você pode usar sua própria chave de API.",

package/src/app/i18n/catalogs/zh-CN.ts

@@ -126,7 +126,7 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.roleOtherInputLabel": "描述你的角色",
   "onboarding.skipForNow": "暂时跳过",
   "onboarding.saveRoleError": "无法保存你的角色。",
-  "onboarding.builderCreateAccount": "创建 Builder.io 账户",
+  "onboarding.builderCreateAccount": "使用 Builder.io",
   "onboarding.builderSignInWithAccount": "使用 Builder.io 账户登录",
   "onboarding.builderActivateDescription":
     "一键创建或重新使用您的 Builder.io 账户，并激活免费额度。",
@@ -145,8 +145,16 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.builderActivateTitle": "激活免费额度",
   "onboarding.builderAccountExistsTitle": "您已有 Builder.io 账户",
   "onboarding.builderAccountExistsDescription": "登录以使用你的账户。",
+  "onboarding.builderActivationChecking": "正在检查是否可以创建新账户。",
+  "onboarding.builderActivationUnavailable":
+    "此应用未启用新账户创建功能。你仍可连接现有账户。",
+  "onboarding.builderActivationUnavailableInMode":
+    "此模式下无法激活新账户。你仍然可以连接现有账户。",
+  "onboarding.builderActivationCheckFailed":
+    "无法确认此应用是否可以创建新账户。",
+
   "onboarding.builderActivationDescription":
-    "一键创建或连接 Builder.io 账户，即可获得免费额度。",
+    "创建新账户以激活免费额度，或使用现有账户继续。",
   "onboarding.builderOrgActivationDescription":
     "我们会一键创建你的 Builder.io 账户，让你的组织可以使用它。",
   "onboarding.builderCreateAndActivate": "创建并激活",
@@ -154,7 +162,7 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.builderTerms": "服务条款",
   "onboarding.builderPrivacy": "隐私政策",
   "onboarding.builderConsentAnd": "和",
-  "onboarding.builderExistingAccount": "使用 Builder.io",
+  "onboarding.builderExistingAccount": "我有 Builder.io 账户",
   "onboarding.builderActivating": "正在激活 Builder.io 免费额度",
   "onboarding.builderConnecting": "正在设置 Builder.io 免费额度",
   "onboarding.builderProvisioningDescription":
@@ -1157,6 +1165,12 @@ const messages: ToolkitAgentChatTranslation = {
   "selection.attached": "已附加选中内容的 {{formattedCount}} 个字符",
   "selection.attached_other": "已附加选中内容的 {{formattedCount}} 个字符",
   "selection.clear": "清除选中内容上下文",
+  "setup.addKeyInSettings": "在设置中添加密钥",
+  "setup.addKeyInSettingsDescription": "用于你的个人账户或组织。",
+  "setup.setEnvironmentVariable": "设置环境变量",
+  "setup.setEnvironmentVariableDescription":
+    "此应用的所有用户共用一个提供商密钥。",
+
   "setup.addOwnKeys": "添加您自己的密钥",
   "setup.builderCredits":
     "Builder.io 提供免费额度，您也可以使用自己的 API 密钥。",

package/src/app/i18n/catalogs/zh-TW.ts

@@ -127,7 +127,7 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.roleOtherInputLabel": "描述你的角色",
   "onboarding.skipForNow": "暫時略過",
   "onboarding.saveRoleError": "無法儲存你的角色。",
-  "onboarding.builderCreateAccount": "建立 Builder.io 帳戶",
+  "onboarding.builderCreateAccount": "使用 Builder.io",
   "onboarding.builderSignInWithAccount": "使用 Builder.io 帳戶登入",
   "onboarding.builderActivateDescription":
     "只要按一下即可建立或重新使用您的 Builder.io 帳戶，並啟用免費額度。",
@@ -146,8 +146,16 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.builderActivateTitle": "啟用免費額度",
   "onboarding.builderAccountExistsTitle": "您已有 Builder.io 帳戶",
   "onboarding.builderAccountExistsDescription": "登入以使用您的帳戶。",
+  "onboarding.builderActivationChecking": "正在確認是否可以建立新帳戶。",
+  "onboarding.builderActivationUnavailable":
+    "此應用程式未啟用新帳戶建立功能。你仍可連結現有帳戶。",
+  "onboarding.builderActivationUnavailableInMode":
+    "此模式無法啟用新帳戶。你仍可連結現有帳戶。",
+  "onboarding.builderActivationCheckFailed":
+    "無法確認此應用程式是否可以建立新帳戶。",
+
   "onboarding.builderActivationDescription":
-    "按一下即可建立或連接 Builder.io 帳戶，取得免費額度。",
+    "建立新帳戶以啟用免費點數，或使用現有帳戶繼續。",
   "onboarding.builderOrgActivationDescription":
     "我們會一鍵建立您的 Builder.io 帳戶，讓您的組織可以使用。",
   "onboarding.builderCreateAndActivate": "建立並啟用",
@@ -155,7 +163,7 @@ const messages: ToolkitAgentChatTranslation = {
   "onboarding.builderTerms": "服務條款",
   "onboarding.builderPrivacy": "隱私權政策",
   "onboarding.builderConsentAnd": "和",
-  "onboarding.builderExistingAccount": "使用 Builder.io",
+  "onboarding.builderExistingAccount": "我有 Builder.io 帳戶",
   "onboarding.builderActivating": "正在啟用 Builder.io 免費額度",
   "onboarding.builderConnecting": "正在設定 Builder.io 免費額度",
   "onboarding.builderProvisioningDescription":
@@ -1161,6 +1169,12 @@ const messages: ToolkitAgentChatTranslation = {
   "selection.attached": "已附加所選內容的 {{formattedCount}} 個字元",
   "selection.attached_other": "已附加所選內容的 {{formattedCount}} 個字元",
   "selection.clear": "清除所選內容的上下文",
+  "setup.addKeyInSettings": "在設定中新增金鑰",
+  "setup.addKeyInSettingsDescription": "供你的個人帳戶或組織使用。",
+  "setup.setEnvironmentVariable": "設定環境變數",
+  "setup.setEnvironmentVariableDescription":
+    "此應用程式的所有使用者共用一個供應商金鑰。",
+
   "setup.addOwnKeys": "加入您自己的金鑰",
   "setup.builderCredits":
     "Builder.io 提供免費額度，您也可以使用自己的 API 金鑰。",

package/src/app/onboarding/FirstRunOnboarding.spec.tsx

@@ -991,7 +991,7 @@ describe("FirstRunOnboarding", () => {
       document.body.querySelector(
         '[data-testid="first-run-builder-create-account"]',
       )?.textContent,
-    ).toBe("Create a Builder.io account");
+    ).toBe("Use Builder.io");
     expect(
       document.body.querySelector('[data-testid="first-run-builder-sign-in"]')
         ?.textContent,
@@ -1567,6 +1567,54 @@ describe("FirstRunOnboarding", () => {
     expect(document.body.textContent).not.toContain("This app is an agent.");
   });
 
+  it("labels Clips setup as Builder, custom keys, or an optional skip", async () => {
+    mocks.useOnboarding.mockReturnValue({
+      firstRun: true,
+      loading: false,
+      error: null,
+      profile: { appId: "clips", appName: "Clips", capabilities: [] },
+      completeFirstRun: mocks.completeFirstRun,
+      completeFirstRunError: null,
+    });
+
+    await act(async () => {
+      root.render(
+        <TooltipProvider>
+          <FirstRunOnboarding />
+        </TooltipProvider>,
+      );
+      await Promise.resolve();
+    });
+
+    await act(async () => {
+      document.body
+        .querySelector('[data-testid="first-run-role-skip"]')
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      await Promise.resolve();
+    });
+
+    const builderButton = document.body.querySelector<HTMLButtonElement>(
+      '[data-testid="first-run-builder-create-account"]',
+    );
+    const customKeysButton = document.body.querySelector<HTMLButtonElement>(
+      '[data-testid="first-run-open-key-settings"]',
+    );
+    const customKeysCard = customKeysButton?.closest("section");
+
+    expect({
+      builder: builderButton?.textContent,
+      customKeys: customKeysCard?.querySelector("h2")?.textContent,
+      customKeysAction: customKeysButton?.textContent,
+      skip: document.body.querySelector('[data-testid="first-run-setup-skip"]')
+        ?.textContent,
+    }).toEqual({
+      builder: "Use Builder.io",
+      customKeys: "Custom keys",
+      customKeysAction: "Open AI key settings",
+      skip: "Skip for now",
+    });
+  });
+
   it("opens the app directly after a configured Builder connection", () => {
     mocks.useBuilderConnectFlow.mockReturnValue({
       hasFetchedStatus: true,

package/src/app/onboarding/FirstRunOnboarding.tsx

@@ -145,9 +145,8 @@ const FIRST_RUN_ROLE_OPTIONS = [
 ] as const;
 
 /**
- * Where "Skip and configure manually" lands: Agent › Model, whose empty state
- * adds a provider key in one click, since the agent can't answer until a model
- * provider is set up. API keys with the redesign off.
+ * Where the custom-key choice lands: Agent › Model, whose empty state adds a
+ * provider key in one click. API keys with the redesign off.
  */
 export function manualSetupSettingsRoute({
   redesign,
@@ -853,17 +852,9 @@ export function FirstRunOnboarding({
               <section className="flex flex-col gap-5 rounded-2xl border border-border bg-card p-6">
                 <div className="flex flex-col gap-2">
                   <h2 className="text-lg font-bold text-foreground">
-                    Configure manually
+                    {t("agentChat.composer.addOwnKeys")}
                   </h2>
                 </div>
-                <div className="flex flex-col gap-1 rounded-xl bg-muted px-4 py-3">
-                  <p className="text-[13px] font-semibold text-foreground">
-                    You configure and maintain everything
-                  </p>
-                  <p className="text-xs text-muted-foreground">
-                    Full control over your infrastructure
-                  </p>
-                </div>
                 <CapabilityList
                   capabilities={profile.capabilities}
                   className="flex-1"
@@ -874,7 +865,7 @@ export function FirstRunOnboarding({
                   className={cn(secondaryButtonClass, "w-full")}
                   onClick={() => void handleOpenSettings()}
                 >
-                  Skip and configure manually
+                  {t("agentChat.onboarding.openAiKeySettings")}
                 </button>
               </section>
             </div>

package/src/app/onboarding/OnboardingBanner.tsx

@@ -1,6 +1,12 @@
+import { useT } from "@agent-native/core/client/i18n";
 import { useOnboarding } from "@agent-native/core/client/onboarding/use-onboarding";
-import { IconChecklist, IconChevronRight } from "@tabler/icons-react";
-import React from "react";
+import { Button } from "@agent-native/toolkit/ui/button";
+import {
+  IconChecklist,
+  IconChevronRight,
+  IconLoader2,
+} from "@tabler/icons-react";
+import React, { useState } from "react";
 
 interface OnboardingBannerProps {
   onContinue?: () => void;
@@ -11,9 +17,55 @@ export function OnboardingBanner({
   onContinue,
   className,
 }: OnboardingBannerProps) {
-  const { loading, totalCount, completeCount, allComplete, dismissed } =
-    useOnboarding();
-  if (loading || totalCount === 0 || allComplete || dismissed) return null;
+  const {
+    loading,
+    totalCount,
+    completeCount,
+    allComplete,
+    dismissed,
+    error,
+    summaryKnown,
+    refresh,
+  } = useOnboarding();
+  const t = useT();
+  const [retrying, setRetrying] = useState(false);
+
+  if (
+    loading ||
+    (summaryKnown && (dismissed || (totalCount > 0 && allComplete)))
+  ) {
+    return null;
+  }
+  if (error && (!summaryKnown || totalCount > 0)) {
+    const retry = async () => {
+      setRetrying(true);
+      try {
+        await refresh();
+      } finally {
+        setRetrying(false);
+      }
+    };
+
+    return (
+      <div role="alert" className={className} style={styles.error}>
+        <span>{t("agentChat.common.chunkLoadFailed")}</span>
+        <Button
+          type="button"
+          variant="outline"
+          size="xs"
+          data-testid="onboarding-summary-retry"
+          disabled={retrying}
+          onClick={() => void retry()}
+        >
+          {retrying ? (
+            <IconLoader2 className="animate-spin" aria-hidden />
+          ) : null}
+          {t("agentChat.common.retry")}
+        </Button>
+      </div>
+    );
+  }
+  if (!summaryKnown || totalCount === 0) return null;
 
   return (
     <button
@@ -38,6 +90,19 @@ export function OnboardingBanner({
 }
 
 const styles: Record<string, React.CSSProperties> = {
+  error: {
+    display: "flex",
+    flexWrap: "wrap",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 8,
+    width: "100%",
+    padding: "8px 12px",
+    borderBottom: "1px solid hsl(var(--border) / 0.7)",
+    background: "hsl(var(--muted) / 0.25)",
+    color: "hsl(var(--muted-foreground))",
+    fontSize: 12,
+  },
   root: {
     display: "flex",
     alignItems: "center",

package/src/app/onboarding/OnboardingPanel.save-scope.spec.tsx

@@ -8,15 +8,26 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 let steps: OnboardingStepStatus[] = [];
+let onboardingError: string | null = null;
+let dismissed = false;
+let summaryKnown = true;
+let refresh = vi.fn(async () => {});
 vi.mock("@agent-native/core/client/onboarding/use-onboarding", () => ({
   createOnboardingCorrelationId: () => "test-onboarding-correlation-id",
   trackOnboardingEvent: vi.fn(),
   useOnboarding: () => ({
     steps,
     currentStepId: steps[0]?.id ?? null,
-    dismissed: false,
+    completeCount: steps.filter((step) => step.complete).length,
+    totalCount: steps.length,
+    allComplete:
+      steps.length > 0 &&
+      steps.filter((step) => step.required).every((step) => step.complete),
+    dismissed,
+    summaryKnown,
     loading: false,
-    refresh: async () => {},
+    error: onboardingError,
+    refresh,
     complete: vi.fn(),
     dismiss: vi.fn(),
   }),
@@ -28,6 +39,7 @@ vi.mock("@agent-native/core/client/use-dev-mode", () => ({
   useDevMode: () => ({ isDevMode: false }),
 }));
 
+import { OnboardingBanner } from "./OnboardingBanner.js";
 import { OnboardingPanel } from "./OnboardingPanel.js";
 
 function json(body: unknown): Response {
@@ -69,9 +81,30 @@ afterEach(() => {
   container?.remove();
   root = null;
   container = null;
+  steps = [];
+  onboardingError = null;
+  dismissed = false;
+  summaryKnown = true;
+  refresh = vi.fn(async () => {});
   vi.unstubAllGlobals();
 });
 
+async function renderOnboarding(child: React.ReactNode): Promise<void> {
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  await act(async () => {
+    root!.render(
+      <QueryClientProvider client={queryClient}>
+        <TooltipProvider>{child}</TooltipProvider>
+      </QueryClientProvider>,
+    );
+  });
+}
+
 async function saveAs(
   role: "member" | "admin",
   saveTo?: "scoped-secrets",
@@ -156,4 +189,112 @@ describe("onboarding form save scope", () => {
     const [secretSave] = await saveAs("admin", "scoped-secrets");
     expect(secretSave.body.scope).toBe("workspace");
   });
+
+  it("shows retry only when the initial summary is unavailable", async () => {
+    steps = [formStep()];
+    onboardingError = "summary: 503";
+    summaryKnown = false;
+    refresh = vi.fn(async () => {});
+    await renderOnboarding(<OnboardingPanel />);
+
+    const retry = container?.querySelector<HTMLButtonElement>(
+      '[data-testid="onboarding-summary-retry"]',
+    );
+    expect(container?.querySelector('[role="alert"]')).not.toBeNull();
+    expect(container?.textContent).not.toContain("Example keys");
+    expect(retry).not.toBeNull();
+    await act(async () => retry?.click());
+    expect(refresh).toHaveBeenCalledOnce();
+  });
+
+  it("keeps known steps visible while showing a summary retry state", async () => {
+    steps = [formStep()];
+    onboardingError = "summary: 503";
+    await renderOnboarding(<OnboardingPanel />);
+
+    expect(container?.querySelector('[role="alert"]')).not.toBeNull();
+    expect(container?.textContent).toContain("Example keys");
+    expect(
+      container?.querySelector('[data-testid="onboarding-summary-retry"]'),
+    ).not.toBeNull();
+  });
+
+  it("shows a retry-only banner when the initial summary is unavailable", async () => {
+    steps = [formStep()];
+    onboardingError = "summary: 503";
+    summaryKnown = false;
+    refresh = vi.fn(async () => {});
+    await renderOnboarding(<OnboardingBanner />);
+
+    const retry = container?.querySelector<HTMLButtonElement>(
+      '[data-testid="onboarding-summary-retry"]',
+    );
+    expect(container?.querySelector('[role="alert"]')).not.toBeNull();
+    expect(container?.textContent).not.toContain("Example keys");
+    expect(container?.textContent).not.toContain("Continue");
+    expect(retry).not.toBeNull();
+    await act(async () => retry?.click());
+    expect(refresh).toHaveBeenCalledOnce();
+  });
+
+  it("shows a retry action on the banner for a known active summary", async () => {
+    steps = [formStep()];
+    onboardingError = "summary: 503";
+    summaryKnown = true;
+    refresh = vi.fn(async () => {});
+    await renderOnboarding(<OnboardingBanner />);
+
+    const retry = container?.querySelector<HTMLButtonElement>(
+      '[data-testid="onboarding-summary-retry"]',
+    );
+    expect(container?.querySelector('[role="alert"]')).not.toBeNull();
+    expect(retry).not.toBeNull();
+    await act(async () => retry?.click());
+    expect(refresh).toHaveBeenCalledOnce();
+  });
+
+  it("hides summary errors after onboarding is dismissed", async () => {
+    dismissed = true;
+    summaryKnown = true;
+    onboardingError = "summary: 503";
+
+    await renderOnboarding(
+      <>
+        <OnboardingBanner />
+        <OnboardingPanel />
+      </>,
+    );
+    expect(container?.querySelector('[role="alert"]')).toBeNull();
+  });
+
+  it("hides summary errors after all required steps are complete", async () => {
+    steps = [{ ...formStep(), complete: true }];
+    summaryKnown = true;
+    onboardingError = "summary: 503";
+
+    await renderOnboarding(
+      <>
+        <OnboardingBanner />
+        <OnboardingPanel />
+      </>,
+    );
+    expect(container?.querySelector('[role="alert"]')).toBeNull();
+  });
+
+  it("keeps the retry notice visible while the panel is collapsed", async () => {
+    steps = [formStep()];
+    summaryKnown = true;
+    onboardingError = "summary: 503";
+    await renderOnboarding(<OnboardingPanel />);
+
+    const collapse = container?.querySelector<HTMLButtonElement>(
+      '[aria-label="Collapse onboarding"]',
+    );
+    await act(async () => collapse?.click());
+
+    expect(container?.querySelector('[role="alert"]')).not.toBeNull();
+    expect(
+      container?.querySelector('[data-testid="onboarding-summary-retry"]'),
+    ).not.toBeNull();
+  });
 });

package/src/app/onboarding/OnboardingPanel.tsx

@@ -12,6 +12,7 @@ import type {
   OnboardingMethod,
   OnboardingStepStatus,
 } from "@agent-native/core/onboarding/types";
+import { Button } from "@agent-native/toolkit/ui/button";
 import {
   Tooltip,
   TooltipContent,
@@ -56,10 +57,13 @@ export function OnboardingPanel({
     currentStepId: rawCurrentStepId,
     dismissed,
     loading,
+    error,
+    summaryKnown,
     refresh,
     complete,
     dismiss,
   } = onboarding;
+  const t = useT();
   const DEV_ONLY_STEP_IDS = new Set(["database", "auth"]);
   const steps = isDevMode
     ? rawSteps
@@ -75,6 +79,7 @@ export function OnboardingPanel({
   const checklistVisible =
     !loading && totalCount > 0 && (previewMode || (!dismissed && !allComplete));
   const [expanded, setExpanded] = useState(true);
+  const [retrying, setRetrying] = useState(false);
   const stepViewRef = useRef<{ key: string; id: string } | null>(null);
 
   useEffect(() => {
@@ -102,12 +107,58 @@ export function OnboardingPanel({
     });
   }, [checklistVisible, currentStepId, expanded, previewMode, steps]);
 
-  if (loading || totalCount === 0) return null;
-  if (!previewMode) {
-    if (dismissed) return null;
-    if (allComplete) return null;
-  }
+  const handleRetry = async () => {
+    setRetrying(true);
+    try {
+      await refresh();
+    } finally {
+      setRetrying(false);
+    }
+  };
+  const errorNotice =
+    error &&
+    (previewMode ||
+      !summaryKnown ||
+      (totalCount > 0 && !dismissed && !allComplete)) ? (
+      <div role="alert" style={styles.errorNotice}>
+        <span>{t("agentChat.common.chunkLoadFailed")}</span>
+        <Button
+          type="button"
+          variant="outline"
+          size="xs"
+          data-testid="onboarding-summary-retry"
+          disabled={retrying}
+          onClick={() => void handleRetry()}
+        >
+          {retrying ? (
+            <IconLoader2 className="animate-spin" aria-hidden />
+          ) : null}
+          {t("agentChat.common.retry")}
+        </Button>
+      </div>
+    ) : null;
 
+  if (loading) return null;
+  if (!previewMode && !summaryKnown) {
+    if (!errorNotice) return null;
+    return (
+      <div className={className} style={styles.errorOnly}>
+        {errorNotice}
+      </div>
+    );
+  }
+  if (!previewMode && (dismissed || (totalCount > 0 && allComplete))) {
+    return null;
+  }
+  if (error && totalCount === 0) {
+    if (!errorNotice) return null;
+    return (
+      <div className={className} style={styles.errorOnly}>
+        {errorNotice}
+      </div>
+    );
+  }
+  if (totalCount === 0) return null;
   if (!expanded) {
     return (
       <div className={className} style={styles.compactBanner}>
@@ -139,6 +190,7 @@ export function OnboardingPanel({
           </TooltipTrigger>
           <TooltipContent>Expand setup</TooltipContent>
         </Tooltip>
+        {errorNotice}
       </div>
     );
   }
@@ -174,6 +226,8 @@ export function OnboardingPanel({
         </Tooltip>
       </div>
 
+      {errorNotice}
+
       <div style={styles.list}>
         {steps.map((step) => (
           <StepCard
@@ -853,6 +907,19 @@ function badgeStyle(
 }
 
 const styles: Record<string, React.CSSProperties> = {
+  errorOnly: {
+    borderBottom: "1px solid hsl(var(--border) / 0.7)",
+    background: "hsl(var(--muted) / 0.25)",
+    fontSize: 12,
+  },
+  errorNotice: {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 8,
+    padding: "8px 12px",
+    color: "hsl(var(--muted-foreground))",
+  },
   root: {
     borderBottom: "1px solid hsl(var(--border) / 0.7)",
     background: "hsl(var(--muted) / 0.25)",