feat(dashboard): Getting Started card for new users (#3398)

- Shows when totalSessions < 3 and not dismissed
- Dismissible via localStorage flag
- CTA opens CreateSessionModal
- Auto-hides after 3+ sessions exist
- 7 Vitest tests (render, dismiss, CTA, edge cases)
- Design token compatible (dark/light themes)

Closes #3398

Author: OneStepAt4time

dashboard/src/__tests__/GettingStartedCard.test.tsx

@@ -0,0 +1,59 @@
+/**
+ * __tests__/GettingStartedCard.test.tsx
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import GettingStartedCard from '../components/shared/GettingStartedCard';
+
+describe('GettingStartedCard', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it('renders when totalSessions < 3', () => {
+    render(<GettingStartedCard totalSessions={0} onCreateSession={vi.fn()} />);
+    expect(screen.getByText('Welcome to Aegis')).toBeTruthy();
+    expect(screen.getByText('Create First Session')).toBeTruthy();
+  });
+
+  it('does not render when totalSessions >= 3', () => {
+    render(<GettingStartedCard totalSessions={3} onCreateSession={vi.fn()} />);
+    expect(screen.queryByText('Welcome to Aegis')).toBeNull();
+  });
+
+  it('does not render when totalSessions > 3', () => {
+    render(<GettingStartedCard totalSessions={10} onCreateSession={vi.fn()} />);
+    expect(screen.queryByText('Welcome to Aegis')).toBeNull();
+  });
+
+  it('calls onCreateSession when CTA is clicked', () => {
+    const onCreate = vi.fn();
+    render(<GettingStartedCard totalSessions={0} onCreateSession={onCreate} />);
+    fireEvent.click(screen.getByText('Create First Session'));
+    expect(onCreate).toHaveBeenCalledOnce();
+  });
+
+  it('dismisses and sets localStorage', () => {
+    render(<GettingStartedCard totalSessions={0} onCreateSession={vi.fn()} />);
+    fireEvent.click(screen.getByLabelText('Dismiss getting started card'));
+    expect(screen.queryByText('Welcome to Aegis')).toBeNull();
+    expect(localStorage.getItem('aegis-getting-started-dismissed')).toBe('true');
+  });
+
+  it('does not render if previously dismissed', () => {
+    localStorage.setItem('aegis-getting-started-dismissed', 'true');
+    render(<GettingStartedCard totalSessions={0} onCreateSession={vi.fn()} />);
+    expect(screen.queryByText('Welcome to Aegis')).toBeNull();
+  });
+
+  it('renders for 1 and 2 sessions', () => {
+    const { rerender } = render(
+      <GettingStartedCard totalSessions={1} onCreateSession={vi.fn()} />
+    );
+    expect(screen.getByText('Welcome to Aegis')).toBeTruthy();
+
+    rerender(<GettingStartedCard totalSessions={2} onCreateSession={vi.fn()} />);
+    expect(screen.getByText('Welcome to Aegis')).toBeTruthy();
+  });
+});

dashboard/src/components/shared/GettingStartedCard.tsx

@@ -0,0 +1,80 @@
+/**
+ * components/shared/GettingStartedCard.tsx — Welcome card for new users.
+ *
+ * Shows when total sessions < 3 and user hasn't dismissed it.
+ * CTA opens the CreateSessionModal.
+ * Uses design tokens for dark/light theme compatibility.
+ */
+
+import { useState } from 'react';
+import { Rocket, X, ArrowRight } from 'lucide-react';
+
+interface GettingStartedCardProps {
+  totalSessions: number;
+  onCreateSession: () => void;
+}
+
+const DISMISS_KEY = 'aegis-getting-started-dismissed';
+
+export default function GettingStartedCard({ totalSessions, onCreateSession }: GettingStartedCardProps) {
+  const [dismissed, setDismissed] = useState(() => {
+    return localStorage.getItem(DISMISS_KEY) === 'true';
+  });
+
+  // Auto-hide: if user has 3+ sessions, never show
+  if (totalSessions >= 3 || dismissed) return null;
+
+  const handleDismiss = () => {
+    localStorage.setItem(DISMISS_KEY, 'true');
+    setDismissed(true);
+  };
+
+  const handleCreate = () => {
+    onCreateSession();
+  };
+
+  return (
+    <div
+      role="complementary"
+      aria-label="Getting started"
+      className="relative rounded-xl border border-[var(--color-accent-cyan)]/20 bg-gradient-to-br from-[var(--color-accent-cyan)]/5 to-[var(--color-surface-strong)] p-5 sm:p-6"
+    >
+      {/* Dismiss button */}
+      <button
+        type="button"
+        onClick={handleDismiss}
+        className="absolute right-3 top-3 rounded-md p-1 text-[var(--color-text-muted)] transition-colors hover:text-[var(--color-text-primary)] hover:bg-[var(--color-void-lighter)]"
+        aria-label="Dismiss getting started card"
+      >
+        <X className="h-4 w-4" />
+      </button>
+
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-center">
+        {/* Icon */}
+        <div className="flex h-12 w-12 shrink-0 items-center justify-center rounded-xl bg-[var(--color-accent-cyan)]/10 text-[var(--color-accent-cyan)]">
+          <Rocket className="h-6 w-6" />
+        </div>
+
+        {/* Content */}
+        <div className="flex-1 min-w-0">
+          <h2 className="text-base font-semibold text-[var(--color-text-primary)]">
+            Welcome to Aegis
+          </h2>
+          <p className="mt-1 text-sm text-[var(--color-text-muted)]">
+            Create your first session to start managing Claude Code with audit logs, permissions, and real-time monitoring.
+          </p>
+        </div>
+
+        {/* CTA */}
+        <button
+          type="button"
+          onClick={handleCreate}
+          className="inline-flex min-h-[44px] shrink-0 items-center justify-center gap-2 rounded-lg border border-[var(--color-accent-cyan)]/30 bg-[var(--color-accent-cyan)]/10 px-5 py-2.5 text-sm font-semibold text-[var(--color-accent-cyan)] transition-all hover:bg-[var(--color-accent-cyan)]/20 hover:border-[var(--color-accent-cyan)]/50"
+        >
+          Create First Session
+          <ArrowRight className="h-4 w-4" />
+        </button>
+      </div>
+    </div>
+  );
+}

dashboard/src/pages/OverviewPage.tsx

@@ -23,6 +23,7 @@ import { EfficiencyGauge } from '../components/analytics/EfficiencyGauge';
 import { useSessionRealtimeUpdates } from '../hooks/useSessionRealtimeUpdates';
 import { useT } from '../i18n/context';
 import { SessionHealthBanner } from '../components/shared/SessionHealthBanner';
+import GettingStartedCard from '../components/shared/GettingStartedCard';
 import { useStore } from '../store/useStore';
 import { getAnalyticsSummary } from '../api/client';
 import { formatCurrency, formatNumber } from '../utils/formatNumber';
@@ -193,6 +194,9 @@ export default function OverviewPage() {
         </div>
       </div>
 
+      {/* Getting Started — new users */}
+      <GettingStartedCard totalSessions={totalSessions} onCreateSession={() => setModalOpen(true)} />
+
       {/* Zone B: KPI Banner */}
       {!analyticsLoading && analytics && (
         <KPIBanner items={buildKPIItems(analytics)} />