Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(onboarding): redesign wizard, add Get Started checklist and aha-first handoff
trohitg565c579af407
diff --git a/client/src/Dashboard.tsx b/client/src/Dashboard.tsxindex 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/uimport 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 = () => {<OnboardingWizardonOpenCredentials={() => 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.tsxnew file mode 100644index 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.tsxindex 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.tsxnew file mode 100644index 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.tsxindex 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,<divclassName={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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsxdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.tsxnew file mode 100644index 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'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'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.tsxdeleted file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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'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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 actionssetCurrentWorkflow: (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 managementsetCurrentWorkflow: (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.pyindex 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 columnsresult = 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.pyindex 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 importedonboarding_completed: bool = Field(default=False) # Track if user completed or skipped onboardingonboarding_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 oncedefault_llm_provider: Optional[str] = Field(default=None, max_length=50) # Global default AI providerdefault_llm_model: Optional[str] = Field(default=None, max_length=200) # Global default AI modelauto_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.pynew file mode 100644index 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"] == 0diff --git a/server/tests/test_user_settings_contract.py b/server/tests/test_user_settings_contract.pynew file mode 100644index 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+ )