Skip to content

Self-improving AI Employees for everyone

feat(onboarding): redesign wizard, add Get Started checklist and aha-first handoff

trohitg565c579af407
diff --git a/client/src/Dashboard.tsx b/client/src/Dashboard.tsx
index 8da1035b..fa1776ac 100644
--- a/client/src/Dashboard.tsx
+++ b/client/src/Dashboard.tsx
@@ -1,5 +1,6 @@
/* eslint-disable react-hooks/exhaustive-deps -- curated dep arrays; reactive-graph derivations + workflow debouncers intentionally omit deps to avoid infinite loops. */
import React, { useEffect } from 'react';
+import { toast } from 'sonner';
import {
ReactFlow,
ReactFlowProvider,
@@ -34,6 +35,8 @@ import SettingsPanel, { WorkflowSettings, defaultSettings } from './components/u
import AIResultModal from './components/ui/AIResultModal';
import CredentialsModal from './components/CredentialsModal';
import OnboardingWizard from './components/onboarding/OnboardingWizard';
+import GetStartedChecklist from './components/onboarding/GetStartedChecklist';
+import { useSaveUserSettingsMutation } from './hooks/useUserSettingsQuery';
import ErrorBoundary from './components/ui/ErrorBoundary';
import ConsolePanel from './components/ui/ConsolePanel';
import StatusBar from './components/ui/StatusBar';
@@ -170,6 +173,8 @@ const DashboardContent: React.FC = () => {
const setSelectedNode = useAppStore((s) => s.setSelectedNode);
const renamingNodeId = useAppStore((s) => s.renamingNodeId);
const setRenamingNodeId = useAppStore((s) => s.setRenamingNodeId);
+ const openExampleAndChat = useAppStore((s) => s.openExampleAndChat);
+ const saveUserSettings = useSaveUserSettingsMutation();
// Per-workflow UI state (n8n pattern)
const setWorkflowExecuting = useAppStore((s) => s.setWorkflowExecuting);
const setWorkflowExecutionOrder = useAppStore((s) => s.setWorkflowExecutionOrder);
@@ -782,6 +787,26 @@ const DashboardContent: React.FC = () => {
}
};
+ // Onboarding handoff: open the AI Assistant example, focus chat, and
+ // deploy it so the chat trigger is live. Shared by the wizard's finish
+ // button and the Get Started checklist.
+ const handleRunExample = React.useCallback(async () => {
+ const workflow = await openExampleAndChat('AI Assistant');
+ if (!workflow) return;
+
+ const alreadyDeployed = deploymentStatus.isRunning && deploymentStatus.workflow_id === workflow.id;
+ if (alreadyDeployed) return;
+
+ try {
+ const result = await deployWorkflow(workflow.id, workflow.nodes, workflow.edges, 'default');
+ if (!result.success) {
+ toast.error('Could not start the example — press Start on the toolbar.');
+ }
+ } catch {
+ toast.error('Could not start the example — press Start on the toolbar.');
+ }
+ }, [openExampleAndChat, deployWorkflow, deploymentStatus.isRunning, deploymentStatus.workflow_id]);
+
// Stop click handler — routes to the right cancel based on what's actually
// running. If the workflow is deployed, cancel the deployment (existing
// path). Otherwise cancel any in-flight ad-hoc execution(s). Falls
@@ -1433,6 +1458,10 @@ const DashboardContent: React.FC = () => {
setSettingsOpen(false);
setOnboardingReopenTrigger(prev => prev + 1);
}}
+ onShowGetStarted={() => {
+ saveUserSettings.mutate({ getting_started_dismissed: false });
+ setSettingsOpen(false);
+ }}
/>
{/* Credentials Modal */}
@@ -1445,6 +1474,16 @@ const DashboardContent: React.FC = () => {
<OnboardingWizard
onOpenCredentials={() => setCredentialsOpen(true)}
reopenTrigger={onboardingReopenTrigger}
+ onFinish={() => void handleRunExample()}
+ />
+
+ {/* Get Started checklist (appears after onboarding completes) */}
+ <GetStartedChecklist
+ actions={{
+ 'add-key': () => setCredentialsOpen(true),
+ 'chat-example': () => void handleRunExample(),
+ 'build-workflow': handleNew,
+ }}
/>
{/* Node Context Menu (right-click) */}
diff --git a/client/src/components/__tests__/ConsolePanel.focus.test.tsx b/client/src/components/__tests__/ConsolePanel.focus.test.tsx
new file mode 100644
index 00000000..e05334b1
--- /dev/null
+++ b/client/src/components/__tests__/ConsolePanel.focus.test.tsx
@@ -0,0 +1,130 @@
+/**
+ * Tests for the ConsolePanel chat-focus effect.
+ *
+ * Locks the handoff contract: when useAppStore.chatFocusRequest increments
+ * while the panel is open, the chat input is focused on the next animation
+ * frame. A chatFocusRequest of 0 (initial) or a closed panel never focuses.
+ */
+
+import { describe, it, expect, vi, beforeEach, beforeAll } from 'vitest';
+import { render, screen, act } from '@testing-library/react';
+
+// Full-module replace of the WS context (importActual+spread is broken under
+// React 19 — see CredentialsModal.test.tsx). ConsolePanel destructures:
+// consoleLogs, clearConsoleLogs, terminalLogs, clearTerminalLogs,
+// sendChatMessage, chatMessages, clearChatMessages. lib/nodeSpec (imported
+// transitively) also pulls useWebSocket but only calls it inside hooks that
+// this test never mounts.
+const wsMock = {
+ consoleLogs: [] as unknown[],
+ terminalLogs: [] as unknown[],
+ chatMessages: [] as unknown[],
+ sendChatMessage: vi.fn().mockResolvedValue(undefined),
+ clearConsoleLogs: vi.fn(),
+ clearTerminalLogs: vi.fn(),
+ clearChatMessages: vi.fn(),
+};
+
+vi.mock('../../contexts/WebSocketContext', () => ({
+ useWebSocket: () => wsMock,
+}));
+
+import ConsolePanel from '../ui/ConsolePanel';
+import { useAppStore } from '../../store/useAppStore';
+
+// --- jsdom shims -------------------------------------------------------------
+
+beforeAll(() => {
+ // jsdom has no scrollIntoView; ConsolePanel's auto-scroll effects call it.
+ Element.prototype.scrollIntoView = vi.fn();
+
+ // Vitest's jsdom env normally provides rAF (pretendToBeVisual); polyfill
+ // defensively so the flush helper below always works.
+ if (typeof globalThis.requestAnimationFrame === 'undefined') {
+ globalThis.requestAnimationFrame = ((cb: FrameRequestCallback) =>
+ setTimeout(() => cb(performance.now()), 0)) as typeof requestAnimationFrame;
+ globalThis.cancelAnimationFrame = ((id: number) =>
+ clearTimeout(id)) as typeof cancelAnimationFrame;
+ }
+});
+
+/** Resolve after the next animation frame — any rAF scheduled before this
+ * call has already run by the time it resolves. */
+const flushAnimationFrame = () =>
+ new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ useAppStore.setState({ chatFocusRequest: 0 });
+});
+
+const renderPanel = (isOpen: boolean) =>
+ render(<ConsolePanel isOpen={isOpen} onToggle={vi.fn()} nodes={[]} />);
+
+// ---------------------------------------------------------------------------
+
+describe('ConsolePanel chat focus', () => {
+ it('does not focus the chat input on mount (chatFocusRequest is 0)', async () => {
+ renderPanel(true);
+ await act(async () => {
+ await flushAnimationFrame();
+ });
+ const input = screen.getByPlaceholderText('Type a message...');
+ expect(input).not.toHaveFocus();
+ });
+
+ it('focuses the chat input when chatFocusRequest increments while open', async () => {
+ renderPanel(true);
+ const input = screen.getByPlaceholderText('Type a message...');
+ expect(input).not.toHaveFocus();
+
+ act(() => {
+ useAppStore.getState().requestChatFocus();
+ });
+ await act(async () => {
+ await flushAnimationFrame();
+ });
+
+ expect(input).toHaveFocus();
+ });
+
+ it('focuses again on a subsequent increment after focus moved elsewhere', async () => {
+ renderPanel(true);
+ const input = screen.getByPlaceholderText('Type a message...');
+
+ act(() => {
+ useAppStore.getState().requestChatFocus();
+ });
+ await act(async () => {
+ await flushAnimationFrame();
+ });
+ expect(input).toHaveFocus();
+
+ act(() => {
+ (input as HTMLInputElement).blur();
+ });
+ expect(input).not.toHaveFocus();
+
+ act(() => {
+ useAppStore.getState().requestChatFocus();
+ });
+ await act(async () => {
+ await flushAnimationFrame();
+ });
+ expect(input).toHaveFocus();
+ });
+
+ it('does not focus when the panel is closed', async () => {
+ renderPanel(false);
+ const input = screen.getByPlaceholderText('Type a message...');
+
+ act(() => {
+ useAppStore.getState().requestChatFocus();
+ });
+ await act(async () => {
+ await flushAnimationFrame();
+ });
+
+ expect(input).not.toHaveFocus();
+ });
+});
diff --git a/client/src/components/icons/AIProviderIcons.tsx b/client/src/components/icons/AIProviderIcons.tsx
index 99cf098f..4f130015 100644
--- a/client/src/components/icons/AIProviderIcons.tsx
+++ b/client/src/components/icons/AIProviderIcons.tsx
@@ -90,7 +90,7 @@ export const AI_PROVIDER_ICONS: Record<string, React.FC<{ size?: number }>> = {
// `iconRef` uses the prefix-dispatch contract resolved by `<NodeIcon>` —
// `lobehub:<brand>` picks the package's `.Color` (or `.Avatar`)
// component. `Icon` stays as a pre-built FC for the remaining direct
-// consumers (e.g. ApiKeyStep onboarding cards).
+// consumers.
export const AI_PROVIDER_META: Record<string, { iconRef: string; Icon: React.FC<{ size?: number }>; color: string; label: string }> = {
openai: { iconRef: 'lobehub:OpenAI', Icon: OpenAIIcon, color: dracula.green, label: 'OpenAI' },
anthropic: { iconRef: 'lobehub:Claude', Icon: ClaudeIcon, color: dracula.orange, label: 'Anthropic' },
diff --git a/client/src/components/onboarding/GetStartedChecklist.tsx b/client/src/components/onboarding/GetStartedChecklist.tsx
new file mode 100644
index 00000000..fc0b78de
--- /dev/null
+++ b/client/src/components/onboarding/GetStartedChecklist.tsx
@@ -0,0 +1,142 @@
+import React from 'react';
+import { Sparkles, Check, ChevronDown, ChevronUp, X } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Card, CardContent, CardHeader } from '@/components/ui/card';
+import { Progress } from '@/components/ui/progress';
+import { Button } from '@/components/ui/button';
+import { ActionButton } from '@/components/ui/action-button';
+import { cn } from '@/lib/utils';
+import { useGetStarted } from '../../hooks/useGetStarted';
+import { GET_STARTED_ITEMS, type GetStartedItemId } from './getStartedItems';
+
+interface GetStartedChecklistProps {
+ /** Per-item click actions, wired by the Dashboard. Items without an
+ * action (or already completed) render as plain rows. */
+ actions?: Partial<Record<GetStartedItemId, () => void>>;
+}
+
+const GetStartedChecklist: React.FC<GetStartedChecklistProps> = ({ actions }) => {
+ const { visible, items, completedCount, totalCount, dismiss } = useGetStarted();
+ const [collapsed, setCollapsed] = React.useState(false);
+
+ if (!visible) return null;
+
+ const handleDismiss = () => {
+ dismiss();
+ toast.info('Get started hidden — reopen it anytime from Settings → Help.');
+ };
+
+ const allComplete = completedCount === totalCount;
+ const completedById = new Map(items.map((item) => [item.id, item.completed]));
+
+ if (collapsed) {
+ return (
+ <button
+ type="button"
+ onClick={() => setCollapsed(false)}
+ className="fixed bottom-14 right-4 z-40 inline-flex h-8 items-center gap-1.5 rounded-full border border-border bg-card px-3 text-xs font-medium shadow-md hover:bg-accent"
+ >
+ <Sparkles className="h-3.5 w-3.5" />
+ Get started · {completedCount}/{totalCount}
+ <ChevronUp className="h-3.5 w-3.5 text-muted-foreground" />
+ </button>
+ );
+ }
+
+ return (
+ <Card className="fixed bottom-14 right-4 z-40 w-80 shadow-md">
+ <CardHeader className="flex flex-row items-center gap-2 space-y-0 px-4 pt-3 pb-2">
+ <Sparkles className="h-4 w-4 shrink-0" />
+ <div className="min-w-0 flex-1">
+ <div className="text-sm font-semibold">
+ {allComplete ? "You're all set!" : 'Get started'}
+ </div>
+ <div className="text-xs text-muted-foreground">
+ {completedCount} of {totalCount} complete
+ </div>
+ </div>
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6"
+ onClick={() => setCollapsed(true)}
+ aria-label="Collapse checklist"
+ >
+ <ChevronDown className="h-4 w-4" />
+ </Button>
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6"
+ onClick={handleDismiss}
+ aria-label="Dismiss checklist"
+ >
+ <X className="h-4 w-4" />
+ </Button>
+ </CardHeader>
+ <CardContent className="flex flex-col gap-1 px-2 pb-3">
+ <div className="px-2 pb-2">
+ <Progress value={(completedCount / totalCount) * 100} className="h-1.5" />
+ </div>
+
+ {GET_STARTED_ITEMS.map((item) => {
+ const completed = completedById.get(item.id) ?? false;
+ const action = actions?.[item.id];
+ const clickable = !completed && item.actionable && action !== undefined;
+ const row = (
+ <>
+ <span
+ className={cn(
+ 'flex h-6 w-6 shrink-0 items-center justify-center rounded-full border',
+ completed
+ ? 'border-primary bg-primary text-primary-foreground'
+ : 'border-border text-muted-foreground',
+ )}
+ >
+ {completed ? <Check className="h-3.5 w-3.5" /> : <item.icon className="h-3.5 w-3.5" />}
+ </span>
+ <span className="min-w-0 flex-1 text-left">
+ <span
+ className={cn(
+ 'block text-sm font-medium',
+ completed && 'text-muted-foreground line-through',
+ )}
+ >
+ {item.label}
+ </span>
+ <span className="block text-xs text-muted-foreground">{item.sublabel}</span>
+ </span>
+ </>
+ );
+
+ return clickable ? (
+ <button
+ key={item.id}
+ type="button"
+ onClick={action}
+ className="flex items-center gap-2.5 rounded-md px-2 py-1.5 hover:bg-accent"
+ >
+ {row}
+ </button>
+ ) : (
+ <div key={item.id} className="flex items-center gap-2.5 rounded-md px-2 py-1.5">
+ {row}
+ </div>
+ );
+ })}
+
+ {allComplete && (
+ <div className="mt-1 px-2 text-center">
+ <ActionButton intent="run" onClick={handleDismiss}>
+ <Check className="h-4 w-4" />
+ Done
+ </ActionButton>
+ </div>
+ )}
+ </CardContent>
+ </Card>
+ );
+};
+
+export default GetStartedChecklist;
diff --git a/client/src/components/onboarding/OnboardingWizard.tsx b/client/src/components/onboarding/OnboardingWizard.tsx
index f5eca7a1..eddf10e8 100644
--- a/client/src/components/onboarding/OnboardingWizard.tsx
+++ b/client/src/components/onboarding/OnboardingWizard.tsx
@@ -1,5 +1,5 @@
import React from 'react';
-import { ArrowLeft, ArrowRight, Check } from 'lucide-react';
+import { ArrowLeft, ArrowRight, Check, MessageCircle } from 'lucide-react';
import { Button } from '@/components/ui/button';
import { ActionButton } from '@/components/ui/action-button';
@@ -7,28 +7,30 @@ import { cn } from '@/lib/utils';
import Modal from '../ui/Modal';
import { useOnboarding } from '../../hooks/useOnboarding';
import WelcomeStep from './steps/WelcomeStep';
-import ConceptsStep from './steps/ConceptsStep';
-import ApiKeyStep from './steps/ApiKeyStep';
-import CanvasStep from './steps/CanvasStep';
-import GetStartedStep from './steps/GetStartedStep';
+import HowItWorksStep from './steps/HowItWorksStep';
+import ConnectAIStep from './steps/ConnectAIStep';
+import TryItStep from './steps/TryItStep';
interface OnboardingWizardProps {
onOpenCredentials: () => void;
reopenTrigger?: number;
+ /** Called after the final step's button completes the wizard — the
+ * Dashboard uses it to open the AI Assistant example and focus chat.
+ * Never called on skip or modal close. */
+ onFinish?: () => void;
}
// Single source of truth for the wizard's step list. Length feeds the
// hook's totalSteps and the progress indicator; renderer is dispatched
// by index. Adding a step is a one-line edit here.
const STEPS: { title: string; render: (props: { onOpenCredentials: () => void }) => React.ReactNode }[] = [
- { title: 'Welcome', render: () => <WelcomeStep /> },
- { title: 'Concepts', render: () => <ConceptsStep /> },
- { title: 'API Keys', render: ({ onOpenCredentials }) => <ApiKeyStep onOpenCredentials={onOpenCredentials} /> },
- { title: 'Canvas', render: () => <CanvasStep /> },
- { title: 'Get Started', render: () => <GetStartedStep /> },
+ { title: 'Welcome', render: () => <WelcomeStep /> },
+ { title: 'How it works', render: () => <HowItWorksStep /> },
+ { title: 'Connect your AI', render: ({ onOpenCredentials }) => <ConnectAIStep onOpenCredentials={onOpenCredentials} /> },
+ { title: 'Try it', render: () => <TryItStep /> },
];
-const OnboardingWizard: React.FC<OnboardingWizardProps> = ({ onOpenCredentials, reopenTrigger }) => {
+const OnboardingWizard: React.FC<OnboardingWizardProps> = ({ onOpenCredentials, reopenTrigger, onFinish }) => {
const {
isVisible,
currentStep,
@@ -42,8 +44,13 @@ const OnboardingWizard: React.FC<OnboardingWizardProps> = ({ onOpenCredentials,
if (!isVisible || !hasChecked || isLoading) return null;
- const isLastStep = currentStep >= STEPS.length - 1;
const safeIndex = Math.min(Math.max(currentStep, 0), STEPS.length - 1);
+ const isLastStep = safeIndex === STEPS.length - 1;
+
+ const handleFinish = () => {
+ complete();
+ onFinish?.();
+ };
return (
<Modal
@@ -58,7 +65,7 @@ const OnboardingWizard: React.FC<OnboardingWizardProps> = ({ onOpenCredentials,
<ol className="mb-4 flex w-full items-center">
{STEPS.map((item, idx) => {
const status: 'completed' | 'active' | 'upcoming' =
- idx < currentStep ? 'completed' : idx === currentStep ? 'active' : 'upcoming';
+ idx < safeIndex ? 'completed' : idx === safeIndex ? 'active' : 'upcoming';
const isLast = idx === STEPS.length - 1;
return (
<li key={item.title} className="flex flex-1 items-center gap-2">
@@ -84,7 +91,7 @@ const OnboardingWizard: React.FC<OnboardingWizardProps> = ({ onOpenCredentials,
<div
className={cn(
'h-px flex-1',
- idx < currentStep ? 'bg-primary' : 'bg-border',
+ idx < safeIndex ? 'bg-primary' : 'bg-border',
)}
/>
)}
@@ -105,16 +112,16 @@ const OnboardingWizard: React.FC<OnboardingWizardProps> = ({ onOpenCredentials,
</Button>
<div className="flex items-center gap-2">
- {currentStep > 0 && (
+ {safeIndex > 0 && (
<Button variant="outline" onClick={prevStep}>
<ArrowLeft className="h-4 w-4" />
Back
</Button>
)}
{isLastStep ? (
- <ActionButton intent="run" onClick={complete}>
- <Check className="h-4 w-4" />
- Start Building
+ <ActionButton intent="run" onClick={handleFinish}>
+ <MessageCircle className="h-4 w-4" />
+ Open AI Assistant
</ActionButton>
) : (
<ActionButton intent="tools" onClick={nextStep}>
diff --git a/client/src/components/onboarding/__tests__/ConnectAIStep.test.tsx b/client/src/components/onboarding/__tests__/ConnectAIStep.test.tsx
new file mode 100644
index 00000000..d4c032d2
--- /dev/null
+++ b/client/src/components/onboarding/__tests__/ConnectAIStep.test.tsx
@@ -0,0 +1,189 @@
+/**
+ * ConnectAIStep behavioural tests.
+ *
+ * The catalogue hook is module-mocked (simpler and more robust than seeding
+ * the TanStack Query cache + real WebSocket plumbing -- the component only
+ * reads `catalogueQuery.data`). The WebSocketContext is also full-module
+ * replaced defensively so no transitive import ever reaches the real
+ * provider (the importActual+spread variant is documented broken under
+ * React 19 -- see CredentialsModal.test.tsx).
+ *
+ * Locks in:
+ * - only `category === 'ai'` providers render
+ * - featured cards render in openai / anthropic / gemini order with the
+ * correct "Get a key" hrefs + target/rel hardening
+ * - stored provider flips: Connected badge, "You're connected" header,
+ * "Manage AI accounts" CTA
+ * - none stored: "Connect your AI" header, "Connect your AI account" CTA,
+ * trust microcopy
+ * - data undefined: skeletons render and the CTA stays usable
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { renderWithProviders } from '../../../test/providers';
+
+import type {
+ CatalogueResponse,
+ ServerProviderConfig,
+} from '../../../hooks/useCatalogueQuery';
+
+// --- Mocks (declared BEFORE importing the component -- vi.mock is hoisted) --
+
+let catalogueData: CatalogueResponse | undefined;
+
+vi.mock('../../../hooks/useCatalogueQuery', () => ({
+ useCatalogueQuery: () => ({ data: catalogueData }),
+}));
+
+// Defensive full-module replace: nothing in this render tree should touch
+// the real WebSocket provider.
+vi.mock('../../../contexts/WebSocketContext', () => ({
+ useWebSocket: () => ({
+ isConnected: true,
+ isReady: true,
+ sendRequest: vi.fn().mockResolvedValue({}),
+ }),
+}));
+
+import ConnectAIStep from '../steps/ConnectAIStep';
+
+// --- Fixtures ---------------------------------------------------------------
+
+const makeProvider = (
+ over: Partial<ServerProviderConfig> & { id: string; name: string },
+): ServerProviderConfig => ({
+ category: 'ai',
+ category_label: 'AI Providers',
+ color: '#8be9fd',
+ kind: 'apiKey',
+ icon_ref: '\u{1F916}',
+ stored: false,
+ ...over,
+});
+
+const baseProviders = (): ServerProviderConfig[] => [
+ makeProvider({ id: 'openai', name: 'OpenAI' }),
+ makeProvider({ id: 'anthropic', name: 'Anthropic' }),
+ makeProvider({ id: 'gemini', name: 'Gemini' }),
+ // Non-featured ai provider -> renders in the "more providers" chip row.
+ makeProvider({ id: 'groq', name: 'Groq' }),
+ // Non-ai provider -> must never render on this step.
+ makeProvider({
+ id: 'google',
+ name: 'Google Workspace',
+ category: 'google',
+ category_label: 'Google',
+ kind: 'oauth',
+ }),
+];
+
+const catalogue = (providers: ServerProviderConfig[]): CatalogueResponse => ({
+ providers,
+ categories: [],
+ version: 'test-v1',
+});
+
+const renderStep = (onOpenCredentials: () => void = vi.fn()) =>
+ renderWithProviders(<ConnectAIStep onOpenCredentials={onOpenCredentials} />);
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ catalogueData = catalogue(baseProviders());
+});
+
+// --- Tests ------------------------------------------------------------------
+
+describe('ConnectAIStep provider filtering', () => {
+ it('renders only ai-category providers', () => {
+ renderStep();
+ // Featured card.
+ expect(screen.getByText('Gemini')).toBeInTheDocument();
+ // Non-featured ai provider appears in the chip row.
+ expect(screen.getByText('Groq')).toBeInTheDocument();
+ // Non-ai category providers are filtered out entirely.
+ expect(screen.queryByText('Google Workspace')).not.toBeInTheDocument();
+ });
+});
+
+describe('ConnectAIStep featured cards', () => {
+ it('renders featured cards in openai/anthropic/gemini order with hardened key links', () => {
+ renderStep();
+
+ const links = screen.getAllByRole('link', { name: /get a key/i });
+ expect(links.map((l) => l.getAttribute('href'))).toEqual([
+ 'https://platform.openai.com/api-keys',
+ 'https://console.anthropic.com/settings/keys',
+ 'https://aistudio.google.com/apikey',
+ ]);
+ for (const link of links) {
+ expect(link).toHaveAttribute('target', '_blank');
+ expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+ }
+ });
+});
+
+describe('ConnectAIStep stored state', () => {
+ it('shows Connected badge, connected header, and Manage CTA when anthropic is stored', () => {
+ catalogueData = catalogue(
+ baseProviders().map((p) => (p.id === 'anthropic' ? { ...p, stored: true } : p)),
+ );
+ renderStep();
+
+ // Badge on the stored card.
+ expect(screen.getByText('Connected')).toBeInTheDocument();
+ // Header flips (curly apostrophe in the source -- match loosely).
+ expect(screen.getByText(/You.re connected/)).toBeInTheDocument();
+ expect(screen.queryByText('Connect your AI')).not.toBeInTheDocument();
+ // CTA flips.
+ expect(
+ screen.getByRole('button', { name: 'Manage AI accounts' }),
+ ).toBeInTheDocument();
+ // Stored card no longer offers a "Get a key" link; the other two do.
+ expect(screen.getAllByRole('link', { name: /get a key/i })).toHaveLength(2);
+ });
+
+ it('shows connect header, connect CTA, and trust microcopy when nothing is stored', () => {
+ renderStep();
+
+ expect(screen.getByText('Connect your AI')).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', { name: 'Connect your AI account' }),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByText(/Your key is saved only on this device/),
+ ).toBeInTheDocument();
+ expect(screen.queryByText('Connected')).not.toBeInTheDocument();
+ });
+});
+
+describe('ConnectAIStep loading state', () => {
+ it('renders skeletons while the catalogue is loading and keeps the CTA usable', async () => {
+ catalogueData = undefined;
+ const onOpenCredentials = vi.fn();
+ const { container } = renderStep(onOpenCredentials);
+
+ // One skeleton per featured provider.
+ expect(container.querySelectorAll('[data-slot="skeleton"]')).toHaveLength(3);
+ // No provider cards yet.
+ expect(screen.queryByText('OpenAI')).not.toBeInTheDocument();
+
+ // CTA renders (loading counts as "not connected") and still fires.
+ const cta = screen.getByRole('button', { name: 'Connect your AI account' });
+ await userEvent.click(cta);
+ expect(onOpenCredentials).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe('ConnectAIStep CTA', () => {
+ it('clicking the CTA calls onOpenCredentials exactly once', async () => {
+ const onOpenCredentials = vi.fn();
+ renderStep(onOpenCredentials);
+
+ await userEvent.click(
+ screen.getByRole('button', { name: 'Connect your AI account' }),
+ );
+ expect(onOpenCredentials).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/client/src/components/onboarding/__tests__/GetStartedChecklist.test.tsx b/client/src/components/onboarding/__tests__/GetStartedChecklist.test.tsx
new file mode 100644
index 00000000..6ff49ea5
--- /dev/null
+++ b/client/src/components/onboarding/__tests__/GetStartedChecklist.test.tsx
@@ -0,0 +1,160 @@
+/**
+ * Tests for GetStartedChecklist — the floating Get Started card.
+ *
+ * The hook contract is exhaustively tested in
+ * client/src/hooks/__tests__/useGetStarted.test.ts. This suite full-replace
+ * mocks the hook and locks the rendering contract:
+ * - renders null when not visible
+ * - header math ("N of M complete")
+ * - incomplete actionable items with a provided action render as buttons
+ * firing exactly that action; completed rows are non-clickable
+ * - collapse chevron -> pill ("Get started · N/M"); pill click re-expands
+ * - all-complete -> "You're all set!" + Done button dismisses
+ * - X dismisses (with toast)
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+
+// --- mocks (hoisted; closures dereference state at call time) ---------------
+
+const dismissMock = vi.fn();
+const restoreMock = vi.fn();
+
+const hookState = {
+ visible: true,
+ items: [] as Array<{ id: string; completed: boolean }>,
+ completedCount: 0,
+ totalCount: 5,
+};
+
+vi.mock('../../../hooks/useGetStarted', () => ({
+ useGetStarted: () => ({
+ visible: hookState.visible,
+ items: hookState.items,
+ completedCount: hookState.completedCount,
+ totalCount: hookState.totalCount,
+ dismiss: dismissMock,
+ restore: restoreMock,
+ }),
+}));
+
+const toastInfoMock = vi.fn();
+vi.mock('sonner', () => ({
+ toast: {
+ info: (...args: unknown[]) => toastInfoMock(...args),
+ error: vi.fn(),
+ success: vi.fn(),
+ message: vi.fn(),
+ warning: vi.fn(),
+ },
+}));
+
+import GetStartedChecklist from '../GetStartedChecklist';
+import { GET_STARTED_ITEMS, type GetStartedItemId } from '../getStartedItems';
+
+// --- helpers -----------------------------------------------------------------
+
+function setItems(completedIds: GetStartedItemId[]) {
+ hookState.items = GET_STARTED_ITEMS.map((item) => ({
+ id: item.id,
+ completed: completedIds.includes(item.id),
+ }));
+ hookState.completedCount = completedIds.length;
+ hookState.totalCount = GET_STARTED_ITEMS.length;
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ hookState.visible = true;
+ setItems(['setup', 'add-key']); // default: 2 of 5 complete
+});
+
+// ---------------------------------------------------------------------------
+
+describe('GetStartedChecklist', () => {
+ it('renders nothing when not visible', () => {
+ hookState.visible = false;
+ const { container } = render(<GetStartedChecklist />);
+ expect(container).toBeEmptyDOMElement();
+ });
+
+ it('renders the header with completion math', () => {
+ render(<GetStartedChecklist />);
+ expect(screen.getByText('Get started')).toBeInTheDocument();
+ expect(screen.getByText('2 of 5 complete')).toBeInTheDocument();
+ // All five item labels render.
+ for (const item of GET_STARTED_ITEMS) {
+ expect(screen.getByText(item.label)).toBeInTheDocument();
+ }
+ });
+
+ it('fires the matching action for an incomplete actionable item', () => {
+ const chatAction = vi.fn();
+ const buildAction = vi.fn();
+ render(
+ <GetStartedChecklist
+ actions={{ 'chat-example': chatAction, 'build-workflow': buildAction }}
+ />,
+ );
+
+ fireEvent.click(
+ screen.getByRole('button', { name: /Chat with your AI Assistant/ }),
+ );
+ expect(chatAction).toHaveBeenCalledTimes(1);
+ expect(buildAction).not.toHaveBeenCalled();
+ });
+
+ it('renders a completed item as a non-clickable row even when an action is provided', () => {
+ setItems(['setup', 'chat-example']);
+ const chatAction = vi.fn();
+ render(<GetStartedChecklist actions={{ 'chat-example': chatAction }} />);
+
+ const label = screen.getByText('Chat with your AI Assistant');
+ expect(label.closest('button')).toBeNull();
+ });
+
+ it('renders an incomplete actionable item without a provided action as a plain row', () => {
+ render(<GetStartedChecklist />); // no actions prop at all
+ const label = screen.getByText('Add your AI key');
+ expect(label.closest('button')).toBeNull();
+ });
+
+ it('collapses to a pill showing "Get started · N/M" and re-expands on pill click', () => {
+ render(<GetStartedChecklist />);
+
+ fireEvent.click(screen.getByLabelText('Collapse checklist'));
+
+ // Collapsed view is a single pill button.
+ expect(screen.queryByText('2 of 5 complete')).not.toBeInTheDocument();
+ const pill = screen.getByRole('button');
+ expect(pill).toHaveTextContent('Get started · 2/5');
+
+ fireEvent.click(pill);
+ expect(screen.getByText('2 of 5 complete')).toBeInTheDocument();
+ });
+
+ it('shows "You\'re all set!" and a Done button that dismisses when everything is complete', () => {
+ setItems(['setup', 'add-key', 'chat-example', 'build-workflow', 'try-theme']);
+ render(<GetStartedChecklist />);
+
+ expect(screen.getByText("You're all set!")).toBeInTheDocument();
+ expect(screen.getByText('5 of 5 complete')).toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole('button', { name: /Done/ }));
+ expect(dismissMock).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not show the Done affordance while incomplete', () => {
+ render(<GetStartedChecklist />);
+ expect(screen.queryByText("You're all set!")).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: /Done/ })).not.toBeInTheDocument();
+ });
+
+ it('X dismisses the checklist and toasts', () => {
+ render(<GetStartedChecklist />);
+ fireEvent.click(screen.getByLabelText('Dismiss checklist'));
+ expect(dismissMock).toHaveBeenCalledTimes(1);
+ expect(toastInfoMock).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/client/src/components/onboarding/__tests__/HowItWorksStep.test.tsx b/client/src/components/onboarding/__tests__/HowItWorksStep.test.tsx
new file mode 100644
index 00000000..c44df982
--- /dev/null
+++ b/client/src/components/onboarding/__tests__/HowItWorksStep.test.tsx
@@ -0,0 +1,96 @@
+/**
+ * HowItWorksStep behavioural tests.
+ *
+ * useNodeGroups is module-mocked (full replace) so the step renders against
+ * a controlled groups payload without WebSocket / TanStack plumbing.
+ *
+ * Locks in:
+ * - Badge chips render ONLY for groups with visibility 'normal' or 'all'
+ * ('dev' groups are filtered out)
+ * - when groups data is undefined, the sentence renders without chips and
+ * the three concept cards still render
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { screen } from '@testing-library/react';
+import { renderWithProviders } from '../../../test/providers';
+
+import type { NodeGroupEntry } from '../../../lib/nodeSpec';
+
+// --- Mocks (declared BEFORE importing the component -- vi.mock is hoisted) --
+
+let groupsData: Record<string, NodeGroupEntry> | undefined;
+
+vi.mock('../../../lib/nodeSpec', () => ({
+ useNodeGroups: () => ({ data: groupsData }),
+}));
+
+import HowItWorksStep from '../steps/HowItWorksStep';
+
+// --- Fixtures ---------------------------------------------------------------
+
+const entry = (
+ label: string,
+ visibility: NodeGroupEntry['visibility'],
+): NodeGroupEntry => ({
+ types: [],
+ label,
+ icon: '\u{1F916}',
+ color: '#bd93f9',
+ visibility,
+});
+
+const CONCEPT_TITLES = [
+ 'Snap blocks together',
+ 'Agents do the thinking',
+ 'Chat to make it go',
+];
+
+beforeEach(() => {
+ groupsData = undefined;
+});
+
+// --- Tests ------------------------------------------------------------------
+
+describe('HowItWorksStep group chips', () => {
+ it('renders chips for normal + all visibility groups and filters out dev groups', () => {
+ groupsData = {
+ agent: entry('AI Agents', 'normal'),
+ model: entry('AI Models', 'all'),
+ android: entry('Android', 'dev'),
+ };
+ renderWithProviders(<HowItWorksStep />);
+
+ expect(screen.getByText('AI Agents')).toBeInTheDocument();
+ expect(screen.getByText('AI Models')).toBeInTheDocument();
+ expect(screen.queryByText('Android')).not.toBeInTheDocument();
+ });
+
+ it('renders the toolbar sentence without chips when groups data is undefined', () => {
+ groupsData = undefined;
+ const { container } = renderWithProviders(<HowItWorksStep />);
+
+ expect(container.querySelectorAll('[data-slot="badge"]')).toHaveLength(0);
+ expect(
+ screen.getByText(/Normal shows just the AI blocks/),
+ ).toBeInTheDocument();
+ });
+});
+
+describe('HowItWorksStep concept cards', () => {
+ it('always renders the three concept cards (with groups data)', () => {
+ groupsData = { agent: entry('AI Agents', 'normal') };
+ renderWithProviders(<HowItWorksStep />);
+ for (const title of CONCEPT_TITLES) {
+ expect(screen.getByText(title)).toBeInTheDocument();
+ }
+ });
+
+ it('always renders the three concept cards (without groups data)', () => {
+ groupsData = undefined;
+ renderWithProviders(<HowItWorksStep />);
+ for (const title of CONCEPT_TITLES) {
+ expect(screen.getByText(title)).toBeInTheDocument();
+ }
+ });
+});
diff --git a/client/src/components/onboarding/__tests__/OnboardingWizard.test.tsx b/client/src/components/onboarding/__tests__/OnboardingWizard.test.tsx
new file mode 100644
index 00000000..9f4636c4
--- /dev/null
+++ b/client/src/components/onboarding/__tests__/OnboardingWizard.test.tsx
@@ -0,0 +1,227 @@
+/**
+ * OnboardingWizard behavioural tests.
+ *
+ * The wizard's state machine lives in useOnboarding (tested separately in
+ * src/hooks/__tests__/useOnboarding.steps.test.ts). Here the hook is fully
+ * mocked so each test pins the wizard at a known step and asserts:
+ * - the 4-step rail renders every step title
+ * - step dispatch by index (ConnectAI stub at index 2, with
+ * onOpenCredentials passed through)
+ * - footer nav wiring: Back hidden on step 0, Next -> nextStep,
+ * final "Open AI Assistant" -> complete() then onFinish() (in order),
+ * "Skip for now" / modal close -> skip() and NEVER onFinish()
+ * - visibility gate: renders nothing unless isVisible && hasChecked
+ * && !isLoading
+ *
+ * Step children that consume live hooks (catalogue / node groups) are
+ * stubbed; the pure steps (Welcome, TryIt) render for real.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type { ComponentProps } from 'react';
+import { renderWithProviders } from '../../../test/providers';
+
+// --- Mocks (declared BEFORE importing the wizard -- vi.mock is hoisted) -----
+
+const nextStep = vi.fn();
+const prevStep = vi.fn();
+const skip = vi.fn();
+const complete = vi.fn();
+
+interface HookState {
+ isVisible: boolean;
+ currentStep: number;
+ isCompleted: boolean;
+ isLoading: boolean;
+ hasChecked: boolean;
+ totalSteps: number;
+}
+
+let hookState: HookState;
+
+// Full-module replace (the importActual+spread variant is documented broken
+// under React 19 for context-backed modules; full replace is the canonical
+// pattern -- see CredentialsModal.test.tsx).
+vi.mock('../../../hooks/useOnboarding', () => ({
+ useOnboarding: () => ({
+ ...hookState,
+ nextStep,
+ prevStep,
+ skip,
+ complete,
+ }),
+}));
+
+// Stub the step children that consume live hooks (useCatalogueQuery /
+// useNodeGroups). They have their own dedicated suites.
+vi.mock('../steps/ConnectAIStep', () => ({
+ default: ({ onOpenCredentials }: { onOpenCredentials: () => void }) => (
+ <button type="button" data-testid="connect-ai-stub" onClick={onOpenCredentials}>
+ ConnectAIStep stub
+ </button>
+ ),
+}));
+
+vi.mock('../steps/HowItWorksStep', () => ({
+ default: () => <div data-testid="how-it-works-stub" />,
+}));
+
+import OnboardingWizard from '../OnboardingWizard';
+
+const RAIL_LABELS = ['Welcome', 'How it works', 'Connect your AI', 'Try it'];
+
+const renderWizard = (
+ props: Partial<ComponentProps<typeof OnboardingWizard>> = {},
+) =>
+ renderWithProviders(
+ <OnboardingWizard onOpenCredentials={props.onOpenCredentials ?? vi.fn()} {...props} />,
+ );
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ hookState = {
+ isVisible: true,
+ currentStep: 0,
+ isCompleted: false,
+ isLoading: false,
+ hasChecked: true,
+ totalSteps: 4,
+ };
+});
+
+describe('OnboardingWizard progress rail', () => {
+ it('renders all four step rail labels', () => {
+ renderWizard();
+ for (const label of RAIL_LABELS) {
+ expect(screen.getByText(label)).toBeInTheDocument();
+ }
+ });
+});
+
+describe('OnboardingWizard step dispatch', () => {
+ it('renders the ConnectAI step at index 2 and passes onOpenCredentials through', async () => {
+ hookState.currentStep = 2;
+ const onOpenCredentials = vi.fn();
+ renderWizard({ onOpenCredentials });
+
+ const stub = screen.getByTestId('connect-ai-stub');
+ expect(stub).toBeInTheDocument();
+ // Steps for other indices are not mounted.
+ expect(screen.queryByTestId('how-it-works-stub')).not.toBeInTheDocument();
+
+ await userEvent.click(stub);
+ expect(onOpenCredentials).toHaveBeenCalledTimes(1);
+ });
+
+ it('renders the HowItWorks step at index 1', () => {
+ hookState.currentStep = 1;
+ renderWizard();
+ expect(screen.getByTestId('how-it-works-stub')).toBeInTheDocument();
+ expect(screen.queryByTestId('connect-ai-stub')).not.toBeInTheDocument();
+ });
+});
+
+describe('OnboardingWizard footer navigation', () => {
+ it('hides the Back button on the first step', () => {
+ renderWizard();
+ expect(screen.queryByRole('button', { name: /back/i })).not.toBeInTheDocument();
+ });
+
+ it('shows Back from step 1 onward and clicking it calls prevStep', async () => {
+ hookState.currentStep = 1;
+ renderWizard();
+ const back = screen.getByRole('button', { name: /back/i });
+ await userEvent.click(back);
+ expect(prevStep).toHaveBeenCalledTimes(1);
+ });
+
+ it('clicking Next calls nextStep', async () => {
+ renderWizard();
+ await userEvent.click(screen.getByRole('button', { name: /next/i }));
+ expect(nextStep).toHaveBeenCalledTimes(1);
+ });
+
+ it('shows "Open AI Assistant" instead of Next on the last step', () => {
+ hookState.currentStep = 3;
+ renderWizard();
+ expect(screen.getByRole('button', { name: 'Open AI Assistant' })).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: /next/i })).not.toBeInTheDocument();
+ });
+
+ it('final button calls complete then onFinish, each exactly once, complete first', async () => {
+ hookState.currentStep = 3;
+ const onFinish = vi.fn();
+ renderWizard({ onFinish });
+
+ await userEvent.click(screen.getByRole('button', { name: 'Open AI Assistant' }));
+
+ expect(complete).toHaveBeenCalledTimes(1);
+ expect(onFinish).toHaveBeenCalledTimes(1);
+ // complete() must run before onFinish() (handleFinish contract).
+ expect(complete.mock.invocationCallOrder[0]).toBeLessThan(
+ onFinish.mock.invocationCallOrder[0],
+ );
+ // Skipping paths untouched.
+ expect(skip).not.toHaveBeenCalled();
+ });
+
+ it('final button does not throw when onFinish is omitted', async () => {
+ hookState.currentStep = 3;
+ renderWizard(); // no onFinish prop
+ await userEvent.click(screen.getByRole('button', { name: 'Open AI Assistant' }));
+ expect(complete).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe('OnboardingWizard skip paths never call onFinish', () => {
+ it('"Skip for now" calls skip and never onFinish/complete', async () => {
+ const onFinish = vi.fn();
+ renderWizard({ onFinish });
+
+ await userEvent.click(screen.getByRole('button', { name: /skip for now/i }));
+
+ expect(skip).toHaveBeenCalledTimes(1);
+ expect(onFinish).not.toHaveBeenCalled();
+ expect(complete).not.toHaveBeenCalled();
+ });
+
+ it('modal close (X) calls skip and never onFinish/complete', async () => {
+ const onFinish = vi.fn();
+ renderWizard({ onFinish });
+
+ // Modal's DialogClose carries aria-label="Close". Radix may fire both the
+ // explicit onClick and onOpenChange(false), so assert >= 1 call rather
+ // than an exact count -- the contract under test is "skip, not finish".
+ await userEvent.click(screen.getByRole('button', { name: /close/i }));
+
+ expect(skip.mock.calls.length).toBeGreaterThanOrEqual(1);
+ expect(onFinish).not.toHaveBeenCalled();
+ expect(complete).not.toHaveBeenCalled();
+ });
+});
+
+describe('OnboardingWizard visibility gate', () => {
+ it('renders nothing when isVisible is false', () => {
+ hookState.isVisible = false;
+ const { container } = renderWizard();
+ expect(container).toBeEmptyDOMElement();
+ // Portal content absent too.
+ expect(screen.queryByText('Welcome Guide')).not.toBeInTheDocument();
+ });
+
+ it('renders nothing before the settings check completes (hasChecked false)', () => {
+ hookState.hasChecked = false;
+ hookState.isLoading = true;
+ const { container } = renderWizard();
+ expect(container).toBeEmptyDOMElement();
+ expect(screen.queryByText('Welcome Guide')).not.toBeInTheDocument();
+ });
+
+ it('renders nothing while isLoading is true', () => {
+ hookState.isLoading = true;
+ const { container } = renderWizard();
+ expect(container).toBeEmptyDOMElement();
+ });
+});
diff --git a/client/src/components/onboarding/aiProviderLinks.ts b/client/src/components/onboarding/aiProviderLinks.ts
new file mode 100644
index 00000000..e90be02d
--- /dev/null
+++ b/client/src/components/onboarding/aiProviderLinks.ts
@@ -0,0 +1,21 @@
+/**
+ * Featured AI providers for onboarding surfaces (wizard + Get Started
+ * checklist). Only marketing hints and key-page URLs live here — display
+ * name, icon, and stored state come from the live credential catalogue
+ * (`useCatalogueQuery`), which is the single source of truth.
+ */
+
+export interface FeaturedAiProvider {
+ /** Catalogue provider id (`ServerProviderConfig.id`). */
+ id: string;
+ /** One-line plain-language hint shown under the provider name. */
+ hint: string;
+ /** Direct link to the page where the user generates an API key. */
+ keyUrl: string;
+}
+
+export const FEATURED_AI_PROVIDERS: FeaturedAiProvider[] = [
+ { id: 'openai', hint: 'Runs GPT models', keyUrl: 'https://platform.openai.com/api-keys' },
+ { id: 'anthropic', hint: 'Runs Claude models', keyUrl: 'https://console.anthropic.com/settings/keys' },
+ { id: 'gemini', hint: 'Runs Gemini models', keyUrl: 'https://aistudio.google.com/apikey' },
+];
diff --git a/client/src/components/onboarding/getStartedItems.ts b/client/src/components/onboarding/getStartedItems.ts
new file mode 100644
index 00000000..47fd1937
--- /dev/null
+++ b/client/src/components/onboarding/getStartedItems.ts
@@ -0,0 +1,61 @@
+import type { LucideIcon } from 'lucide-react';
+import { Sparkles, KeyRound, MessageCircle, Workflow, Palette } from 'lucide-react';
+
+export type GetStartedItemId =
+ | 'setup'
+ | 'add-key'
+ | 'chat-example'
+ | 'build-workflow'
+ | 'try-theme';
+
+export interface GetStartedItemDef {
+ id: GetStartedItemId;
+ /** Verb-first label. */
+ label: string;
+ sublabel: string;
+ icon: LucideIcon;
+ /** Whether clicking the row performs an action (wired by Dashboard). */
+ actionable: boolean;
+}
+
+/** The three seeded example workflow names — used to tell "built your own
+ * workflow" apart from editing a shipped example. */
+export const EXAMPLE_WORKFLOW_NAMES = ['AI Assistant', 'AI Employee', 'Claude Assistant'];
+
+export const GET_STARTED_ITEMS: GetStartedItemDef[] = [
+ {
+ id: 'setup',
+ label: 'Set up your workspace',
+ sublabel: 'OpenCompany is installed and running',
+ icon: Sparkles,
+ actionable: false,
+ },
+ {
+ id: 'add-key',
+ label: 'Add your AI key',
+ sublabel: 'Connect OpenAI, Anthropic, or another provider',
+ icon: KeyRound,
+ actionable: true,
+ },
+ {
+ id: 'chat-example',
+ label: 'Chat with your AI Assistant',
+ sublabel: 'Say hello to the ready-made example',
+ icon: MessageCircle,
+ actionable: true,
+ },
+ {
+ id: 'build-workflow',
+ label: 'Build your own workflow',
+ sublabel: 'Start from a blank canvas and save it',
+ icon: Workflow,
+ actionable: true,
+ },
+ {
+ id: 'try-theme',
+ label: 'Try a new look',
+ sublabel: 'Pick one of 12 visual themes',
+ icon: Palette,
+ actionable: false,
+ },
+];
diff --git a/client/src/components/onboarding/nodeRoleClasses.ts b/client/src/components/onboarding/nodeRoleClasses.ts
index 199c9785..dfc57875 100644
--- a/client/src/components/onboarding/nodeRoleClasses.ts
+++ b/client/src/components/onboarding/nodeRoleClasses.ts
@@ -1,8 +1,8 @@
/**
* Shared role-to-Tailwind-classes map for the onboarding step cards.
* Each role keys into the existing `--node-X` triplet (soft bg + border
- * + accent text). Co-located with the onboarding folder because both
- * consumers (ConceptsStep, GetStartedStep) live here.
+ * + accent text). Co-located with the onboarding folder because all
+ * consumers (the wizard steps) live here.
*/
export type NodeRole = 'model' | 'skill' | 'agent' | 'workflow' | 'trigger';
diff --git a/client/src/components/onboarding/steps/ApiKeyStep.tsx b/client/src/components/onboarding/steps/ApiKeyStep.tsx
deleted file mode 100644
index 64cae29c..00000000
--- a/client/src/components/onboarding/steps/ApiKeyStep.tsx
+++ /dev/null
@@ -1,70 +0,0 @@
-import React from 'react';
-import { Key, ExternalLink } from 'lucide-react';
-
-import { Button } from '@/components/ui/button';
-import { Alert, AlertDescription } from '@/components/ui/alert';
-import {
- OpenAIIcon, ClaudeIcon, GeminiIcon, GroqIcon, OpenRouterIcon, CerebrasIcon,
-} from '../../icons/AIProviderIcons';
-
-interface ApiKeyStepProps {
- onOpenCredentials: () => void;
-}
-
-const providers = [
- { name: 'OpenAI', icon: <OpenAIIcon />, desc: 'GPT-4o, o3, o4 models', url: 'platform.openai.com' },
- { name: 'Anthropic', icon: <ClaudeIcon />, desc: 'Claude Opus, Sonnet models', url: 'console.anthropic.com' },
- { name: 'Gemini', icon: <GeminiIcon />, desc: 'Gemini Pro, Flash models', url: 'aistudio.google.com' },
- { name: 'Groq', icon: <GroqIcon />, desc: 'Ultra-fast Llama, Qwen', url: 'console.groq.com' },
- { name: 'OpenRouter', icon: <OpenRouterIcon />, desc: 'Access 200+ models', url: 'openrouter.ai' },
- { name: 'Cerebras', icon: <CerebrasIcon />, desc: 'Fast inference on custom HW', url: 'cloud.cerebras.ai' },
-];
-
-const ApiKeyStep: React.FC<ApiKeyStepProps> = ({ onOpenCredentials }) => {
- return (
- <div className="py-1">
- <div className="mb-4 text-center">
- <h4 className="m-0 mb-1 flex items-center justify-center gap-2 text-lg font-semibold">
- <Key className="h-4 w-4 text-warning" />
- API Key Setup
- </h4>
- <p className="text-xs text-muted-foreground">
- Configure at least one AI provider to use AI agents
- </p>
- </div>
-
- <div className="flex w-full flex-col gap-2">
- {providers.map((p) => (
- <div
- key={p.name}
- className="flex items-center gap-2.5 rounded-md border border-border bg-muted/50 px-3 py-2"
- >
- <div className="flex h-6 w-6 shrink-0 items-center justify-center">{p.icon}</div>
- <div className="min-w-0 flex-1">
- <div className="block text-sm font-semibold">{p.name}</div>
- <div className="text-xs text-muted-foreground">{p.desc}</div>
- </div>
- <div className="flex items-center gap-1 text-[10px] text-muted-foreground">
- <ExternalLink className="h-3 w-3" /> {p.url}
- </div>
- </div>
- ))}
- </div>
-
- <div className="mt-5 text-center">
- <Button onClick={onOpenCredentials} className="gap-2">
- <Key className="h-4 w-4" />
- Open Credentials
- </Button>
- </div>
-
- <Alert variant="info" className="mt-4">
- <AlertDescription className="text-xs">
- You can always change API keys later from the toolbar credentials button.
- </AlertDescription>
- </Alert>
- </div>
- );
-};
-
-export default ApiKeyStep;
diff --git a/client/src/components/onboarding/steps/CanvasStep.tsx b/client/src/components/onboarding/steps/CanvasStep.tsx
deleted file mode 100644
index 250a3b83..00000000
--- a/client/src/components/onboarding/steps/CanvasStep.tsx
+++ /dev/null
@@ -1,101 +0,0 @@
-import React from 'react';
-import { Layout, Wrench, Terminal } from 'lucide-react';
-import { Badge } from '@/components/ui/badge';
-
-const CanvasStep: React.FC = () => {
- const shortcuts = [
- { keys: 'Ctrl+S', action: 'Save workflow' },
- { keys: 'F2', action: 'Rename node' },
- { keys: 'Delete', action: 'Remove node' },
- { keys: 'Ctrl+C', action: 'Copy node' },
- ];
-
- return (
- <div className="py-1">
- <div className="mb-4 text-center">
- <h4 className="m-0 mb-1 text-lg font-semibold">Canvas Tour</h4>
- <p className="text-xs text-muted-foreground">
- Navigate the main interface regions
- </p>
- </div>
-
- {/*
- * Visual layout diagram. Region tints mirror the live UI's
- * accent colours via the predefined --node-X-soft tokens — no
- * opacity arithmetic at the call site. Each region maps to a
- * node-group colour: toolbar→workflow, sidebar→model,
- * canvas→agent, palette→skill, console→trigger. Both the region
- * tints (--node-X-soft) and the text/icon accents (text-node-X)
- * use the role tokens, so the diagram tracks every theme.
- */}
- <div className="mb-4 overflow-hidden rounded-lg border border-border">
- {/* Toolbar */}
- <div className="flex items-center gap-1.5 border-b border-border bg-node-workflow-soft px-2.5 py-1.5">
- <Wrench className="h-3 w-3 text-node-workflow" />
- <span className="text-xs font-semibold text-node-workflow">Toolbar</span>
- <div className="flex-1" />
- <Badge variant="warning" className="text-[10px]">Run</Badge>
- <Badge variant="secondary" className="text-[10px]">Start</Badge>
- <Badge variant="info" className="text-[10px]">Save</Badge>
- </div>
-
- {/* Main area */}
- <div className="flex h-[120px]">
- {/* Sidebar */}
- <div className="flex w-20 flex-col gap-1 border-r border-border bg-node-model-soft p-1.5">
- <span className="text-[9px] font-semibold text-node-model">Sidebar</span>
- {['Workflow 1', 'Workflow 2'].map((w) => (
- <div key={w} className="rounded-sm bg-muted px-1 py-0.5 text-[8px] text-muted-foreground">
- {w}
- </div>
- ))}
- </div>
-
- {/* Canvas */}
- <div className="relative flex flex-1 items-center justify-center bg-node-agent-soft">
- <div className="text-center">
- <Layout className="mx-auto h-5 w-5 text-node-agent opacity-50" />
- <div className="mt-0.5 text-[9px] text-node-agent">Canvas</div>
- </div>
- </div>
-
- {/* Palette */}
- <div className="flex w-20 flex-col gap-1 border-l border-border bg-node-skill-soft p-1.5">
- <span className="text-[9px] font-semibold text-node-skill">Palette</span>
- {['AI Agents', 'AI Models', 'Skills'].map((c) => (
- <div key={c} className="rounded-sm bg-muted px-1 py-0.5 text-[8px] text-muted-foreground">
- {c}
- </div>
- ))}
- </div>
- </div>
-
- {/* Console */}
- <div className="flex items-center gap-1.5 border-t border-border bg-node-trigger-soft px-2.5 py-1.5">
- <Terminal className="h-3 w-3 text-node-trigger" />
- <span className="text-xs font-semibold text-node-trigger">Console</span>
- <div className="flex-1" />
- <Badge variant="outline" className="text-[9px]">Chat</Badge>
- <Badge variant="outline" className="text-[9px]">Logs</Badge>
- </div>
- </div>
-
- {/* Keyboard shortcuts */}
- <div>
- <div className="mb-2 block text-xs font-semibold">Keyboard Shortcuts</div>
- <div className="flex flex-wrap items-center gap-x-2 gap-y-1.5">
- {shortcuts.map((s) => (
- <span key={s.keys} className="inline-flex items-center gap-1.5 text-xs">
- <Badge variant="outline" className="font-mono text-[11px]">
- {s.keys}
- </Badge>
- <span className="text-xs text-muted-foreground">{s.action}</span>
- </span>
- ))}
- </div>
- </div>
- </div>
- );
-};
-
-export default CanvasStep;
diff --git a/client/src/components/onboarding/steps/ConceptsStep.tsx b/client/src/components/onboarding/steps/ConceptsStep.tsx
deleted file mode 100644
index d2fe87b5..00000000
--- a/client/src/components/onboarding/steps/ConceptsStep.tsx
+++ /dev/null
@@ -1,75 +0,0 @@
-import React from 'react';
-import { LayoutGrid, GitBranch, Bot, Wrench, ArrowLeftRight } from 'lucide-react';
-import { NODE_ROLE_CLASSES, type NodeRole } from '../nodeRoleClasses';
-
-const concepts: { Icon: typeof LayoutGrid; title: string; desc: string; role: NodeRole }[] = [
- {
- Icon: LayoutGrid,
- title: 'Nodes',
- desc: 'Building blocks of your workflow. Each node performs a specific action like sending a message, calling an AI model, or processing data.',
- role: 'model',
- },
- {
- Icon: GitBranch,
- title: 'Edges',
- desc: "Connections between nodes that define data flow. Drag from one node's output to another's input to connect them.",
- role: 'skill',
- },
- {
- Icon: Bot,
- title: 'AI Agents',
- desc: 'Intelligent nodes that use LLMs (Claude, GPT, Gemini) to reason, call tools, and complete tasks autonomously.',
- role: 'agent',
- },
- {
- Icon: Wrench,
- title: 'Skills & Tools',
- desc: 'Connect skills and tools to agents to extend their capabilities. Skills provide instructions, tools provide actions.',
- role: 'workflow',
- },
- {
- Icon: ArrowLeftRight,
- title: 'Normal vs Dev Mode',
- desc: 'Normal mode shows AI-focused nodes for simple workflows. Dev mode unlocks all 108+ nodes for advanced automation.',
- role: 'trigger',
- },
-];
-
-const ConceptsStep: React.FC = () => {
- return (
- <div className="py-1">
- <div className="mb-4 text-center">
- <h4 className="m-0 mb-1 text-lg font-semibold">Key Concepts</h4>
- <p className="text-xs text-muted-foreground">
- Understanding these will help you build powerful workflows
- </p>
- </div>
-
- <div className="flex w-full flex-col gap-2.5">
- {concepts.map((c) => {
- const classes = NODE_ROLE_CLASSES[c.role];
- return (
- <div
- key={c.title}
- className={`flex items-start gap-3 rounded-md border p-3 ${classes.card}`}
- >
- <div className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-md ${classes.card}`}>
- <c.Icon className={`h-4 w-4 ${classes.text}`} />
- </div>
- <div className="min-w-0 flex-1">
- <div className={`mb-0.5 text-sm font-semibold ${classes.text}`}>
- {c.title}
- </div>
- <p className="m-0 text-xs leading-relaxed text-muted-foreground">
- {c.desc}
- </p>
- </div>
- </div>
- );
- })}
- </div>
- </div>
- );
-};
-
-export default ConceptsStep;
diff --git a/client/src/components/onboarding/steps/ConnectAIStep.tsx b/client/src/components/onboarding/steps/ConnectAIStep.tsx
new file mode 100644
index 00000000..4b8f6d47
--- /dev/null
+++ b/client/src/components/onboarding/steps/ConnectAIStep.tsx
@@ -0,0 +1,146 @@
+import React from 'react';
+import { KeyRound, Check, ExternalLink, ShieldCheck } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Badge } from '@/components/ui/badge';
+import { Skeleton } from '@/components/ui/skeleton';
+import { NodeIcon } from '../../../assets/icons';
+import { useCatalogueQuery, type ServerProviderConfig } from '../../../hooks/useCatalogueQuery';
+import { FEATURED_AI_PROVIDERS } from '../aiProviderLinks';
+
+interface ConnectAIStepProps {
+ onOpenCredentials: () => void;
+}
+
+const ConnectAIStep: React.FC<ConnectAIStepProps> = ({ onOpenCredentials }) => {
+ const catalogueQuery = useCatalogueQuery();
+ const providers = catalogueQuery.data?.providers;
+
+ const aiProviders = React.useMemo(
+ () => (providers ?? []).filter((p) => p.category === 'ai'),
+ [providers],
+ );
+ const featured = FEATURED_AI_PROVIDERS
+ .map((entry) => {
+ const provider = aiProviders.find((p) => p.id === entry.id);
+ return provider ? { ...entry, provider } : null;
+ })
+ .filter((entry): entry is { id: string; hint: string; keyUrl: string; provider: ServerProviderConfig } => entry !== null);
+ const featuredIds = new Set(FEATURED_AI_PROVIDERS.map((entry) => entry.id));
+ const moreProviders = aiProviders.filter((p) => !featuredIds.has(p.id));
+ const connected = aiProviders.some((p) => p.stored);
+ const isLoading = providers === undefined;
+
+ return (
+ <div className="py-1">
+ <div className="mb-4 text-center">
+ <h4 className="m-0 mb-1 flex items-center justify-center gap-2 text-lg font-semibold">
+ {connected ? (
+ <>
+ <Check className="h-4 w-4 text-success" />
+ You&apos;re connected
+ </>
+ ) : (
+ <>
+ <KeyRound className="h-4 w-4 text-warning" />
+ Connect your AI
+ </>
+ )}
+ </h4>
+ <p className="text-xs text-muted-foreground">
+ {connected
+ ? 'Nice — your AI is ready to think.'
+ : 'Your agents need an AI account to think. Paste one key — it takes about a minute.'}
+ </p>
+ </div>
+
+ {isLoading ? (
+ <div className="grid grid-cols-3 gap-2">
+ {FEATURED_AI_PROVIDERS.map((entry) => (
+ <Skeleton key={entry.id} className="h-24 w-full" />
+ ))}
+ </div>
+ ) : (
+ <>
+ <div className="grid grid-cols-3 gap-2">
+ {featured.map(({ id, hint, keyUrl, provider }) => (
+ <div
+ key={id}
+ className="flex flex-col items-center gap-1 rounded-md border border-border bg-muted/50 px-3 py-3 text-center"
+ >
+ <NodeIcon icon={provider.icon_ref} className="h-6 w-6 shrink-0 text-lg" />
+ <span className="text-sm font-semibold">{provider.name}</span>
+ <span className="text-xs text-muted-foreground">{hint}</span>
+ {provider.stored ? (
+ <Badge variant="success" className="mt-1">
+ <Check className="h-3 w-3" />
+ Connected
+ </Badge>
+ ) : (
+ <a
+ href={keyUrl}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="mt-1 inline-flex items-center gap-1 text-[10px] text-muted-foreground hover:text-foreground"
+ >
+ <ExternalLink className="h-3 w-3" /> Get a key
+ </a>
+ )}
+ </div>
+ ))}
+ </div>
+
+ {moreProviders.length > 0 && (
+ <div className="mt-3 text-center">
+ <div className="flex flex-wrap items-center justify-center gap-1.5">
+ {moreProviders.map((p) => (
+ <span
+ key={p.id}
+ className="inline-flex items-center gap-1 rounded-full border border-border bg-muted/50 px-2 py-0.5 text-xs"
+ >
+ <NodeIcon icon={p.icon_ref} className="h-3.5 w-3.5 shrink-0 text-sm" />
+ {p.name}
+ {p.stored && <Check className="h-3 w-3 text-success" />}
+ </span>
+ ))}
+ </div>
+ <p className="mt-2 text-xs text-muted-foreground">
+ No account yet? Ollama and LM Studio run free models right on your computer — pick
+ one from the list.
+ </p>
+ </div>
+ )}
+ </>
+ )}
+
+ <div className="mt-5 text-center">
+ <Button
+ variant={connected ? 'outline' : 'default'}
+ onClick={onOpenCredentials}
+ className="gap-2"
+ >
+ <KeyRound className="h-4 w-4" />
+ {connected ? 'Manage AI accounts' : 'Connect your AI account'}
+ </Button>
+ </div>
+
+ {connected ? (
+ <Alert variant="success" className="mt-4">
+ <AlertDescription className="text-xs">
+ You can add another AI account or change your key anytime — click the key button in the
+ toolbar.
+ </AlertDescription>
+ </Alert>
+ ) : (
+ <p className="mt-4 flex items-center justify-center gap-1.5 text-xs text-muted-foreground">
+ <ShieldCheck className="h-3.5 w-3.5" />
+ Your key is saved only on this device. It&apos;s never shared with anyone except the AI you
+ choose.
+ </p>
+ )}
+ </div>
+ );
+};
+
+export default ConnectAIStep;
diff --git a/client/src/components/onboarding/steps/GetStartedStep.tsx b/client/src/components/onboarding/steps/GetStartedStep.tsx
deleted file mode 100644
index b83dd4b8..00000000
--- a/client/src/components/onboarding/steps/GetStartedStep.tsx
+++ /dev/null
@@ -1,88 +0,0 @@
-import React from 'react';
-import { Play, FlaskConical, BookOpen, Settings } from 'lucide-react';
-import { Card, CardContent } from '@/components/ui/card';
-import { Badge } from '@/components/ui/badge';
-import { NODE_ROLE_CLASSES, type NodeRole } from '../nodeRoleClasses';
-
-type Tip = {
- Icon: typeof Play;
- title: string;
- desc: React.ReactNode;
- role: NodeRole;
-};
-
-const tips: Tip[] = [
- {
- Icon: Play,
- title: 'Try an Example Workflow',
- desc: 'Open the sidebar and click on one of the pre-loaded example workflows to see how things work.',
- role: 'skill',
- },
- {
- Icon: FlaskConical,
- title: 'Build Your First Workflow',
- desc: (
- <>
- Quick recipe: drag{' '}
- <Badge variant="outline" className="mx-0.5 text-[10px]">Chat Trigger</Badge>
- <span className="text-xs text-muted-foreground">{'→'}</span>{' '}
- <Badge variant="outline" className="mx-0.5 text-[10px]">Zeenie</Badge>
- <span className="text-xs text-muted-foreground">{'→'}</span>{' '}
- <Badge variant="outline" className="mx-0.5 text-[10px]">Claude Model</Badge>
- {' '}then click{' '}
- <Badge variant="success" className="mx-0.5 text-[10px]">Run</Badge>
- </>
- ),
- role: 'agent',
- },
- {
- Icon: BookOpen,
- title: 'Explore AI Skills',
- desc: 'Use the Master Skill node to browse and enable built-in skills for your AI agents.',
- role: 'model',
- },
- {
- Icon: Settings,
- title: 'Revisit This Guide',
- desc: 'You can replay this welcome guide anytime from Settings.',
- role: 'workflow',
- },
-];
-
-const GetStartedStep: React.FC = () => {
- return (
- <div className="py-1">
- <div className="mb-4 text-center">
- <h4 className="m-0 mb-1 text-lg font-semibold">Get Started</h4>
- <p className="text-xs text-muted-foreground">
- Here are some things to try first
- </p>
- </div>
-
- <div className="flex w-full flex-col gap-2.5">
- {tips.map(({ Icon, title, desc, role }, i) => {
- const classes = NODE_ROLE_CLASSES[role];
- return (
- <Card key={i} className={classes.card}>
- <CardContent className="flex items-start gap-2.5 p-3">
- <div className={`flex h-7 w-7 shrink-0 items-center justify-center rounded-md ${classes.card}`}>
- <Icon className={`h-3.5 w-3.5 ${classes.text}`} />
- </div>
- <div className="min-w-0 flex-1">
- <div className={`mb-0.5 text-sm font-semibold ${classes.text}`}>
- {title}
- </div>
- <p className="m-0 text-xs leading-relaxed text-muted-foreground">
- {desc}
- </p>
- </div>
- </CardContent>
- </Card>
- );
- })}
- </div>
- </div>
- );
-};
-
-export default GetStartedStep;
diff --git a/client/src/components/onboarding/steps/HowItWorksStep.tsx b/client/src/components/onboarding/steps/HowItWorksStep.tsx
new file mode 100644
index 00000000..7f5c2956
--- /dev/null
+++ b/client/src/components/onboarding/steps/HowItWorksStep.tsx
@@ -0,0 +1,80 @@
+import React from 'react';
+import { LayoutGrid, Bot, MessageCircle } from 'lucide-react';
+import { Badge } from '@/components/ui/badge';
+import { useNodeGroups } from '../../../lib/nodeSpec';
+import { NODE_ROLE_CLASSES, type NodeRole } from '../nodeRoleClasses';
+
+const concepts: { Icon: typeof LayoutGrid; title: string; desc: string; role: NodeRole }[] = [
+ {
+ Icon: LayoutGrid,
+ title: 'Snap blocks together',
+ desc: 'Every project is made of simple blocks — a chat window, an AI brain, a web search. Drag them in from the right-hand panel and draw lines to connect them.',
+ role: 'model',
+ },
+ {
+ Icon: Bot,
+ title: 'Agents do the thinking',
+ desc: 'An agent is a block with a brain. Tell it what you want in plain English and it plans the steps, using the blocks connected to it.',
+ role: 'agent',
+ },
+ {
+ Icon: MessageCircle,
+ title: 'Chat to make it go',
+ desc: 'Press the green Start button at the top, then type in the chat panel at the bottom. Your agent answers right there.',
+ role: 'trigger',
+ },
+];
+
+const HowItWorksStep: React.FC = () => {
+ const groupsQuery = useNodeGroups();
+ const normalGroupLabels = Object.values(groupsQuery.data ?? {})
+ .filter((group) => group.visibility === 'normal' || group.visibility === 'all')
+ .map((group) => group.label);
+
+ return (
+ <div className="py-1">
+ <div className="mb-4 text-center">
+ <h4 className="m-0 mb-1 text-lg font-semibold">See how it works</h4>
+ <p className="text-xs text-muted-foreground">Three ideas are all you need.</p>
+ </div>
+
+ <div className="flex w-full flex-col gap-2.5">
+ {concepts.map((c) => {
+ const classes = NODE_ROLE_CLASSES[c.role];
+ return (
+ <div
+ key={c.title}
+ className={`flex items-start gap-3 rounded-md border p-3 ${classes.card}`}
+ >
+ <div className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-md ${classes.card}`}>
+ <c.Icon className={`h-4 w-4 ${classes.text}`} />
+ </div>
+ <div className="min-w-0 flex-1">
+ <div className={`mb-0.5 text-sm font-semibold ${classes.text}`}>{c.title}</div>
+ <p className="m-0 text-xs leading-relaxed text-muted-foreground">{c.desc}</p>
+ </div>
+ </div>
+ );
+ })}
+ </div>
+
+ <div className="mt-4 text-center text-xs text-muted-foreground">
+ <span>
+ The Normal / Dev switch in the toolbar keeps things simple. Normal shows just the AI blocks
+ </span>
+ {normalGroupLabels.length > 0 && (
+ <span className="mx-1 inline-flex flex-wrap items-center justify-center gap-1 align-middle">
+ {normalGroupLabels.map((label) => (
+ <Badge key={label} variant="outline" className="text-[10px]">
+ {label}
+ </Badge>
+ ))}
+ </span>
+ )}
+ <span> — flip to Dev when you want everything else.</span>
+ </div>
+ </div>
+ );
+};
+
+export default HowItWorksStep;
diff --git a/client/src/components/onboarding/steps/TryItStep.tsx b/client/src/components/onboarding/steps/TryItStep.tsx
new file mode 100644
index 00000000..cac3920e
--- /dev/null
+++ b/client/src/components/onboarding/steps/TryItStep.tsx
@@ -0,0 +1,99 @@
+import React from 'react';
+import { FolderOpen, Play, MessageCircle, Code, Users } from 'lucide-react';
+import { NODE_ROLE_CLASSES, type NodeRole } from '../nodeRoleClasses';
+
+const recipe: { Icon: typeof FolderOpen; title: string; desc: string; role: NodeRole }[] = [
+ {
+ Icon: FolderOpen,
+ title: 'Open AI Assistant',
+ desc: 'Find it in the sidebar on the left — a friendly helper that can search the web and manage files.',
+ role: 'skill',
+ },
+ {
+ Icon: Play,
+ title: 'Press the green Start button',
+ desc: "It's in the toolbar at the top. This wakes your agent up.",
+ role: 'agent',
+ },
+ {
+ Icon: MessageCircle,
+ title: 'Say hello',
+ desc: 'Type anything in the chat panel at the bottom of the screen. Your agent replies right there.',
+ role: 'trigger',
+ },
+];
+
+const explore: { Icon: typeof Code; title: string; desc: string; role: NodeRole }[] = [
+ {
+ Icon: Code,
+ title: 'Claude Assistant',
+ desc: 'An agent powered by Claude Code — great for coding help. Works best with an Anthropic key.',
+ role: 'model',
+ },
+ {
+ Icon: Users,
+ title: 'AI Employee',
+ desc: "A whole team of agents working together. Explore it once you're comfortable.",
+ role: 'workflow',
+ },
+];
+
+const TryItStep: React.FC = () => {
+ return (
+ <div className="py-1">
+ <div className="mb-4 text-center">
+ <h4 className="m-0 mb-1 text-lg font-semibold">Say hello to your first agent</h4>
+ <p className="text-xs text-muted-foreground">
+ Three examples are already waiting in your sidebar. Here&apos;s the fastest way in.
+ </p>
+ </div>
+
+ <div className="flex w-full flex-col gap-2.5">
+ {recipe.map((step, index) => {
+ const classes = NODE_ROLE_CLASSES[step.role];
+ return (
+ <div
+ key={step.title}
+ className={`flex items-start gap-3 rounded-md border p-3 ${classes.card}`}
+ >
+ <div className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-full ${classes.card}`}>
+ <span className={`text-sm font-semibold ${classes.text}`}>{index + 1}</span>
+ </div>
+ <div className="min-w-0 flex-1">
+ <div className={`mb-0.5 flex items-center gap-1.5 text-sm font-semibold ${classes.text}`}>
+ <step.Icon className="h-4 w-4" />
+ {step.title}
+ </div>
+ <p className="m-0 text-xs leading-relaxed text-muted-foreground">{step.desc}</p>
+ </div>
+ </div>
+ );
+ })}
+ </div>
+
+ <div className="mt-4 mb-2 text-center text-xs font-semibold text-muted-foreground">
+ More to explore
+ </div>
+ <div className="grid grid-cols-2 gap-2.5">
+ {explore.map((item) => {
+ const classes = NODE_ROLE_CLASSES[item.role];
+ return (
+ <div key={item.title} className={`rounded-md border p-3 ${classes.card}`}>
+ <div className={`mb-0.5 flex items-center gap-1.5 text-sm font-semibold ${classes.text}`}>
+ <item.Icon className="h-4 w-4" />
+ {item.title}
+ </div>
+ <p className="m-0 text-xs leading-relaxed text-muted-foreground">{item.desc}</p>
+ </div>
+ );
+ })}
+ </div>
+
+ <p className="mt-4 text-center text-xs text-muted-foreground">
+ You can replay this guide anytime from Settings.
+ </p>
+ </div>
+ );
+};
+
+export default TryItStep;
diff --git a/client/src/components/onboarding/steps/WelcomeStep.tsx b/client/src/components/onboarding/steps/WelcomeStep.tsx
index b5ba2df5..7bf67686 100644
--- a/client/src/components/onboarding/steps/WelcomeStep.tsx
+++ b/client/src/components/onboarding/steps/WelcomeStep.tsx
@@ -1,12 +1,13 @@
import React from 'react';
-import { Rocket, Plug, Move, Zap } from 'lucide-react';
+import { Rocket, Bot, Blocks, Plug, ShieldCheck } from 'lucide-react';
import { Card, CardContent } from '@/components/ui/card';
+import { NODE_ROLE_CLASSES, type NodeRole } from '../nodeRoleClasses';
-const features = [
- { Icon: Plug, label: '108+ Nodes', desc: 'Workflow building blocks' },
- { Icon: Rocket, label: '12 AI Providers', desc: 'OpenAI, Claude, Gemini & more' },
- { Icon: Move, label: 'Drag & Drop', desc: 'Visual workflow builder' },
- { Icon: Zap, label: 'Real-time', desc: 'Live execution & monitoring' },
+const features: { Icon: typeof Bot; label: string; desc: string; role: NodeRole }[] = [
+ { Icon: Bot, label: 'Agents that work for you', desc: 'Give them a goal; they figure out the steps.', role: 'agent' },
+ { Icon: Blocks, label: 'Build by dragging', desc: 'Snap blocks together — no code, no setup scripts.', role: 'model' },
+ { Icon: Plug, label: 'Bring your favorite AI', desc: 'Works with OpenAI, Claude, Gemini and more.', role: 'skill' },
+ { Icon: ShieldCheck, label: 'Yours and private', desc: 'Everything runs and stays on this device.', role: 'workflow' },
];
const WelcomeStep: React.FC = () => {
@@ -14,31 +15,31 @@ const WelcomeStep: React.FC = () => {
<div className="py-2 text-center">
<Rocket className="mx-auto mb-2 h-10 w-10 text-node-agent" />
- <h3 className="m-0 mb-1 text-xl font-semibold">Welcome to OpenCompany</h3>
+ <h3 className="m-0 mb-1 text-xl font-semibold">Build your own AI team</h3>
<p className="text-[15px] font-semibold text-node-agent">
- Visual workflow automation powered by AI agents
+ Helpful AI agents that chat with you and get real work done
</p>
<p className="mx-auto mt-4 mb-6 max-w-[480px] text-sm text-muted-foreground">
- OpenCompany lets you build intelligent automation workflows by connecting
- AI models, tools, and services together on an interactive canvas.
- No coding required for most tasks.
+ OpenCompany runs on your own computer. Snap building blocks together on
+ a visual canvas, connect your favorite AI, and watch your agents get to
+ work. No coding needed.
</p>
<div className="mx-auto grid max-w-[440px] grid-cols-2 gap-3">
- {features.map(({ Icon, label, desc }) => (
- <Card
- key={label}
- className="text-center bg-node-agent-soft border-node-agent-border"
- >
- <CardContent className="flex flex-col items-center gap-1 p-3">
- <Icon className="h-5 w-5 text-node-agent" />
- <span className="block text-sm font-semibold">{label}</span>
- <span className="text-xs text-muted-foreground">{desc}</span>
- </CardContent>
- </Card>
- ))}
+ {features.map(({ Icon, label, desc, role }) => {
+ const classes = NODE_ROLE_CLASSES[role];
+ return (
+ <Card key={label} className={`text-center ${classes.card}`}>
+ <CardContent className="flex flex-col items-center gap-1 p-3">
+ <Icon className={`h-5 w-5 ${classes.text}`} />
+ <span className="block text-sm font-semibold">{label}</span>
+ <span className="text-xs text-muted-foreground">{desc}</span>
+ </CardContent>
+ </Card>
+ );
+ })}
</div>
</div>
);
diff --git a/client/src/components/parameterPanel/MasterSkillEditor.tsx b/client/src/components/parameterPanel/MasterSkillEditor.tsx
index 1be0a015..3a40e95d 100644
--- a/client/src/components/parameterPanel/MasterSkillEditor.tsx
+++ b/client/src/components/parameterPanel/MasterSkillEditor.tsx
@@ -1,4 +1,3 @@
-/* eslint-disable react-hooks/exhaustive-deps -- userSkills/folderSkills are React-Query slices; dep arrays curated to avoid re-derivation on every refetch. */
/**
* MasterSkillEditor - Editor for Master Skill node
*
diff --git a/client/src/components/ui/ConsolePanel.tsx b/client/src/components/ui/ConsolePanel.tsx
index cf3be142..2b5c4f33 100644
--- a/client/src/components/ui/ConsolePanel.tsx
+++ b/client/src/components/ui/ConsolePanel.tsx
@@ -31,6 +31,7 @@ import {
} from '@/components/ui/select';
import { cn } from '@/lib/utils';
import { resolveNodeDescription } from '../../lib/nodeSpec';
+import { useAppStore } from '../../store/useAppStore';
// ---------------------------------------------------------------------------
// Persisted prefs (localStorage)
@@ -174,6 +175,18 @@ const ConsolePanel: React.FC<ConsolePanelProps> = ({
const chatEndRef = useRef<HTMLDivElement>(null);
const chatInputRef = useRef<HTMLInputElement>(null);
+ // Focus the chat input when requested (onboarding handoff, checklist).
+ // Each request is consumed once so later manual panel toggles don't
+ // re-steal focus.
+ const chatFocusRequest = useAppStore((s) => s.chatFocusRequest);
+ const handledFocusRequestRef = useRef(0);
+ useEffect(() => {
+ if (chatFocusRequest === handledFocusRequestRef.current || !isOpen) return;
+ handledFocusRequestRef.current = chatFocusRequest;
+ const frame = requestAnimationFrame(() => chatInputRef.current?.focus());
+ return () => cancelAnimationFrame(frame);
+ }, [chatFocusRequest, isOpen]);
+
const [chatInput, setChatInput] = useState('');
const [isSending, setIsSending] = useState(false);
const containerRef = useRef<HTMLDivElement>(null);
diff --git a/client/src/components/ui/SettingsPanel.tsx b/client/src/components/ui/SettingsPanel.tsx
index 97e7749a..3a092041 100644
--- a/client/src/components/ui/SettingsPanel.tsx
+++ b/client/src/components/ui/SettingsPanel.tsx
@@ -11,6 +11,7 @@ import {
RotateCcw,
X,
Volume2,
+ ListChecks,
} from 'lucide-react';
import { useAppStore } from '../../store/useAppStore';
@@ -41,6 +42,7 @@ interface SettingsPanelProps {
settings: WorkflowSettings;
onSettingsChange: (settings: WorkflowSettings) => void;
onReplayOnboarding?: () => void;
+ onShowGetStarted?: () => void;
}
// ---------------------------------------------------------------------------
@@ -106,6 +108,7 @@ const SettingsPanel: React.FC<SettingsPanelProps> = ({
settings,
onSettingsChange,
onReplayOnboarding,
+ onShowGetStarted,
}) => {
const settingsQuery = useUserSettingsQuery();
const saveMutation = useSaveUserSettingsMutation();
@@ -419,6 +422,20 @@ const SettingsPanel: React.FC<SettingsPanelProps> = ({
Replay
</Button>
</Row>
+ <Row
+ label="Get Started Checklist"
+ description="Show the getting-started checklist on the canvas"
+ >
+ <Button
+ size="sm"
+ variant="default"
+ onClick={onShowGetStarted}
+ disabled={!onShowGetStarted}
+ >
+ <ListChecks className="h-3.5 w-3.5" />
+ Show
+ </Button>
+ </Row>
</Section>
</div>
</div>
diff --git a/client/src/hooks/__tests__/useGetStarted.test.ts b/client/src/hooks/__tests__/useGetStarted.test.ts
new file mode 100644
index 00000000..1c71bfdf
--- /dev/null
+++ b/client/src/hooks/__tests__/useGetStarted.test.ts
@@ -0,0 +1,285 @@
+/**
+ * Tests for useGetStarted — the Get Started checklist state hook.
+ *
+ * Locks the contract:
+ * - visible = settings query success && onboarding_completed && !dismissed
+ * - completion per item = persisted latch field || live signal
+ * - newly-true live signals persist a one-way latch via saveSettings.mutate,
+ * guarded by the settings flag (no re-write when already latched)
+ * - build-workflow excludes the three seeded example workflow names
+ * - try-theme compares against the theme captured on first render
+ * - dismiss()/restore() write getting_started_dismissed true/false
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+
+// --- controllable mock state -------------------------------------------------
+// Factories below return closures that read these at call time (safe under
+// vi.mock hoisting — the values are only dereferenced during render).
+
+const settingsState: {
+ data: Record<string, any> | undefined;
+ isSuccess: boolean;
+} = { data: undefined, isSuccess: false };
+
+const saveMutate = vi.fn();
+
+vi.mock('../useUserSettingsQuery', () => ({
+ useUserSettingsQuery: () => ({
+ data: settingsState.data,
+ isSuccess: settingsState.isSuccess,
+ }),
+ useSaveUserSettingsMutation: () => ({ mutate: saveMutate }),
+}));
+
+const catalogueState = { storedCount: 0 };
+vi.mock('../useCatalogueQuery', () => ({
+ useStoredProviderCount: () => catalogueState.storedCount,
+}));
+
+const wsState = {
+ chatMessages: [] as Array<{ role: 'user' | 'assistant'; message: string; timestamp: string }>,
+};
+// Full-module replace — importActual+spread is broken under React 19 (see
+// CredentialsModal.test.tsx for the canonical note).
+vi.mock('../../contexts/WebSocketContext', () => ({
+ useWebSocket: () => ({ chatMessages: wsState.chatMessages }),
+}));
+
+const themeState = { theme: 'dark' };
+vi.mock('../../contexts/ThemeContext', () => ({
+ useTheme: () => ({ theme: themeState.theme }),
+}));
+
+import { useGetStarted } from '../useGetStarted';
+import { useAppStore, type WorkflowData } from '../../store/useAppStore';
+import type { GetStartedItemId } from '../../components/onboarding/getStartedItems';
+
+// --- helpers -----------------------------------------------------------------
+
+const makeWorkflow = (name: string, nodeCount = 1): WorkflowData => ({
+ id: 'wf-1',
+ name,
+ slug: '',
+ nodes: Array.from({ length: nodeCount }, (_, i) => ({
+ id: `n${i}`,
+ type: 'aiAgent',
+ position: { x: 0, y: 0 },
+ data: {},
+ })) as WorkflowData['nodes'],
+ edges: [],
+ createdAt: new Date(),
+ lastModified: new Date(),
+});
+
+const completedSettings = (extra: Record<string, any> = {}) => ({
+ onboarding_completed: true,
+ ...extra,
+});
+
+function itemCompleted(
+ result: { current: ReturnType<typeof useGetStarted> },
+ id: GetStartedItemId,
+): boolean {
+ const item = result.current.items.find((i) => i.id === id);
+ expect(item).toBeDefined();
+ return item!.completed;
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ settingsState.data = completedSettings();
+ settingsState.isSuccess = true;
+ catalogueState.storedCount = 0;
+ wsState.chatMessages = [];
+ themeState.theme = 'dark';
+ useAppStore.setState({ currentWorkflow: null, hasUnsavedChanges: false });
+});
+
+// --- visibility --------------------------------------------------------------
+
+describe('useGetStarted visibility', () => {
+ it('is hidden when getting_started_dismissed is set', () => {
+ settingsState.data = completedSettings({ getting_started_dismissed: true });
+ const { result } = renderHook(() => useGetStarted());
+ expect(result.current.visible).toBe(false);
+ });
+
+ it('is hidden when onboarding is not completed', () => {
+ settingsState.data = { onboarding_completed: false };
+ const { result } = renderHook(() => useGetStarted());
+ expect(result.current.visible).toBe(false);
+ });
+
+ it('is hidden while the settings query is pending, and persists no latches', () => {
+ settingsState.data = undefined;
+ settingsState.isSuccess = false;
+ catalogueState.storedCount = 3; // live signal true, but query not settled
+ const { result } = renderHook(() => useGetStarted());
+ expect(result.current.visible).toBe(false);
+ expect(saveMutate).not.toHaveBeenCalled();
+ });
+
+ it('is visible for completed-onboarding, non-dismissed settings', () => {
+ const { result } = renderHook(() => useGetStarted());
+ expect(result.current.visible).toBe(true);
+ });
+});
+
+// --- baseline ----------------------------------------------------------------
+
+describe('useGetStarted baseline', () => {
+ it('endows fresh settings with only the setup item completed (1 of 5)', () => {
+ const { result } = renderHook(() => useGetStarted());
+ expect(result.current.totalCount).toBe(5);
+ expect(result.current.completedCount).toBe(1);
+ expect(itemCompleted(result, 'setup')).toBe(true);
+ expect(itemCompleted(result, 'add-key')).toBe(false);
+ expect(itemCompleted(result, 'chat-example')).toBe(false);
+ expect(itemCompleted(result, 'build-workflow')).toBe(false);
+ expect(itemCompleted(result, 'try-theme')).toBe(false);
+ expect(saveMutate).not.toHaveBeenCalled();
+ });
+});
+
+// --- add-key -----------------------------------------------------------------
+
+describe('useGetStarted add-key', () => {
+ it('completes when a provider credential is stored and persists the latch', () => {
+ catalogueState.storedCount = 2;
+ const { result } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'add-key')).toBe(true);
+ expect(result.current.completedCount).toBe(2); // setup + add-key
+ expect(saveMutate).toHaveBeenCalledWith({ getting_started_added_key: true });
+ expect(saveMutate).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not re-persist when the latch flag is already set', () => {
+ settingsState.data = completedSettings({ getting_started_added_key: true });
+ catalogueState.storedCount = 2;
+ const { result } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'add-key')).toBe(true);
+ expect(saveMutate).not.toHaveBeenCalled();
+ });
+});
+
+// --- chat-example ------------------------------------------------------------
+
+describe('useGetStarted chat-example', () => {
+ it('stays incomplete with only user messages', () => {
+ wsState.chatMessages = [{ role: 'user', message: 'hi', timestamp: 't1' }];
+ const { result } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'chat-example')).toBe(false);
+ expect(saveMutate).not.toHaveBeenCalled();
+ });
+
+ it('completes on an assistant message and persists the latch', () => {
+ wsState.chatMessages = [
+ { role: 'user', message: 'hi', timestamp: 't1' },
+ { role: 'assistant', message: 'hello!', timestamp: 't2' },
+ ];
+ const { result } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'chat-example')).toBe(true);
+ expect(saveMutate).toHaveBeenCalledWith({ getting_started_ran_example: true });
+ });
+});
+
+// --- build-workflow ----------------------------------------------------------
+
+describe('useGetStarted build-workflow', () => {
+ it('completes for a saved, non-example workflow with nodes', () => {
+ useAppStore.setState({
+ currentWorkflow: makeWorkflow('My Automation', 2),
+ hasUnsavedChanges: false,
+ });
+ const { result } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'build-workflow')).toBe(true);
+ expect(saveMutate).toHaveBeenCalledWith({ getting_started_built_workflow: true });
+ });
+
+ it('does NOT complete via live signal for a seeded example workflow name', () => {
+ useAppStore.setState({
+ currentWorkflow: makeWorkflow('AI Assistant', 3),
+ hasUnsavedChanges: false,
+ });
+ const { result } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'build-workflow')).toBe(false);
+ expect(saveMutate).not.toHaveBeenCalledWith({ getting_started_built_workflow: true });
+ });
+
+ it('does not complete while the workflow has unsaved changes', () => {
+ useAppStore.setState({
+ currentWorkflow: makeWorkflow('My Automation', 2),
+ hasUnsavedChanges: true,
+ });
+ const { result } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'build-workflow')).toBe(false);
+ });
+
+ it('does not complete for an empty (node-less) workflow', () => {
+ useAppStore.setState({
+ currentWorkflow: makeWorkflow('My Automation', 0),
+ hasUnsavedChanges: false,
+ });
+ const { result } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'build-workflow')).toBe(false);
+ });
+});
+
+// --- try-theme ---------------------------------------------------------------
+
+describe('useGetStarted try-theme', () => {
+ it('stays incomplete while the theme matches the initial theme', () => {
+ const { result, rerender } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'try-theme')).toBe(false);
+ rerender();
+ expect(itemCompleted(result, 'try-theme')).toBe(false);
+ expect(saveMutate).not.toHaveBeenCalled();
+ });
+
+ it('completes when the theme changes from the initial one and persists the latch', () => {
+ const { result, rerender } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'try-theme')).toBe(false);
+
+ themeState.theme = 'cyber';
+ rerender();
+
+ expect(itemCompleted(result, 'try-theme')).toBe(true);
+ expect(saveMutate).toHaveBeenCalledWith({ getting_started_tried_theme: true });
+ });
+});
+
+// --- one-way latch -----------------------------------------------------------
+
+describe('useGetStarted one-way latch', () => {
+ it('keeps an item completed via the latch even when the live signal is false', () => {
+ settingsState.data = completedSettings({
+ getting_started_tried_theme: true,
+ getting_started_added_key: true,
+ });
+ // All live signals false: no stored providers, no chat, same theme.
+ const { result } = renderHook(() => useGetStarted());
+ expect(itemCompleted(result, 'try-theme')).toBe(true);
+ expect(itemCompleted(result, 'add-key')).toBe(true);
+ expect(result.current.completedCount).toBe(3); // setup + the two latches
+ expect(saveMutate).not.toHaveBeenCalled();
+ });
+});
+
+// --- dismiss / restore -------------------------------------------------------
+
+describe('useGetStarted dismiss/restore', () => {
+ it('dismiss() persists getting_started_dismissed: true', () => {
+ const { result } = renderHook(() => useGetStarted());
+ act(() => result.current.dismiss());
+ expect(saveMutate).toHaveBeenCalledWith({ getting_started_dismissed: true });
+ });
+
+ it('restore() persists getting_started_dismissed: false', () => {
+ settingsState.data = completedSettings({ getting_started_dismissed: true });
+ const { result } = renderHook(() => useGetStarted());
+ act(() => result.current.restore());
+ expect(saveMutate).toHaveBeenCalledWith({ getting_started_dismissed: false });
+ });
+});
diff --git a/client/src/hooks/__tests__/useOnboarding.steps.test.ts b/client/src/hooks/__tests__/useOnboarding.steps.test.ts
new file mode 100644
index 00000000..9d3910f5
--- /dev/null
+++ b/client/src/hooks/__tests__/useOnboarding.steps.test.ts
@@ -0,0 +1,93 @@
+/**
+ * useOnboarding step-hydration tests.
+ *
+ * Locks in the persisted-step validation contract: on hydration the hook
+ * keeps `onboarding_step` only when `0 <= step < totalSteps`; anything
+ * out of range (the old 5-step wizard persisted step 4, the new wizard
+ * has 4 steps) resets to 0 so a replay never starts past the end.
+ * Also locks the visibility gate on `onboarding_completed`.
+ *
+ * useUserSettingsQuery / useSaveUserSettingsMutation are module-mocked
+ * (full replace) so no WebSocket / TanStack plumbing is exercised.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { wrapperWithProviders } from '../../test/providers';
+
+// --- Mocks (declared BEFORE importing the hook -- vi.mock is hoisted) -------
+
+interface SettingsQueryState {
+ isSuccess: boolean;
+ isError: boolean;
+ data: Record<string, unknown> | undefined;
+ error: Error | null;
+}
+
+let settingsQueryState: SettingsQueryState;
+const mutateMock = vi.fn();
+
+vi.mock('../useUserSettingsQuery', () => ({
+ useUserSettingsQuery: () => settingsQueryState,
+ useSaveUserSettingsMutation: () => ({ mutate: mutateMock }),
+}));
+
+import { useOnboarding } from '../useOnboarding';
+
+const TOTAL_STEPS = 4;
+
+const renderOnboarding = () =>
+ renderHook(() => useOnboarding(undefined, TOTAL_STEPS), {
+ wrapper: wrapperWithProviders(),
+ });
+
+beforeEach(() => {
+ mutateMock.mockClear();
+ settingsQueryState = {
+ isSuccess: true,
+ isError: false,
+ data: {},
+ error: null,
+ };
+});
+
+// --- Tests ------------------------------------------------------------------
+
+describe('useOnboarding persisted-step hydration', () => {
+ it('resets an out-of-range persisted step (old 5-step wizard) to 0 and stays visible', () => {
+ settingsQueryState.data = { onboarding_step: 4, onboarding_completed: false };
+ const { result } = renderOnboarding();
+
+ expect(result.current.currentStep).toBe(0);
+ expect(result.current.isVisible).toBe(true);
+ expect(result.current.isCompleted).toBe(false);
+ expect(result.current.hasChecked).toBe(true);
+ expect(result.current.isLoading).toBe(false);
+ });
+
+ it('keeps an in-range persisted step', () => {
+ settingsQueryState.data = { onboarding_step: 2, onboarding_completed: false };
+ const { result } = renderOnboarding();
+
+ expect(result.current.currentStep).toBe(2);
+ expect(result.current.isVisible).toBe(true);
+ });
+
+ it('resets a negative persisted step to 0', () => {
+ settingsQueryState.data = { onboarding_step: -1, onboarding_completed: false };
+ const { result } = renderOnboarding();
+
+ expect(result.current.currentStep).toBe(0);
+ expect(result.current.isVisible).toBe(true);
+ });
+
+ it('stays hidden when onboarding is already completed', () => {
+ settingsQueryState.data = { onboarding_step: 1, onboarding_completed: true };
+ const { result } = renderOnboarding();
+
+ expect(result.current.isVisible).toBe(false);
+ expect(result.current.isCompleted).toBe(true);
+ expect(result.current.hasChecked).toBe(true);
+ expect(result.current.isLoading).toBe(false);
+ });
+});
diff --git a/client/src/hooks/useGetStarted.ts b/client/src/hooks/useGetStarted.ts
new file mode 100644
index 00000000..a956b6d5
--- /dev/null
+++ b/client/src/hooks/useGetStarted.ts
@@ -0,0 +1,109 @@
+/**
+ * Get Started checklist state.
+ *
+ * Each item's completion is `persisted latch || live signal`. Latches are
+ * one-way booleans in `user_settings` (written once via the shared settings
+ * mutation, guarded by the flag itself) so completion survives the live
+ * signal disappearing later (key deleted, chat cleared, theme reverted).
+ */
+
+import { useEffect, useRef } from 'react';
+import { useUserSettingsQuery, useSaveUserSettingsMutation } from './useUserSettingsQuery';
+import { useStoredProviderCount } from './useCatalogueQuery';
+import { useWebSocket } from '../contexts/WebSocketContext';
+import { useTheme } from '../contexts/ThemeContext';
+import { useAppStore } from '../store/useAppStore';
+import {
+ GET_STARTED_ITEMS,
+ EXAMPLE_WORKFLOW_NAMES,
+ type GetStartedItemId,
+} from '../components/onboarding/getStartedItems';
+
+const LATCH_FIELDS: Partial<Record<GetStartedItemId, string>> = {
+ 'add-key': 'getting_started_added_key',
+ 'chat-example': 'getting_started_ran_example',
+ 'build-workflow': 'getting_started_built_workflow',
+ 'try-theme': 'getting_started_tried_theme',
+};
+
+export interface GetStartedItemState {
+ id: GetStartedItemId;
+ completed: boolean;
+}
+
+export interface GetStartedState {
+ visible: boolean;
+ items: GetStartedItemState[];
+ completedCount: number;
+ totalCount: number;
+ dismiss: () => void;
+ restore: () => void;
+}
+
+export function useGetStarted(): GetStartedState {
+ const settingsQuery = useUserSettingsQuery();
+ const saveSettings = useSaveUserSettingsMutation();
+ const settings = settingsQuery.data;
+
+ // Live signals.
+ const storedProviderCount = useStoredProviderCount();
+ const { chatMessages } = useWebSocket();
+ const { theme } = useTheme();
+ const initialThemeRef = useRef(theme);
+ const currentWorkflowName = useAppStore((s) => s.currentWorkflow?.name);
+ const currentWorkflowNodeCount = useAppStore((s) => s.currentWorkflow?.nodes.length ?? 0);
+ const hasUnsavedChanges = useAppStore((s) => s.hasUnsavedChanges);
+
+ const liveSignals: Partial<Record<GetStartedItemId, boolean>> = {
+ 'add-key': storedProviderCount > 0,
+ 'chat-example': chatMessages.some((m) => m.role === 'assistant'),
+ 'build-workflow':
+ !hasUnsavedChanges &&
+ currentWorkflowNodeCount > 0 &&
+ currentWorkflowName !== undefined &&
+ !EXAMPLE_WORKFLOW_NAMES.some(
+ (example) => example.toLowerCase() === currentWorkflowName.toLowerCase(),
+ ),
+ 'try-theme': theme !== initialThemeRef.current,
+ };
+
+ const completedById = Object.fromEntries(
+ GET_STARTED_ITEMS.map((item) => {
+ const latchField = LATCH_FIELDS[item.id];
+ const latched = latchField ? Boolean(settings?.[latchField]) : true;
+ return [item.id, latched || Boolean(liveSignals[item.id])];
+ }),
+ ) as Record<GetStartedItemId, boolean>;
+
+ // Persist newly-true live signals as one-way latches.
+ const { mutate: saveMutate } = saveSettings;
+ useEffect(() => {
+ if (!settingsQuery.isSuccess) return;
+ for (const [itemId, field] of Object.entries(LATCH_FIELDS)) {
+ if (liveSignals[itemId as GetStartedItemId] && !settings?.[field]) {
+ saveMutate({ [field]: true });
+ }
+ }
+ // The settings flag is the dedup guard once the mutation settles
+ // (onSuccess patches the query cache). Renders before settlement may
+ // re-send the same boolean patch — harmless, the write is idempotent.
+ });
+
+ const items = GET_STARTED_ITEMS.map((item) => ({
+ id: item.id,
+ completed: completedById[item.id],
+ }));
+ const completedCount = items.filter((item) => item.completed).length;
+
+ return {
+ visible:
+ settingsQuery.isSuccess &&
+ Boolean(settings?.onboarding_completed) &&
+ !settings?.getting_started_dismissed,
+ items,
+ completedCount,
+ totalCount: items.length,
+ dismiss: () => saveMutate({ getting_started_dismissed: true }),
+ restore: () => saveMutate({ getting_started_dismissed: false }),
+ };
+}
diff --git a/client/src/hooks/useOnboarding.ts b/client/src/hooks/useOnboarding.ts
index 1bb9111f..18bf5f1a 100644
--- a/client/src/hooks/useOnboarding.ts
+++ b/client/src/hooks/useOnboarding.ts
@@ -42,7 +42,8 @@ export const useOnboarding = (
if (!settingsQuery.isSuccess) return;
const settings = settingsQuery.data;
const completed = settings?.onboarding_completed ?? false;
- const step = settings?.onboarding_step ?? 0;
+ const storedStep = settings?.onboarding_step ?? 0;
+ const step = storedStep >= 0 && storedStep < totalSteps ? storedStep : 0;
setState((prev) => ({
...prev,
// Only flip visibility on first hydration; later renders shouldn't
@@ -53,7 +54,7 @@ export const useOnboarding = (
isLoading: false,
hasChecked: true,
}));
- }, [settingsQuery.isSuccess, settingsQuery.data]);
+ }, [settingsQuery.isSuccess, settingsQuery.data, totalSteps]);
// Surface query errors as a non-blocking "checked" state so the app
// continues even if the WS round-trip failed.
diff --git a/client/src/store/__tests__/openExampleAndChat.test.ts b/client/src/store/__tests__/openExampleAndChat.test.ts
new file mode 100644
index 00000000..b491816d
--- /dev/null
+++ b/client/src/store/__tests__/openExampleAndChat.test.ts
@@ -0,0 +1,180 @@
+/**
+ * Tests for useAppStore.openExampleAndChat + requestChatFocus.
+ *
+ * Locks the onboarding handoff contract:
+ * - case-insensitive name lookup against workflowApi.getAllWorkflows()
+ * - hit: loads the workflow (workflowApi.getWorkflow), reveals the console
+ * panel, bumps chatFocusRequest, returns the loaded workflow
+ * - miss: toast.info, returns null, state untouched
+ * - load failure (getWorkflow -> null): toast.error, returns null,
+ * state untouched
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// --- mocks (hoisted; closures dereference the spies at call time) -----------
+
+const getAllWorkflowsMock = vi.fn();
+const getWorkflowMock = vi.fn();
+const saveWorkflowMock = vi.fn();
+const deleteWorkflowMock = vi.fn();
+
+vi.mock('../../services/workflowApi', () => ({
+ workflowApi: {
+ getAllWorkflows: (...args: unknown[]) => getAllWorkflowsMock(...args),
+ getWorkflow: (...args: unknown[]) => getWorkflowMock(...args),
+ saveWorkflow: (...args: unknown[]) => saveWorkflowMock(...args),
+ deleteWorkflow: (...args: unknown[]) => deleteWorkflowMock(...args),
+ },
+}));
+
+const toastInfoMock = vi.fn();
+const toastErrorMock = vi.fn();
+vi.mock('sonner', () => ({
+ toast: {
+ info: (...args: unknown[]) => toastInfoMock(...args),
+ error: (...args: unknown[]) => toastErrorMock(...args),
+ success: vi.fn(),
+ message: vi.fn(),
+ warning: vi.fn(),
+ },
+}));
+
+import { useAppStore } from '../useAppStore';
+
+// --- fixtures ----------------------------------------------------------------
+
+const summary = (id: string, name: string) => ({
+ id,
+ name,
+ slug: `${name.replace(/\s+/g, '_')}_1`,
+ nodeCount: 1,
+ createdAt: '2026-01-01T00:00:00Z',
+ lastModified: '2026-01-02T00:00:00Z',
+});
+
+// Shape of workflowApi.getWorkflow's resolved value (services/workflowApi.ts
+// WorkflowData): { id, name, slug, data: { nodes, edges }, createdAt,
+// lastModified }.
+const workflowRecord = (id: string, name: string) => ({
+ id,
+ name,
+ slug: `${name.replace(/\s+/g, '_')}_1`,
+ data: { nodes: [], edges: [] },
+ createdAt: '2026-01-01T00:00:00Z',
+ lastModified: '2026-01-02T00:00:00Z',
+});
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ useAppStore.setState({
+ currentWorkflow: null,
+ hasUnsavedChanges: false,
+ selectedNode: null,
+ consolePanelVisible: false,
+ chatFocusRequest: 0,
+ });
+});
+
+// ---------------------------------------------------------------------------
+
+describe('useAppStore.requestChatFocus', () => {
+ it('increments the monotonic chatFocusRequest counter', () => {
+ expect(useAppStore.getState().chatFocusRequest).toBe(0);
+ useAppStore.getState().requestChatFocus();
+ expect(useAppStore.getState().chatFocusRequest).toBe(1);
+ useAppStore.getState().requestChatFocus();
+ expect(useAppStore.getState().chatFocusRequest).toBe(2);
+ });
+});
+
+describe('useAppStore.openExampleAndChat', () => {
+ it('finds the workflow case-insensitively, loads it, opens the console, and requests chat focus', async () => {
+ getAllWorkflowsMock.mockResolvedValue([
+ summary('wf-other', 'Other Flow'),
+ summary('wf-1', 'AI Assistant'),
+ ]);
+ getWorkflowMock.mockResolvedValue(workflowRecord('wf-1', 'AI Assistant'));
+
+ const result = await useAppStore.getState().openExampleAndChat('ai assistant');
+
+ // Load path went through workflowApi.getWorkflow with the matched id.
+ expect(getWorkflowMock).toHaveBeenCalledTimes(1);
+ expect(getWorkflowMock).toHaveBeenCalledWith('wf-1');
+
+ // Returns the loaded workflow.
+ expect(result).not.toBeNull();
+ expect(result!.id).toBe('wf-1');
+ expect(result!.name).toBe('AI Assistant');
+
+ const state = useAppStore.getState();
+ expect(state.currentWorkflow?.id).toBe('wf-1');
+ expect(state.currentWorkflow?.name).toBe('AI Assistant');
+ expect(state.hasUnsavedChanges).toBe(false);
+ expect(state.consolePanelVisible).toBe(true);
+ expect(state.chatFocusRequest).toBe(1);
+
+ expect(toastInfoMock).not.toHaveBeenCalled();
+ expect(toastErrorMock).not.toHaveBeenCalled();
+ });
+
+ it('toasts info and leaves state untouched when no workflow matches the name', async () => {
+ getAllWorkflowsMock.mockResolvedValue([summary('wf-other', 'Other Flow')]);
+
+ const result = await useAppStore.getState().openExampleAndChat('AI Assistant');
+
+ expect(result).toBeNull();
+ expect(toastInfoMock).toHaveBeenCalledTimes(1);
+ expect(getWorkflowMock).not.toHaveBeenCalled();
+
+ const state = useAppStore.getState();
+ expect(state.currentWorkflow).toBeNull();
+ expect(state.consolePanelVisible).toBe(false);
+ expect(state.chatFocusRequest).toBe(0);
+ expect(toastErrorMock).not.toHaveBeenCalled();
+ });
+
+ it('toasts error and returns null when the workflow fails to load', async () => {
+ getAllWorkflowsMock.mockResolvedValue([summary('wf-1', 'AI Assistant')]);
+ getWorkflowMock.mockResolvedValue(null); // loadWorkflow leaves the store untouched
+
+ const result = await useAppStore.getState().openExampleAndChat('AI Assistant');
+
+ expect(result).toBeNull();
+ expect(getWorkflowMock).toHaveBeenCalledWith('wf-1');
+ expect(toastErrorMock).toHaveBeenCalledTimes(1);
+ expect(toastInfoMock).not.toHaveBeenCalled();
+
+ const state = useAppStore.getState();
+ expect(state.currentWorkflow).toBeNull();
+ expect(state.consolePanelVisible).toBe(false);
+ expect(state.chatFocusRequest).toBe(0);
+ });
+
+ it('does not treat a different open workflow as the load target (id verification)', async () => {
+ // A previously open workflow stays current when the load fails; the id
+ // check must compare against the TARGET id, not merely non-null.
+ useAppStore.setState({
+ currentWorkflow: {
+ id: 'wf-prev',
+ name: 'Previous',
+ slug: '',
+ nodes: [],
+ edges: [],
+ createdAt: new Date(),
+ lastModified: new Date(),
+ },
+ });
+ getAllWorkflowsMock.mockResolvedValue([summary('wf-1', 'AI Assistant')]);
+ getWorkflowMock.mockResolvedValue(null);
+
+ const result = await useAppStore.getState().openExampleAndChat('AI Assistant');
+
+ expect(result).toBeNull();
+ expect(toastErrorMock).toHaveBeenCalledTimes(1);
+ const state = useAppStore.getState();
+ expect(state.currentWorkflow?.id).toBe('wf-prev');
+ expect(state.consolePanelVisible).toBe(false);
+ expect(state.chatFocusRequest).toBe(0);
+ });
+});
diff --git a/client/src/store/useAppStore.ts b/client/src/store/useAppStore.ts
index a91d6a4a..2bc7c511 100644
--- a/client/src/store/useAppStore.ts
+++ b/client/src/store/useAppStore.ts
@@ -1,5 +1,6 @@
import { create } from 'zustand';
import { Node, Edge } from 'reactflow';
+import { toast } from 'sonner';
import { generateWorkflowId } from '../utils/workflow';
import { theme } from '../styles/theme';
import {
@@ -64,6 +65,9 @@ interface AppStore {
* user's first interaction (no separate audio permission needed). */
soundEnabled: boolean;
renamingNodeId: string | null;
+ /** Monotonic counter — ConsolePanel focuses the chat input whenever it
+ * increments. Not persisted. */
+ chatFocusRequest: number;
// Workflow actions
setCurrentWorkflow: (workflow: WorkflowData) => void;
@@ -88,6 +92,11 @@ interface AppStore {
setComponentPaletteVisible: (visible: boolean) => void;
setConsolePanelVisible: (visible: boolean) => void;
toggleConsolePanelVisible: () => void;
+ requestChatFocus: () => void;
+ /** Open a workflow by display name, reveal the console panel, and focus
+ * the chat input. Used by the onboarding finish handoff and the Get
+ * Started checklist. Returns the loaded workflow, or null if not found. */
+ openExampleAndChat: (name: string) => Promise<WorkflowData | null>;
applyUIDefaults: (defaults: { sidebarDefaultOpen?: boolean; componentPaletteDefaultOpen?: boolean; consolePanelDefaultOpen?: boolean }) => void;
// Per-workflow UI state actions (n8n pattern)
@@ -195,6 +204,7 @@ export const useAppStore = create<AppStore>((set, get) => ({
BRAND_STORAGE_KEYS.sound.legacy,
), // On by default; user can disable in Settings -> Audio. Browsers gesture-gate WebAudio (no separate permission), so the AC unlocks on first interaction via Sounds.unlock().
renamingNodeId: null,
+ chatFocusRequest: 0,
// Workflow management
setCurrentWorkflow: (workflow) => {
@@ -404,6 +414,30 @@ export const useAppStore = create<AppStore>((set, get) => ({
});
},
+ requestChatFocus: () => {
+ set((state) => ({ chatFocusRequest: state.chatFocusRequest + 1 }));
+ },
+
+ openExampleAndChat: async (name) => {
+ const workflows = await workflowApi.getAllWorkflows();
+ const target = workflows.find((w) => w.name.toLowerCase() === name.toLowerCase());
+ if (!target) {
+ toast.info(`The "${name}" example was not found. Open any workflow from the sidebar to chat with it.`);
+ return null;
+ }
+
+ await get().loadWorkflow(target.id);
+ const loaded = get().currentWorkflow;
+ if (loaded?.id !== target.id) {
+ toast.error(`Could not open "${name}". Try opening it from the sidebar.`);
+ return null;
+ }
+
+ get().setConsolePanelVisible(true);
+ get().requestChatFocus();
+ return loaded;
+ },
+
applyUIDefaults: (defaults) => {
const updates: Partial<{ sidebarVisible: boolean; componentPaletteVisible: boolean; consolePanelVisible: boolean }> = {};
diff --git a/server/core/database.py b/server/core/database.py
index 95e213ef..99a6e23a 100644
--- a/server/core/database.py
+++ b/server/core/database.py
@@ -173,6 +173,22 @@ class Database:
if "max_delegation_depth" not in columns:
await conn.execute(text("ALTER TABLE user_settings ADD COLUMN max_delegation_depth INTEGER DEFAULT 2"))
+ if "getting_started_dismissed" not in columns:
+ await conn.execute(text("ALTER TABLE user_settings ADD COLUMN getting_started_dismissed BOOLEAN DEFAULT 0"))
+ # Existing users who already finished/skipped onboarding never see the checklist
+ await conn.execute(text("UPDATE user_settings SET getting_started_dismissed = 1 WHERE onboarding_completed = 1"))
+ logger.info("Added getting_started_dismissed column to user_settings")
+
+ for col in [
+ "getting_started_added_key",
+ "getting_started_ran_example",
+ "getting_started_built_workflow",
+ "getting_started_tried_theme",
+ ]:
+ if col not in columns:
+ await conn.execute(text(f"ALTER TABLE user_settings ADD COLUMN {col} BOOLEAN DEFAULT 0"))
+ logger.info(f"Added {col} column to user_settings")
+
# Migrate token_usage_metrics table - add cost columns
result = await conn.execute(text("PRAGMA table_info(token_usage_metrics)"))
columns = {row[1] for row in result.fetchall()}
@@ -1816,6 +1832,11 @@ class Database:
"examples_loaded": settings.examples_loaded,
"onboarding_completed": settings.onboarding_completed,
"onboarding_step": settings.onboarding_step,
+ "getting_started_dismissed": settings.getting_started_dismissed,
+ "getting_started_added_key": settings.getting_started_added_key,
+ "getting_started_ran_example": settings.getting_started_ran_example,
+ "getting_started_built_workflow": settings.getting_started_built_workflow,
+ "getting_started_tried_theme": settings.getting_started_tried_theme,
"default_llm_provider": settings.default_llm_provider,
"default_llm_model": settings.default_llm_model,
"auto_add_skill_for_tools": settings.auto_add_skill_for_tools,
diff --git a/server/models/database.py b/server/models/database.py
index be99fc2e..8a4b91b0 100644
--- a/server/models/database.py
+++ b/server/models/database.py
@@ -280,6 +280,11 @@ class UserSettings(SQLModel, table=True):
examples_loaded: bool = Field(default=False) # Track if example workflows were imported
onboarding_completed: bool = Field(default=False) # Track if user completed or skipped onboarding
onboarding_step: int = Field(default=0) # Last completed onboarding step (for resuming)
+ getting_started_dismissed: bool = Field(default=False) # User closed the Get Started checklist card
+ getting_started_added_key: bool = Field(default=False) # Latched: a credential was stored at least once
+ getting_started_ran_example: bool = Field(default=False) # Latched: chatted while a workflow was deployed
+ getting_started_built_workflow: bool = Field(default=False) # Latched: saved a self-built workflow with nodes
+ getting_started_tried_theme: bool = Field(default=False) # Latched: switched visual theme at least once
default_llm_provider: Optional[str] = Field(default=None, max_length=50) # Global default AI provider
default_llm_model: Optional[str] = Field(default=None, max_length=200) # Global default AI model
auto_add_skill_for_tools: bool = Field(
diff --git a/server/tests/services/test_getting_started_settings.py b/server/tests/services/test_getting_started_settings.py
new file mode 100644
index 00000000..29beef1a
--- /dev/null
+++ b/server/tests/services/test_getting_started_settings.py
@@ -0,0 +1,94 @@
+"""Real-SQLite tests for the Get Started checklist settings columns.
+
+Uses the file-loaded real Database (same fixture pattern as
+test_subagent_concurrency.py) so schema creation, the ALTER TABLE
+migration, and the save/get round-trip run against actual SQLite.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+import uuid
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from sqlalchemy import text
+
+GETTING_STARTED_COLUMNS = [
+ "getting_started_dismissed",
+ "getting_started_added_key",
+ "getting_started_ran_example",
+ "getting_started_built_workflow",
+ "getting_started_tried_theme",
+]
+
+
+async def settings_database():
+ module_name = "tests._real_settings_database"
+ spec = importlib.util.spec_from_file_location(
+ module_name, Path(__file__).resolve().parents[2] / "core" / "database.py"
+ )
+ assert spec and spec.loader
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[module_name] = module
+ spec.loader.exec_module(module)
+ db_path = Path.cwd() / f".getting-started-{uuid.uuid4().hex}.db"
+ database = module.Database(SimpleNamespace(
+ database_url=f"sqlite+aiosqlite:///{db_path.as_posix()}",
+ database_echo=False, database_pool_size=5, database_max_overflow=5,
+ ))
+ await database.startup()
+ try:
+ yield database
+ finally:
+ await database.shutdown()
+ sys.modules.pop(module_name, None)
+ for candidate in (db_path, Path(f"{db_path}-wal"), Path(f"{db_path}-shm")):
+ candidate.unlink(missing_ok=True)
+
+
+async def test_fresh_database_has_getting_started_columns(settings_database):
+ async with settings_database.engine.begin() as conn:
+ result = await conn.execute(text("PRAGMA table_info(user_settings)"))
+ columns = {row[1] for row in result.fetchall()}
+ for column in GETTING_STARTED_COLUMNS:
+ assert column in columns
+
+
+async def test_save_get_round_trip_returns_getting_started_keys(settings_database):
+ assert await settings_database.save_user_settings(
+ {"getting_started_ran_example": True}, user_id="default"
+ )
+ settings = await settings_database.get_user_settings("default")
+ assert settings is not None
+ assert settings["getting_started_ran_example"] is True
+ assert settings["getting_started_dismissed"] is False
+
+
+async def test_migration_backfills_dismissed_for_completed_onboarding(settings_database):
+ # Simulate a pre-feature database: rows exist, new columns absent.
+ assert await settings_database.save_user_settings(
+ {"onboarding_completed": True}, user_id="veteran"
+ )
+ assert await settings_database.save_user_settings(
+ {"onboarding_completed": False}, user_id="newbie"
+ )
+ async with settings_database.engine.begin() as conn:
+ for column in GETTING_STARTED_COLUMNS:
+ await conn.execute(text(f"ALTER TABLE user_settings DROP COLUMN {column}"))
+
+ await settings_database._migrate_user_settings()
+
+ async with settings_database.engine.begin() as conn:
+ rows = await conn.execute(text(
+ "SELECT user_id, getting_started_dismissed FROM user_settings"
+ ))
+ dismissed_by_user = dict(rows.fetchall())
+ assert dismissed_by_user["veteran"] == 1
+ assert dismissed_by_user["newbie"] == 0
diff --git a/server/tests/test_user_settings_contract.py b/server/tests/test_user_settings_contract.py
new file mode 100644
index 00000000..d95d352f
--- /dev/null
+++ b/server/tests/test_user_settings_contract.py
@@ -0,0 +1,77 @@
+"""Contract tests for the UserSettings persistence surface.
+
+``save_user_settings`` is generic over ``UserSettings.model_fields``, but
+``get_user_settings`` hand-builds its return dict — a new model field that
+is not added to the getter silently never reaches the frontend. These
+tests lock that symmetry plus the migration branches, using the same
+``inspect.getsource`` introspection idiom as test_credential_broadcasts.py
+(the conftest stubs ``core.database``, so the real module is loaded from
+file like tests/services/test_subagent_concurrency.py does).
+"""
+
+import importlib.util
+import inspect
+import sys
+from pathlib import Path
+
+import pytest
+
+from models.database import UserSettings
+
+GETTING_STARTED_FIELDS = [
+ "getting_started_dismissed",
+ "getting_started_added_key",
+ "getting_started_ran_example",
+ "getting_started_built_workflow",
+ "getting_started_tried_theme",
+]
+
+# Bookkeeping columns the save path never writes and the getter formats
+# specially (timestamps) or returns as-is (user_id).
+_MANAGED = {"id", "user_id", "created_at", "updated_at"}
+
+
[email protected](scope="module")
+def real_database_module():
+ """Load the real core/database.py (conftest stubs core.database)."""
+ module_name = "tests._real_database_for_contract"
+ spec = importlib.util.spec_from_file_location(
+ module_name, Path(__file__).resolve().parents[1] / "core" / "database.py"
+ )
+ assert spec and spec.loader
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[module_name] = module
+ spec.loader.exec_module(module)
+ yield module
+ sys.modules.pop(module_name, None)
+
+
+def test_model_declares_getting_started_fields():
+ for field in GETTING_STARTED_FIELDS:
+ assert field in UserSettings.model_fields, f"UserSettings missing {field}"
+ assert UserSettings.model_fields[field].default is False
+
+
+def test_get_user_settings_returns_every_model_field(real_database_module):
+ """Every non-managed model field must appear in the hand-built getter dict."""
+ source = inspect.getsource(real_database_module.Database.get_user_settings)
+ for field in set(UserSettings.model_fields) - _MANAGED:
+ assert f'"{field}"' in source, (
+ f"UserSettings.{field} is persisted by save_user_settings but "
+ f"missing from the get_user_settings return dict — the frontend "
+ f"will never see it."
+ )
+
+
+def test_migration_adds_getting_started_columns(real_database_module):
+ source = inspect.getsource(real_database_module.Database._migrate_user_settings)
+ for field in GETTING_STARTED_FIELDS:
+ assert field in source, f"_migrate_user_settings has no branch for {field}"
+
+
+def test_migration_backfills_dismissed_for_existing_users(real_database_module):
+ """Users who already finished onboarding must not see the checklist."""
+ source = inspect.getsource(real_database_module.Database._migrate_user_settings)
+ assert (
+ "SET getting_started_dismissed = 1 WHERE onboarding_completed = 1" in source
+ )