feat: add onboarding wizard components and logic

- Introduced a new onboarding wizard for guiding users through the board features.
- Added shared onboarding components including OnboardingWizard, useOnboardingWizard, and related types and constants.
- Implemented onboarding logic in the BoardView, integrating sample feature generation for a quick start.
- Updated UI components to support onboarding interactions and improve user experience.
- Enhanced onboarding state management with localStorage persistence for user progress tracking.

apps/ui/src/components/shared/index.ts

@@ -5,3 +5,17 @@ export {
   type UseModelOverrideOptions,
   type UseModelOverrideResult,
 } from './use-model-override';
+
+// Onboarding Wizard Components
+export {
+  OnboardingWizard,
+  useOnboardingWizard,
+  ONBOARDING_STORAGE_PREFIX,
+  ONBOARDING_TARGET_ATTRIBUTE,
+  ONBOARDING_ANALYTICS,
+  type OnboardingStep,
+  type OnboardingState,
+  type OnboardingWizardProps,
+  type UseOnboardingWizardOptions,
+  type UseOnboardingWizardResult,
+} from './onboarding';

apps/ui/src/components/shared/onboarding/constants.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared Onboarding Wizard Constants
+ *
+ * Layout, positioning, and timing constants for the onboarding wizard.
+ */
+
+/** Storage key prefix for onboarding state */
+export const ONBOARDING_STORAGE_PREFIX = 'automaker:onboarding';
+
+/** Padding around spotlight highlight elements (px) */
+export const SPOTLIGHT_PADDING = 8;
+
+/** Padding between target element and tooltip (px) */
+export const TOOLTIP_OFFSET = 16;
+
+/** Vertical offset from top of target to tooltip (px) */
+export const TOOLTIP_TOP_OFFSET = 40;
+
+/** Maximum tooltip width (px) */
+export const TOOLTIP_MAX_WIDTH = 400;
+
+/** Minimum safe margin from viewport edges (px) */
+export const VIEWPORT_SAFE_MARGIN = 16;
+
+/** Threshold for placing tooltip to the right of target (30% of viewport) */
+export const TOOLTIP_POSITION_RIGHT_THRESHOLD = 0.3;
+
+/** Threshold for placing tooltip to the left of target (70% of viewport) */
+export const TOOLTIP_POSITION_LEFT_THRESHOLD = 0.7;
+
+/** Threshold from bottom of viewport to trigger alternate positioning (px) */
+export const BOTTOM_THRESHOLD = 450;
+
+/** Debounce delay for resize handler (ms) */
+export const RESIZE_DEBOUNCE_MS = 100;
+
+/** Animation duration for step transitions (ms) */
+export const STEP_TRANSITION_DURATION = 200;
+
+/** ID for the wizard description element (for aria-describedby) */
+export const WIZARD_DESCRIPTION_ID = 'onboarding-wizard-description';
+
+/** ID for the wizard title element (for aria-labelledby) */
+export const WIZARD_TITLE_ID = 'onboarding-wizard-title';
+
+/** Data attribute name for targeting elements */
+export const ONBOARDING_TARGET_ATTRIBUTE = 'data-onboarding-target';
+
+/** Analytics event names for onboarding tracking */
+export const ONBOARDING_ANALYTICS = {
+  STARTED: 'onboarding_started',
+  COMPLETED: 'onboarding_completed',
+  SKIPPED: 'onboarding_skipped',
+  STEP_VIEWED: 'onboarding_step_viewed',
+} as const;

apps/ui/src/components/shared/onboarding/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared Onboarding Components
+ *
+ * Generic onboarding wizard infrastructure for building
+ * interactive tutorials across different views.
+ */
+
+export { OnboardingWizard } from './onboarding-wizard';
+export { useOnboardingWizard } from './use-onboarding-wizard';
+export type {
+  OnboardingStep,
+  OnboardingState,
+  OnboardingWizardProps,
+  UseOnboardingWizardOptions,
+  UseOnboardingWizardResult,
+} from './types';
+export {
+  ONBOARDING_STORAGE_PREFIX,
+  ONBOARDING_TARGET_ATTRIBUTE,
+  ONBOARDING_ANALYTICS,
+} from './constants';

apps/ui/src/components/shared/onboarding/onboarding-wizard.tsx

@@ -0,0 +1,545 @@
+/**
+ * Generic Onboarding Wizard Component
+ *
+ * A multi-step wizard overlay that guides users through features
+ * with visual highlighting (spotlight effect) on target elements.
+ *
+ * Features:
+ * - Spotlight overlay targeting elements via data-onboarding-target
+ * - Responsive tooltip positioning (left/right/bottom)
+ * - Step navigation (keyboard & mouse)
+ * - Configurable children slot for view-specific content
+ * - Completion celebration animation
+ * - Full accessibility (ARIA, focus management)
+ */
+
+import { useEffect, useRef, useCallback, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { X, ChevronLeft, ChevronRight, CheckCircle2, PartyPopper, Sparkles } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+import {
+  SPOTLIGHT_PADDING,
+  TOOLTIP_OFFSET,
+  TOOLTIP_TOP_OFFSET,
+  TOOLTIP_MAX_WIDTH,
+  VIEWPORT_SAFE_MARGIN,
+  TOOLTIP_POSITION_RIGHT_THRESHOLD,
+  TOOLTIP_POSITION_LEFT_THRESHOLD,
+  BOTTOM_THRESHOLD,
+  RESIZE_DEBOUNCE_MS,
+  STEP_TRANSITION_DURATION,
+  WIZARD_DESCRIPTION_ID,
+  WIZARD_TITLE_ID,
+  ONBOARDING_TARGET_ATTRIBUTE,
+} from './constants';
+import type { OnboardingWizardProps, OnboardingStep } from './types';
+
+interface HighlightRect {
+  top: number;
+  left: number;
+  right: number;
+  bottom: number;
+  width: number;
+  height: number;
+}
+
+export function OnboardingWizard({
+  isVisible,
+  currentStep,
+  currentStepData,
+  totalSteps,
+  onNext,
+  onPrevious,
+  onSkip,
+  onComplete,
+  steps,
+  children,
+}: OnboardingWizardProps) {
+  const [highlightRect, setHighlightRect] = useState<HighlightRect | null>(null);
+  const [tooltipPosition, setTooltipPosition] = useState<'left' | 'right' | 'bottom'>('bottom');
+  const [isAnimating, setIsAnimating] = useState(false);
+  const [showCompletionCelebration, setShowCompletionCelebration] = useState(false);
+
+  // Refs for focus management
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const nextButtonRef = useRef<HTMLButtonElement>(null);
+
+  // Detect if user is on a touch device
+  const [isTouchDevice, setIsTouchDevice] = useState(false);
+
+  useEffect(() => {
+    setIsTouchDevice('ontouchstart' in window || navigator.maxTouchPoints > 0);
+  }, []);
+
+  // Lock scroll when wizard is visible
+  useEffect(() => {
+    if (!isVisible) return;
+
+    const originalOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+
+    return () => {
+      document.body.style.overflow = originalOverflow;
+    };
+  }, [isVisible]);
+
+  // Focus management - move focus to dialog when opened
+  useEffect(() => {
+    if (!isVisible) return;
+
+    const timer = setTimeout(() => {
+      nextButtonRef.current?.focus();
+    }, STEP_TRANSITION_DURATION);
+
+    return () => clearTimeout(timer);
+  }, [isVisible]);
+
+  // Animate step transitions
+  useEffect(() => {
+    if (!isVisible) return;
+
+    setIsAnimating(true);
+    const timer = setTimeout(() => {
+      setIsAnimating(false);
+    }, STEP_TRANSITION_DURATION);
+
+    return () => clearTimeout(timer);
+  }, [currentStep, isVisible]);
+
+  // Find and highlight the target element
+  useEffect(() => {
+    if (!isVisible || !currentStepData) {
+      setHighlightRect(null);
+      return;
+    }
+
+    const updateHighlight = () => {
+      // Find target element by data-onboarding-target attribute
+      const targetEl = document.querySelector(
+        `[${ONBOARDING_TARGET_ATTRIBUTE}="${currentStepData.targetId}"]`
+      );
+
+      if (targetEl) {
+        const rect = targetEl.getBoundingClientRect();
+        setHighlightRect({
+          top: rect.top,
+          left: rect.left,
+          right: rect.right,
+          bottom: rect.bottom,
+          width: rect.width,
+          height: rect.height,
+        });
+
+        // Determine tooltip position based on target position and available space
+        const viewportWidth = window.innerWidth;
+        const viewportHeight = window.innerHeight;
+        const targetCenter = rect.left + rect.width / 2;
+        const tooltipWidth = Math.min(TOOLTIP_MAX_WIDTH, viewportWidth - VIEWPORT_SAFE_MARGIN * 2);
+
+        const spaceAtBottom = viewportHeight - rect.bottom - TOOLTIP_OFFSET;
+        const spaceAtRight = viewportWidth - rect.right - TOOLTIP_OFFSET;
+        const spaceAtLeft = rect.left - TOOLTIP_OFFSET;
+
+        // For leftmost targets, prefer right position
+        if (
+          targetCenter < viewportWidth * TOOLTIP_POSITION_RIGHT_THRESHOLD &&
+          spaceAtRight >= tooltipWidth
+        ) {
+          setTooltipPosition('right');
+        }
+        // For rightmost targets, prefer left position
+        else if (
+          targetCenter > viewportWidth * TOOLTIP_POSITION_LEFT_THRESHOLD &&
+          spaceAtLeft >= tooltipWidth
+        ) {
+          setTooltipPosition('left');
+        }
+        // For middle targets, check if bottom position would work
+        else if (spaceAtBottom >= BOTTOM_THRESHOLD) {
+          setTooltipPosition('bottom');
+        }
+        // Fallback logic
+        else if (spaceAtRight > spaceAtLeft && spaceAtRight >= tooltipWidth * 0.6) {
+          setTooltipPosition('right');
+        } else if (spaceAtLeft >= tooltipWidth * 0.6) {
+          setTooltipPosition('left');
+        } else {
+          setTooltipPosition('bottom');
+        }
+      }
+    };
+
+    updateHighlight();
+
+    // Debounced resize handler
+    let resizeTimeout: ReturnType<typeof setTimeout>;
+    const handleResize = () => {
+      clearTimeout(resizeTimeout);
+      resizeTimeout = setTimeout(updateHighlight, RESIZE_DEBOUNCE_MS);
+    };
+
+    window.addEventListener('resize', handleResize);
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      clearTimeout(resizeTimeout);
+    };
+  }, [isVisible, currentStepData]);
+
+  // Keyboard navigation
+  useEffect(() => {
+    if (!isVisible) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        onSkip();
+      } else if (e.key === 'ArrowRight' || e.key === 'Enter') {
+        if (currentStep < totalSteps - 1) {
+          onNext();
+        } else {
+          handleComplete();
+        }
+      } else if (e.key === 'ArrowLeft') {
+        onPrevious();
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [isVisible, currentStep, totalSteps, onNext, onPrevious, onSkip]);
+
+  // Calculate tooltip styles based on position and highlight rect
+  const getTooltipStyles = useCallback((): React.CSSProperties => {
+    if (!highlightRect) return {};
+
+    const viewportHeight = window.innerHeight;
+    const viewportWidth = window.innerWidth;
+    const tooltipWidth = Math.min(TOOLTIP_MAX_WIDTH, viewportWidth - VIEWPORT_SAFE_MARGIN * 2);
+
+    switch (tooltipPosition) {
+      case 'right': {
+        const topPos = Math.max(VIEWPORT_SAFE_MARGIN, highlightRect.top + TOOLTIP_TOP_OFFSET);
+        const availableHeight = viewportHeight - topPos - VIEWPORT_SAFE_MARGIN;
+        return {
+          position: 'fixed',
+          top: topPos,
+          left: highlightRect.right + TOOLTIP_OFFSET,
+          width: tooltipWidth,
+          maxWidth: `calc(100vw - ${highlightRect.right + TOOLTIP_OFFSET * 2}px)`,
+          maxHeight: Math.max(200, availableHeight),
+        };
+      }
+      case 'left': {
+        const topPos = Math.max(VIEWPORT_SAFE_MARGIN, highlightRect.top + TOOLTIP_TOP_OFFSET);
+        const availableHeight = viewportHeight - topPos - VIEWPORT_SAFE_MARGIN;
+        return {
+          position: 'fixed',
+          top: topPos,
+          right: viewportWidth - highlightRect.left + TOOLTIP_OFFSET,
+          width: tooltipWidth,
+          maxWidth: `calc(${highlightRect.left - TOOLTIP_OFFSET * 2}px)`,
+          maxHeight: Math.max(200, availableHeight),
+        };
+      }
+      case 'bottom':
+      default: {
+        const idealTop = highlightRect.bottom + TOOLTIP_OFFSET;
+        const availableHeight = viewportHeight - idealTop - VIEWPORT_SAFE_MARGIN;
+
+        const minTop = 100;
+        const topPos =
+          availableHeight < 250
+            ? Math.max(
+                minTop,
+                viewportHeight - Math.max(300, availableHeight) - VIEWPORT_SAFE_MARGIN
+              )
+            : idealTop;
+
+        const idealLeft = highlightRect.left + highlightRect.width / 2 - tooltipWidth / 2;
+        const leftPos = Math.max(
+          VIEWPORT_SAFE_MARGIN,
+          Math.min(idealLeft, viewportWidth - tooltipWidth - VIEWPORT_SAFE_MARGIN)
+        );
+
+        return {
+          position: 'fixed',
+          top: topPos,
+          left: leftPos,
+          width: tooltipWidth,
+          maxHeight: Math.max(200, viewportHeight - topPos - VIEWPORT_SAFE_MARGIN),
+        };
+      }
+    }
+  }, [highlightRect, tooltipPosition]);
+
+  // Handle completion with celebration
+  const handleComplete = useCallback(() => {
+    setShowCompletionCelebration(true);
+    setTimeout(() => {
+      setShowCompletionCelebration(false);
+      onComplete();
+    }, 1200);
+  }, [onComplete]);
+
+  // Handle step indicator click for direct navigation
+  const handleStepClick = useCallback(
+    (stepIndex: number) => {
+      if (stepIndex === currentStep) return;
+
+      if (stepIndex > currentStep) {
+        for (let i = currentStep; i < stepIndex; i++) {
+          onNext();
+        }
+      } else {
+        for (let i = currentStep; i > stepIndex; i--) {
+          onPrevious();
+        }
+      }
+    },
+    [currentStep, onNext, onPrevious]
+  );
+
+  if (!isVisible || !currentStepData) return null;
+
+  const StepIcon = currentStepData.icon || Sparkles;
+  const isLastStep = currentStep === totalSteps - 1;
+  const isFirstStep = currentStep === 0;
+
+  const content = (
+    <div
+      ref={dialogRef}
+      className="fixed inset-0 z-[100]"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby={WIZARD_TITLE_ID}
+      aria-describedby={WIZARD_DESCRIPTION_ID}
+    >
+      {/* Completion celebration overlay */}
+      {showCompletionCelebration && (
+        <div className="absolute inset-0 z-[102] flex items-center justify-center pointer-events-none">
+          <div className="animate-in zoom-in-50 fade-in duration-300 flex flex-col items-center gap-4 text-white">
+            <PartyPopper className="w-16 h-16 text-yellow-400 animate-bounce" />
+            <p className="text-2xl font-bold">You're all set!</p>
+          </div>
+        </div>
+      )}
+
+      {/* Dark overlay with cutout for highlighted element */}
+      <svg
+        className="absolute inset-0 w-full h-full pointer-events-none"
+        xmlns="http://www.w3.org/2000/svg"
+        aria-hidden="true"
+      >
+        <defs>
+          <mask id="spotlight-mask">
+            <rect x="0" y="0" width="100%" height="100%" fill="white" />
+            {highlightRect && (
+              <rect
+                x={highlightRect.left - SPOTLIGHT_PADDING}
+                y={highlightRect.top - SPOTLIGHT_PADDING}
+                width={highlightRect.width + SPOTLIGHT_PADDING * 2}
+                height={highlightRect.height + SPOTLIGHT_PADDING * 2}
+                rx="16"
+                fill="black"
+              />
+            )}
+          </mask>
+        </defs>
+        <rect
+          x="0"
+          y="0"
+          width="100%"
+          height="100%"
+          fill="rgba(0, 0, 0, 0.75)"
+          mask="url(#spotlight-mask)"
+          className="transition-all duration-300"
+        />
+      </svg>
+
+      {/* Highlight border around the target element */}
+      {highlightRect && (
+        <div
+          className="absolute pointer-events-none transition-all duration-300 ease-out"
+          style={{
+            left: highlightRect.left - SPOTLIGHT_PADDING,
+            top: highlightRect.top - SPOTLIGHT_PADDING,
+            width: highlightRect.width + SPOTLIGHT_PADDING * 2,
+            height: highlightRect.height + SPOTLIGHT_PADDING * 2,
+            borderRadius: '16px',
+            border: '2px solid hsl(var(--primary))',
+            boxShadow:
+              '0 0 20px 4px hsl(var(--primary) / 0.3), inset 0 0 20px 4px hsl(var(--primary) / 0.1)',
+          }}
+        />
+      )}
+
+      {/* Skip button - top right */}
+      <Button
+        variant="ghost"
+        size="sm"
+        className={cn(
+          'fixed top-4 right-4 z-[101]',
+          'text-white/70 hover:text-white hover:bg-white/10',
+          'focus-visible:ring-2 focus-visible:ring-white focus-visible:ring-offset-2 focus-visible:ring-offset-transparent',
+          'min-h-[44px] min-w-[44px] px-3'
+        )}
+        onClick={onSkip}
+        aria-label="Skip the onboarding tour"
+      >
+        <X className="w-4 h-4 mr-1.5" aria-hidden="true" />
+        <span>Skip Tour</span>
+      </Button>
+
+      {/* Tooltip card with step content */}
+      <div
+        className={cn(
+          'z-[101] bg-popover/95 backdrop-blur-xl rounded-xl shadow-2xl border border-border/50',
+          'p-6 animate-in fade-in-0 slide-in-from-bottom-4 duration-300',
+          'max-h-[calc(100vh-100px)] overflow-y-auto',
+          isAnimating && 'opacity-90 scale-[0.98]',
+          'transition-all duration-200 ease-out'
+        )}
+        style={getTooltipStyles()}
+      >
+        {/* Header */}
+        <div className="flex items-start gap-4 mb-4">
+          <div className="flex items-center justify-center w-12 h-12 rounded-xl bg-primary/10 border border-primary/20 shrink-0">
+            <StepIcon className="w-6 h-6 text-primary" />
+          </div>
+          <div className="flex-1 min-w-0">
+            <h3 id={WIZARD_TITLE_ID} className="text-lg font-semibold text-foreground truncate">
+              {currentStepData.title}
+            </h3>
+            <div className="flex items-center gap-2 mt-1.5">
+              <span className="text-xs text-muted-foreground" aria-live="polite">
+                Step {currentStep + 1} of {totalSteps}
+              </span>
+              {/* Step indicators - clickable for navigation */}
+              <nav aria-label="Wizard steps" className="flex items-center gap-1">
+                {Array.from({ length: totalSteps }).map((_, i) => (
+                  <button
+                    key={i}
+                    type="button"
+                    onClick={() => handleStepClick(i)}
+                    className={cn(
+                      'relative flex items-center justify-center',
+                      'w-6 h-6',
+                      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-1 focus-visible:rounded-full',
+                      'transition-transform duration-200 hover:scale-110'
+                    )}
+                    aria-label={`Go to step ${i + 1}: ${steps[i]?.title}`}
+                    aria-current={i === currentStep ? 'step' : undefined}
+                  >
+                    <span
+                      className={cn(
+                        'block rounded-full transition-all duration-200',
+                        i === currentStep
+                          ? 'w-2.5 h-2.5 bg-primary ring-2 ring-primary/30 ring-offset-1 ring-offset-popover'
+                          : i < currentStep
+                            ? 'w-2 h-2 bg-primary/60'
+                            : 'w-2 h-2 bg-muted-foreground/40'
+                      )}
+                    />
+                  </button>
+                ))}
+              </nav>
+            </div>
+          </div>
+        </div>
+
+        {/* Description */}
+        <p
+          id={WIZARD_DESCRIPTION_ID}
+          className="text-sm text-muted-foreground leading-relaxed mb-4"
+        >
+          {currentStepData.description}
+        </p>
+
+        {/* Tip box */}
+        {currentStepData.tip && (
+          <div className="rounded-lg bg-primary/5 border border-primary/10 p-3 mb-4">
+            <p className="text-xs text-muted-foreground">
+              <span className="font-medium text-foreground">Tip: </span>
+              {currentStepData.tip}
+            </p>
+          </div>
+        )}
+
+        {/* Custom content slot (e.g., Quick Start section) */}
+        {children}
+
+        {/* Navigation buttons */}
+        <div className="flex items-center justify-between gap-3 pt-2">
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={onPrevious}
+            disabled={isFirstStep}
+            className={cn(
+              'text-muted-foreground min-h-[44px]',
+              'focus-visible:ring-2 focus-visible:ring-primary',
+              isFirstStep && 'invisible'
+            )}
+            aria-label="Go to previous step"
+          >
+            <ChevronLeft className="w-4 h-4 mr-1" aria-hidden="true" />
+            <span>Previous</span>
+          </Button>
+
+          <Button
+            ref={nextButtonRef}
+            size="sm"
+            onClick={isLastStep ? handleComplete : onNext}
+            disabled={showCompletionCelebration}
+            className={cn(
+              'bg-primary hover:bg-primary/90 text-primary-foreground',
+              'min-w-[120px] min-h-[44px]',
+              'focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2',
+              'transition-all duration-200'
+            )}
+            aria-label={isLastStep ? 'Complete the tour and get started' : 'Go to next step'}
+          >
+            {isLastStep ? (
+              <>
+                <span>Get Started</span>
+                <CheckCircle2 className="w-4 h-4 ml-1.5" aria-hidden="true" />
+              </>
+            ) : (
+              <>
+                <span>Next</span>
+                <ChevronRight className="w-4 h-4 ml-1" aria-hidden="true" />
+              </>
+            )}
+          </Button>
+        </div>
+
+        {/* Keyboard hints - hidden on touch devices */}
+        {!isTouchDevice && (
+          <div
+            className="mt-4 pt-3 border-t border-border/50 flex items-center justify-center gap-4 text-xs text-muted-foreground/70"
+            aria-hidden="true"
+          >
+            <span className="flex items-center gap-1.5">
+              <kbd className="px-2 py-1 rounded bg-muted text-muted-foreground font-mono text-[11px] shadow-sm">
+                ESC
+              </kbd>
+              <span>to skip</span>
+            </span>
+            <span className="flex items-center gap-1.5">
+              <kbd className="px-2 py-1 rounded bg-muted text-muted-foreground font-mono text-[11px] shadow-sm">
+                ←
+              </kbd>
+              <kbd className="px-2 py-1 rounded bg-muted text-muted-foreground font-mono text-[11px] shadow-sm">
+                →
+              </kbd>
+              <span>to navigate</span>
+            </span>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+
+  // Render in a portal to ensure it's above everything
+  return createPortal(content, document.body);
+}

apps/ui/src/components/shared/onboarding/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared Onboarding Wizard Types
+ *
+ * Generic types for building onboarding wizards across different views.
+ */
+
+import type { ComponentType } from 'react';
+
+/**
+ * Represents a single step in the onboarding wizard
+ */
+export interface OnboardingStep {
+  /** Unique identifier for this step */
+  id: string;
+  /** Target element ID - matches data-onboarding-target attribute */
+  targetId: string;
+  /** Step title displayed in the wizard */
+  title: string;
+  /** Main description explaining this step */
+  description: string;
+  /** Optional tip shown in a highlighted box */
+  tip?: string;
+  /** Optional icon component for visual identification */
+  icon?: ComponentType<{ className?: string }>;
+}
+
+/**
+ * Persisted onboarding state structure
+ */
+export interface OnboardingState {
+  /** Whether the wizard has been completed */
+  completed: boolean;
+  /** ISO timestamp when completed */
+  completedAt?: string;
+  /** Whether the wizard has been skipped */
+  skipped: boolean;
+  /** ISO timestamp when skipped */
+  skippedAt?: string;
+}
+
+/**
+ * Options for the useOnboardingWizard hook
+ */
+export interface UseOnboardingWizardOptions {
+  /** Unique storage key for localStorage persistence */
+  storageKey: string;
+  /** Array of wizard steps to display */
+  steps: OnboardingStep[];
+  /** Optional callback when wizard is completed */
+  onComplete?: () => void;
+  /** Optional callback when wizard is skipped */
+  onSkip?: () => void;
+}
+
+/**
+ * Return type for the useOnboardingWizard hook
+ */
+export interface UseOnboardingWizardResult {
+  /** Whether the wizard is currently visible */
+  isVisible: boolean;
+  /** Current step index (0-based) */
+  currentStep: number;
+  /** Current step data or null if not available */
+  currentStepData: OnboardingStep | null;
+  /** Total number of steps */
+  totalSteps: number;
+  /** Navigate to the next step */
+  goToNextStep: () => void;
+  /** Navigate to the previous step */
+  goToPreviousStep: () => void;
+  /** Navigate to a specific step by index */
+  goToStep: (step: number) => void;
+  /** Start/show the wizard from the beginning */
+  startWizard: () => void;
+  /** Complete the wizard and hide it */
+  completeWizard: () => void;
+  /** Skip the wizard and hide it */
+  skipWizard: () => void;
+  /** Whether the wizard has been completed */
+  isCompleted: boolean;
+  /** Whether the wizard has been skipped */
+  isSkipped: boolean;
+}
+
+/**
+ * Props for the OnboardingWizard component
+ */
+export interface OnboardingWizardProps {
+  /** Whether the wizard is visible */
+  isVisible: boolean;
+  /** Current step index */
+  currentStep: number;
+  /** Current step data */
+  currentStepData: OnboardingStep | null;
+  /** Total number of steps */
+  totalSteps: number;
+  /** Handler for next step navigation */
+  onNext: () => void;
+  /** Handler for previous step navigation */
+  onPrevious: () => void;
+  /** Handler for skipping the wizard */
+  onSkip: () => void;
+  /** Handler for completing the wizard */
+  onComplete: () => void;
+  /** Array of all steps (for step indicator navigation) */
+  steps: OnboardingStep[];
+  /** Optional content to render before navigation buttons (e.g., Quick Start) */
+  children?: React.ReactNode;
+}

apps/ui/src/components/shared/onboarding/use-onboarding-wizard.ts

@@ -0,0 +1,216 @@
+/**
+ * Generic Onboarding Wizard Hook
+ *
+ * Manages the state and logic for interactive onboarding wizards.
+ * Can be used to create onboarding experiences for any view.
+ *
+ * Features:
+ * - Persists completion status to localStorage
+ * - Step navigation (next, previous, jump to step)
+ * - Analytics tracking hooks
+ * - No auto-show logic - wizard only shows via startWizard()
+ */
+
+import { useState, useCallback, useEffect, useMemo } from 'react';
+import { createLogger } from '@automaker/utils/logger';
+import { getItem, setItem } from '@/lib/storage';
+import { ONBOARDING_STORAGE_PREFIX, ONBOARDING_ANALYTICS } from './constants';
+import type {
+  OnboardingState,
+  OnboardingStep,
+  UseOnboardingWizardOptions,
+  UseOnboardingWizardResult,
+} from './types';
+
+const logger = createLogger('OnboardingWizard');
+
+/** Default state for new wizards */
+const DEFAULT_ONBOARDING_STATE: OnboardingState = {
+  completed: false,
+  skipped: false,
+};
+
+/**
+ * Load onboarding state from localStorage
+ */
+function loadOnboardingState(storageKey: string): OnboardingState {
+  try {
+    const fullKey = `${ONBOARDING_STORAGE_PREFIX}:${storageKey}`;
+    const stored = getItem(fullKey);
+    if (stored) {
+      return JSON.parse(stored) as OnboardingState;
+    }
+  } catch (error) {
+    logger.error('Failed to load onboarding state:', error);
+  }
+  return { ...DEFAULT_ONBOARDING_STATE };
+}
+
+/**
+ * Save onboarding state to localStorage
+ */
+function saveOnboardingState(storageKey: string, state: OnboardingState): void {
+  try {
+    const fullKey = `${ONBOARDING_STORAGE_PREFIX}:${storageKey}`;
+    setItem(fullKey, JSON.stringify(state));
+  } catch (error) {
+    logger.error('Failed to save onboarding state:', error);
+  }
+}
+
+/**
+ * Track analytics event (placeholder - integrate with actual analytics service)
+ */
+function trackAnalytics(event: string, data?: Record<string, unknown>): void {
+  logger.debug(`[Analytics] ${event}`, data);
+}
+
+/**
+ * Generic hook for managing onboarding wizard state.
+ *
+ * @example
+ * ```tsx
+ * const wizard = useOnboardingWizard({
+ *   storageKey: 'my-view-onboarding',
+ *   steps: MY_WIZARD_STEPS,
+ *   onComplete: () => console.log('Done!'),
+ * });
+ *
+ * // Start the wizard when user clicks help button
+ * <button onClick={wizard.startWizard}>Help</button>
+ *
+ * // Render the wizard
+ * <OnboardingWizard
+ *   isVisible={wizard.isVisible}
+ *   currentStep={wizard.currentStep}
+ *   currentStepData={wizard.currentStepData}
+ *   totalSteps={wizard.totalSteps}
+ *   onNext={wizard.goToNextStep}
+ *   onPrevious={wizard.goToPreviousStep}
+ *   onSkip={wizard.skipWizard}
+ *   onComplete={wizard.completeWizard}
+ *   steps={MY_WIZARD_STEPS}
+ * />
+ * ```
+ */
+export function useOnboardingWizard({
+  storageKey,
+  steps,
+  onComplete,
+  onSkip,
+}: UseOnboardingWizardOptions): UseOnboardingWizardResult {
+  const [currentStep, setCurrentStep] = useState(0);
+  const [isWizardVisible, setIsWizardVisible] = useState(false);
+  const [onboardingState, setOnboardingState] = useState<OnboardingState>(DEFAULT_ONBOARDING_STATE);
+
+  // Load persisted state on mount
+  useEffect(() => {
+    const state = loadOnboardingState(storageKey);
+    setOnboardingState(state);
+  }, [storageKey]);
+
+  // Update persisted state helper
+  const updateState = useCallback(
+    (updates: Partial<OnboardingState>) => {
+      setOnboardingState((prev) => {
+        const newState = { ...prev, ...updates };
+        saveOnboardingState(storageKey, newState);
+        return newState;
+      });
+    },
+    [storageKey]
+  );
+
+  // Current step data
+  const currentStepData = useMemo(() => steps[currentStep] || null, [steps, currentStep]);
+  const totalSteps = steps.length;
+
+  // Navigation handlers
+  const goToNextStep = useCallback(() => {
+    if (currentStep < totalSteps - 1) {
+      const nextStep = currentStep + 1;
+      setCurrentStep(nextStep);
+      trackAnalytics(ONBOARDING_ANALYTICS.STEP_VIEWED, {
+        storageKey,
+        step: nextStep,
+        stepId: steps[nextStep]?.id,
+      });
+    }
+  }, [currentStep, totalSteps, storageKey, steps]);
+
+  const goToPreviousStep = useCallback(() => {
+    if (currentStep > 0) {
+      setCurrentStep(currentStep - 1);
+    }
+  }, [currentStep]);
+
+  const goToStep = useCallback(
+    (step: number) => {
+      if (step >= 0 && step < totalSteps) {
+        setCurrentStep(step);
+        trackAnalytics(ONBOARDING_ANALYTICS.STEP_VIEWED, {
+          storageKey,
+          step,
+          stepId: steps[step]?.id,
+        });
+      }
+    },
+    [totalSteps, storageKey, steps]
+  );
+
+  // Wizard lifecycle handlers
+  const startWizard = useCallback(() => {
+    setCurrentStep(0);
+    setIsWizardVisible(true);
+    trackAnalytics(ONBOARDING_ANALYTICS.STARTED, { storageKey });
+  }, [storageKey]);
+
+  const completeWizard = useCallback(() => {
+    setIsWizardVisible(false);
+    setCurrentStep(0);
+    updateState({
+      completed: true,
+      completedAt: new Date().toISOString(),
+    });
+    trackAnalytics(ONBOARDING_ANALYTICS.COMPLETED, { storageKey });
+    onComplete?.();
+  }, [storageKey, updateState, onComplete]);
+
+  const skipWizard = useCallback(() => {
+    setIsWizardVisible(false);
+    setCurrentStep(0);
+    updateState({
+      skipped: true,
+      skippedAt: new Date().toISOString(),
+    });
+    trackAnalytics(ONBOARDING_ANALYTICS.SKIPPED, {
+      storageKey,
+      skippedAtStep: currentStep,
+    });
+    onSkip?.();
+  }, [storageKey, currentStep, updateState, onSkip]);
+
+  return {
+    // Visibility
+    isVisible: isWizardVisible,
+
+    // Steps
+    currentStep,
+    currentStepData,
+    totalSteps,
+
+    // Navigation
+    goToNextStep,
+    goToPreviousStep,
+    goToStep,
+
+    // Actions
+    startWizard,
+    completeWizard,
+    skipWizard,
+
+    // State
+    isCompleted: onboardingState.completed,
+    isSkipped: onboardingState.skipped,
+  };
+}

apps/ui/src/components/views/board-view.tsx

@@ -72,9 +72,11 @@ import {
   useBoardPersistence,
   useFollowUpState,
   useSelectionMode,
+  useBoardOnboarding,
 } from './board-view/hooks';
-import { SelectionActionBar } from './board-view/components';
+import { SelectionActionBar, BoardOnboardingWizard } from './board-view/components';
 import { MassEditDialog } from './board-view/dialogs';
+import { generateSampleFeatures, isSampleFeature } from './board-view/constants';
 
 // Stable empty array to avoid infinite loop in selector
 const EMPTY_WORKTREES: ReturnType<ReturnType<typeof useAppStore.getState>['getWorktrees']> = [];
@@ -186,6 +188,8 @@ export function BoardView() {
   const [searchQuery, setSearchQuery] = useState('');
   // Plan approval loading state
   const [isPlanApprovalLoading, setIsPlanApprovalLoading] = useState(false);
+  // Quick start loading state for onboarding
+  const [isQuickStartLoading, setIsQuickStartLoading] = useState(false);
   // Derive spec creation state from store - check if current project is the one being created
   const isCreatingSpec = specCreatingForProject === currentProject?.path;
   const creatingSpecProjectPath = specCreatingForProject ?? undefined;
@@ -1028,6 +1032,76 @@ export function BoardView() {
     currentProject,
   });
 
+  // Use onboarding wizard hook - triggered manually via help button
+  const onboarding = useBoardOnboarding({
+    projectPath: currentProject?.path || null,
+  });
+
+  // Handler for Quick Start - create sample features
+  const handleQuickStart = useCallback(async () => {
+    if (!currentProject) return;
+
+    setIsQuickStartLoading(true);
+    try {
+      const api = getHttpApiClient();
+      const sampleFeatures = generateSampleFeatures();
+
+      // Create each sample feature
+      for (const featureData of sampleFeatures) {
+        const result = await api.features.create(currentProject.path, featureData);
+        if (result.success && result.feature) {
+          useAppStore.getState().addFeature(result.feature);
+        }
+      }
+
+      onboarding.markQuickStartUsed();
+      toast.success('Sample tasks added!', {
+        description: 'Explore the board to see tasks at different stages.',
+      });
+
+      // Reload features to ensure state is in sync
+      loadFeatures();
+    } catch (error) {
+      logger.error('Failed to create sample features:', error);
+      toast.error('Failed to add sample tasks');
+    } finally {
+      setIsQuickStartLoading(false);
+    }
+  }, [currentProject, loadFeatures, onboarding]);
+
+  // Handler for clearing sample data
+  const handleClearSampleData = useCallback(async () => {
+    if (!currentProject) return;
+
+    const sampleFeatures = hookFeatures.filter((f) => isSampleFeature(f));
+    if (sampleFeatures.length === 0) {
+      onboarding.setHasSampleData(false);
+      return;
+    }
+
+    try {
+      const api = getHttpApiClient();
+      const featureIds = sampleFeatures.map((f) => f.id);
+      const result = await api.features.bulkDelete(currentProject.path, featureIds);
+
+      if (result.success || (result.results && result.results.some((r) => r.success))) {
+        // Remove from local state
+        const successfullyDeletedIds =
+          result.results?.filter((r) => r.success).map((r) => r.featureId) ?? featureIds;
+        successfullyDeletedIds.forEach((id) => {
+          useAppStore.getState().removeFeature(id);
+        });
+
+        onboarding.setHasSampleData(false);
+        toast.success('Sample tasks removed');
+        loadFeatures();
+      }
+    } catch (error) {
+      logger.error('Failed to clear sample data:', error);
+      toast.error('Failed to remove sample tasks');
+    }
+  }, [currentProject, hookFeatures, loadFeatures, onboarding]);
+
   // Find feature for pending plan approval
   const pendingApprovalFeature = useMemo(() => {
     if (!pendingPlanApproval) return null;
@@ -1210,6 +1284,7 @@ export function BoardView() {
         onShowBoardBackground={() => setShowBoardBackgroundModal(true)}
         onShowCompletedModal={() => setShowCompletedModal(true)}
         completedCount={completedFeatures.length}
+        onStartTour={onboarding.startWizard}
       />
 
       {/* Worktree Panel - conditionally rendered based on visibility setting */}
@@ -1568,6 +1643,23 @@ export function BoardView() {
           setSelectedWorktreeForAction(null);
         }}
       />
+
+      {/* Board Onboarding Wizard */}
+      <BoardOnboardingWizard
+        isVisible={onboarding.isWizardVisible}
+        currentStep={onboarding.currentStep}
+        currentStepData={onboarding.currentStepData}
+        totalSteps={onboarding.totalSteps}
+        onNext={onboarding.goToNextStep}
+        onPrevious={onboarding.goToPreviousStep}
+        onSkip={onboarding.skipWizard}
+        onComplete={onboarding.completeWizard}
+        onQuickStart={handleQuickStart}
+        hasSampleData={onboarding.hasSampleData}
+        onClearSampleData={handleClearSampleData}
+        isQuickStartLoading={isQuickStartLoading}
+        steps={onboarding.steps}
+      />
     </div>
   );
 }

apps/ui/src/components/views/board-view/board-controls.tsx

@@ -1,12 +1,14 @@
 import { Button } from '@/components/ui/button';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
-import { ImageIcon, Archive } from 'lucide-react';
+import { ImageIcon, Archive, HelpCircle } from 'lucide-react';
 
 interface BoardControlsProps {
   isMounted: boolean;
   onShowBoardBackground: () => void;
   onShowCompletedModal: () => void;
   completedCount: number;
+  /** Callback to start the onboarding wizard tour */
+  onStartTour?: () => void;
 }
 
 export function BoardControls({
@@ -14,12 +16,34 @@ export function BoardControls({
   onShowBoardBackground,
   onShowCompletedModal,
   completedCount,
+  onStartTour,
 }: BoardControlsProps) {
   if (!isMounted) return null;
 
   return (
     <TooltipProvider>
       <div className="flex items-center gap-2">
+        {/* Board Tour Button - always visible when handler is provided */}
+        {onStartTour && (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={onStartTour}
+                className="h-8 px-2 min-w-[32px] focus-visible:ring-2 focus-visible:ring-primary"
+                data-testid="board-tour-button"
+                aria-label="Take a board tour - learn how to use the kanban board"
+              >
+                <HelpCircle className="w-4 h-4" aria-hidden="true" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>
+              <p>Take a Board Tour</p>
+            </TooltipContent>
+          </Tooltip>
+        )}
+
         {/* Board Background Button */}
         <Tooltip>
           <TooltipTrigger asChild>

apps/ui/src/components/views/board-view/board-header.tsx

@@ -31,6 +31,8 @@ interface BoardHeaderProps {
   onShowBoardBackground: () => void;
   onShowCompletedModal: () => void;
   completedCount: number;
+  // Tour/onboarding props
+  onStartTour?: () => void;
 }
 
 // Shared styles for header control containers
@@ -53,6 +55,7 @@ export function BoardHeader({
   onShowBoardBackground,
   onShowCompletedModal,
   completedCount,
+  onStartTour,
 }: BoardHeaderProps) {
   const [showAutoModeSettings, setShowAutoModeSettings] = useState(false);
   const apiKeys = useAppStore((state) => state.apiKeys);
@@ -113,6 +116,7 @@ export function BoardHeader({
           onShowBoardBackground={onShowBoardBackground}
           onShowCompletedModal={onShowCompletedModal}
           completedCount={completedCount}
+          onStartTour={onStartTour}
         />
       </div>
       <div className="flex gap-2 items-center">

apps/ui/src/components/views/board-view/components/board-onboarding-wizard.tsx

@@ -0,0 +1,137 @@
+/**
+ * Board Onboarding Wizard Component
+ *
+ * Board-specific wrapper around the shared OnboardingWizard component.
+ * Adds Quick Start functionality to generate sample tasks.
+ */
+
+import { Sparkles, CheckCircle2, Trash2, Loader2 } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+import { OnboardingWizard, type OnboardingStep } from '@/components/shared/onboarding';
+
+interface BoardOnboardingWizardProps {
+  isVisible: boolean;
+  currentStep: number;
+  currentStepData: OnboardingStep | null;
+  totalSteps: number;
+  onNext: () => void;
+  onPrevious: () => void;
+  onSkip: () => void;
+  onComplete: () => void;
+  onQuickStart: () => void;
+  hasSampleData: boolean;
+  onClearSampleData: () => void;
+  isQuickStartLoading?: boolean;
+  steps: OnboardingStep[];
+}
+
+/**
+ * Quick Start section component - only shown on first step
+ */
+function QuickStartSection({
+  onQuickStart,
+  hasSampleData,
+  onClearSampleData,
+  isQuickStartLoading = false,
+}: {
+  onQuickStart: () => void;
+  hasSampleData: boolean;
+  onClearSampleData: () => void;
+  isQuickStartLoading?: boolean;
+}) {
+  return (
+    <div className="rounded-lg bg-muted/30 border border-border/50 p-4 mb-4">
+      <h4 className="text-sm font-medium text-foreground mb-2 flex items-center gap-2">
+        <Sparkles className="w-4 h-4 text-primary" aria-hidden="true" />
+        Quick Start
+      </h4>
+      <p className="text-xs text-muted-foreground mb-3">
+        Want to see the board in action? We can add some sample tasks to demonstrate the workflow.
+      </p>
+      <div className="flex gap-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          onClick={onQuickStart}
+          disabled={hasSampleData || isQuickStartLoading}
+          className={cn('flex-1 min-h-[40px]', 'focus-visible:ring-2 focus-visible:ring-primary')}
+          aria-busy={isQuickStartLoading}
+        >
+          {isQuickStartLoading ? (
+            <>
+              <Loader2 className="w-3.5 h-3.5 mr-1.5 animate-spin" aria-hidden="true" />
+              <span>Adding tasks...</span>
+            </>
+          ) : hasSampleData ? (
+            <>
+              <CheckCircle2 className="w-3.5 h-3.5 mr-1.5 text-green-500" aria-hidden="true" />
+              <span>Sample Data Added</span>
+            </>
+          ) : (
+            <>
+              <Sparkles className="w-3.5 h-3.5 mr-1.5" aria-hidden="true" />
+              <span>Add Sample Tasks</span>
+            </>
+          )}
+        </Button>
+        {hasSampleData && (
+          <Button
+            size="sm"
+            variant="ghost"
+            onClick={onClearSampleData}
+            className={cn(
+              'min-w-[44px] min-h-[40px] px-3',
+              'focus-visible:ring-2 focus-visible:ring-destructive'
+            )}
+            aria-label="Remove sample tasks"
+          >
+            <Trash2 className="w-4 h-4" aria-hidden="true" />
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export function BoardOnboardingWizard({
+  isVisible,
+  currentStep,
+  currentStepData,
+  totalSteps,
+  onNext,
+  onPrevious,
+  onSkip,
+  onComplete,
+  onQuickStart,
+  hasSampleData,
+  onClearSampleData,
+  isQuickStartLoading = false,
+  steps,
+}: BoardOnboardingWizardProps) {
+  const isFirstStep = currentStep === 0;
+
+  return (
+    <OnboardingWizard
+      isVisible={isVisible}
+      currentStep={currentStep}
+      currentStepData={currentStepData}
+      totalSteps={totalSteps}
+      onNext={onNext}
+      onPrevious={onPrevious}
+      onSkip={onSkip}
+      onComplete={onComplete}
+      steps={steps}
+    >
+      {/* Board-specific Quick Start section - only on first step */}
+      {isFirstStep && (
+        <QuickStartSection
+          onQuickStart={onQuickStart}
+          hasSampleData={hasSampleData}
+          onClearSampleData={onClearSampleData}
+          isQuickStartLoading={isQuickStartLoading}
+        />
+      )}
+    </OnboardingWizard>
+  );
+}

apps/ui/src/components/views/board-view/components/index.ts

@@ -1,3 +1,4 @@
 export { KanbanCard } from './kanban-card/kanban-card';
 export { KanbanColumn } from './kanban-column';
 export { SelectionActionBar } from './selection-action-bar';
+export { BoardOnboardingWizard } from './board-onboarding-wizard';

apps/ui/src/components/views/board-view/components/kanban-column.tsx

@@ -50,6 +50,7 @@ export const KanbanColumn = memo(function KanbanColumn({
       )}
       style={widthStyle}
       data-testid={`kanban-column-${id}`}
+      data-onboarding-target={id}
     >
       {/* Background layer with opacity */}
       <div

apps/ui/src/components/views/board-view/constants.ts

@@ -89,3 +89,117 @@ export function getStepIdFromStatus(status: string): string | null {
   }
   return status.replace('pipeline_', '');
 }
+
+// ============================================================================
+// SAMPLE DATA FOR ONBOARDING WIZARD
+// ============================================================================
+
+/**
+ * Prefix used to identify sample/demo features in the board
+ * This marker persists through the database and is used for cleanup
+ */
+export const SAMPLE_FEATURE_PREFIX = '[DEMO]';
+
+/**
+ * Sample feature template for Quick Start onboarding
+ * These demonstrate a typical workflow progression across columns
+ */
+export interface SampleFeatureTemplate {
+  title: string;
+  description: string;
+  category: string;
+  status: Feature['status'];
+  priority: number;
+  isSampleData: true; // Marker to identify sample data
+}
+
+/**
+ * Sample features that demonstrate the workflow across all columns.
+ * Each feature shows a realistic task at different stages.
+ */
+export const SAMPLE_FEATURES: SampleFeatureTemplate[] = [
+  // Backlog items - awaiting work
+  {
+    title: '[DEMO] Add user profile page',
+    description:
+      'Create a user profile page where users can view and edit their account settings, change password, and manage preferences.\n\n---\n**This is sample data** - Click the trash icon in the wizard to remove all demo items.',
+    category: 'Feature',
+    status: 'backlog',
+    priority: 1,
+    isSampleData: true,
+  },
+  {
+    title: '[DEMO] Implement dark mode toggle',
+    description:
+      'Add a toggle in the settings to switch between light and dark themes. Should persist the preference across sessions.\n\n---\n**This is sample data** - Click the trash icon in the wizard to remove all demo items.',
+    category: 'Enhancement',
+    status: 'backlog',
+    priority: 2,
+    isSampleData: true,
+  },
+
+  // In Progress - currently being worked on
+  {
+    title: '[DEMO] Fix login timeout issue',
+    description:
+      'Users are being logged out after 5 minutes of inactivity. Investigate and increase the session timeout to 30 minutes.\n\n---\n**This is sample data** - Click the trash icon in the wizard to remove all demo items.',
+    category: 'Bug Fix',
+    status: 'in_progress',
+    priority: 1,
+    isSampleData: true,
+  },
+
+  // Waiting Approval - completed and awaiting review
+  {
+    title: '[DEMO] Update API documentation',
+    description:
+      'Update the API documentation to reflect recent endpoint changes and add examples for new authentication flow.\n\n---\n**This is sample data** - Click the trash icon in the wizard to remove all demo items.',
+    category: 'Documentation',
+    status: 'waiting_approval',
+    priority: 2,
+    isSampleData: true,
+  },
+
+  // Verified - approved and ready
+  {
+    title: '[DEMO] Add loading spinners',
+    description:
+      'Added loading spinner components to all async operations to improve user feedback during data fetching.\n\n---\n**This is sample data** - Click the trash icon in the wizard to remove all demo items.',
+    category: 'Enhancement',
+    status: 'verified',
+    priority: 3,
+    isSampleData: true,
+  },
+];
+
+/**
+ * Check if a feature is sample data
+ * Uses the SAMPLE_FEATURE_PREFIX in the title as the marker for sample data
+ */
+export function isSampleFeature(feature: Partial<Feature>): boolean {
+  // Check title prefix - this is the reliable marker that persists through the database
+  return feature.title?.startsWith(SAMPLE_FEATURE_PREFIX) ?? false;
+}
+
+/**
+ * Generate sample feature data with unique IDs
+ * @returns Array of sample features ready to be created
+ */
+export function generateSampleFeatures(): Array<Omit<Feature, 'id' | 'createdAt' | 'updatedAt'>> {
+  return SAMPLE_FEATURES.map((template) => ({
+    title: template.title,
+    description: template.description,
+    category: template.category,
+    status: template.status,
+    priority: template.priority,
+    images: [],
+    imagePaths: [],
+    skipTests: true,
+    model: 'sonnet' as const,
+    thinkingLevel: 'none' as const,
+    planningMode: 'skip' as const,
+    requirePlanApproval: false,
+    // Mark as sample data in a way that persists
+    // We use the title prefix [DEMO] as the marker
+  }));
+}

apps/ui/src/components/views/board-view/hooks/index.ts

@@ -8,3 +8,4 @@ export { useBoardBackground } from './use-board-background';
 export { useBoardPersistence } from './use-board-persistence';
 export { useFollowUpState } from './use-follow-up-state';
 export { useSelectionMode } from './use-selection-mode';
+export { useBoardOnboarding } from './use-board-onboarding';

apps/ui/src/components/views/board-view/hooks/use-board-onboarding.ts

@@ -0,0 +1,275 @@
+/**
+ * Board Onboarding Hook
+ *
+ * Board-specific wrapper around the shared onboarding wizard hook.
+ * Manages board-specific features like sample data (Quick Start).
+ *
+ * Usage:
+ * - Wizard is triggered manually via startWizard() when user clicks help button
+ * - No auto-show logic - user controls when to see the wizard
+ */
+
+import { useState, useCallback, useEffect } from 'react';
+import { createLogger } from '@automaker/utils/logger';
+import { getItem, setItem } from '@/lib/storage';
+import {
+  useOnboardingWizard,
+  ONBOARDING_TARGET_ATTRIBUTE,
+  type OnboardingStep,
+} from '@/components/shared/onboarding';
+import { PlayCircle, Sparkles, Lightbulb, CheckCircle2, Settings2 } from 'lucide-react';
+
+const logger = createLogger('BoardOnboarding');
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Storage key prefix for board-specific onboarding data */
+const BOARD_ONBOARDING_STORAGE_KEY = 'automaker:board-onboarding-data';
+
+/** Maximum length for project path hash in storage key */
+const PROJECT_PATH_HASH_MAX_LENGTH = 50;
+
+// Board-specific analytics events
+export const BOARD_ONBOARDING_ANALYTICS = {
+  QUICK_START_USED: 'board_onboarding_quick_start_used',
+  SAMPLE_DATA_CLEARED: 'board_onboarding_sample_data_cleared',
+} as const;
+
+// ============================================================================
+// WIZARD STEPS
+// ============================================================================
+
+/**
+ * Board wizard step definitions
+ * Each step targets a kanban column via data-onboarding-target
+ */
+export const BOARD_WIZARD_STEPS: OnboardingStep[] = [
+  {
+    id: 'backlog',
+    targetId: 'backlog',
+    title: 'Backlog',
+    description:
+      'This is where all your planned tasks live. Add new features, bug fixes, or improvements here. When you\'re ready to work on something, drag it to "In Progress" or click the play button.',
+    tip: 'Press N or click the + button to quickly add a new feature.',
+    icon: PlayCircle,
+  },
+  {
+    id: 'in_progress',
+    targetId: 'in_progress',
+    title: 'In Progress',
+    description:
+      'Tasks being actively worked on appear here. AI agents automatically pick up items from the backlog and move them here when processing begins.',
+    tip: 'You can run multiple tasks simultaneously using Auto Mode.',
+    icon: Sparkles,
+  },
+  {
+    id: 'waiting_approval',
+    targetId: 'waiting_approval',
+    title: 'Waiting Approval',
+    description:
+      'Completed work lands here for your review. Check the changes, run tests, and approve or send back for revisions.',
+    tip: 'Click "View Output" to see what the AI agent did.',
+    icon: Lightbulb,
+  },
+  {
+    id: 'verified',
+    targetId: 'verified',
+    title: 'Verified',
+    description:
+      "Approved and verified tasks are ready for deployment! Archive them when you're done or move them back if changes are needed.",
+    tip: 'Click "Complete All" to archive all verified items at once.',
+    icon: CheckCircle2,
+  },
+  {
+    id: 'custom_columns',
+    targetId: 'pipeline-settings', // Highlight the pipeline settings button icon
+    title: 'Custom Pipelines',
+    description:
+      'You can create custom columns (called pipelines) to build your own workflow! Click this settings icon to add, rename, or configure pipeline steps.',
+    tip: 'Use pipelines to add code review, QA testing, or any custom stage to your workflow.',
+    icon: Settings2,
+  },
+];
+
+// Re-export for backward compatibility
+export type { OnboardingStep as WizardStep } from '@/components/shared/onboarding';
+export { ONBOARDING_TARGET_ATTRIBUTE };
+
+// ============================================================================
+// BOARD-SPECIFIC STATE
+// ============================================================================
+
+interface BoardOnboardingData {
+  hasSampleData: boolean;
+  quickStartUsed: boolean;
+}
+
+const DEFAULT_BOARD_DATA: BoardOnboardingData = {
+  hasSampleData: false,
+  quickStartUsed: false,
+};
+
+/**
+ * Sanitize project path to create a storage key
+ */
+function sanitizeProjectPath(projectPath: string): string {
+  return projectPath.replace(/[^a-zA-Z0-9]/g, '_').slice(0, PROJECT_PATH_HASH_MAX_LENGTH);
+}
+
+/**
+ * Get storage key for board-specific data
+ */
+function getBoardDataStorageKey(projectPath: string): string {
+  const hash = sanitizeProjectPath(projectPath);
+  return `${BOARD_ONBOARDING_STORAGE_KEY}:${hash}`;
+}
+
+/**
+ * Load board-specific onboarding data from localStorage
+ */
+function loadBoardData(projectPath: string): BoardOnboardingData {
+  try {
+    const key = getBoardDataStorageKey(projectPath);
+    const stored = getItem(key);
+    if (stored) {
+      return JSON.parse(stored) as BoardOnboardingData;
+    }
+  } catch (error) {
+    logger.error('Failed to load board onboarding data:', error);
+  }
+  return { ...DEFAULT_BOARD_DATA };
+}
+
+/**
+ * Save board-specific onboarding data to localStorage
+ */
+function saveBoardData(projectPath: string, data: BoardOnboardingData): void {
+  try {
+    const key = getBoardDataStorageKey(projectPath);
+    setItem(key, JSON.stringify(data));
+  } catch (error) {
+    logger.error('Failed to save board onboarding data:', error);
+  }
+}
+
+/**
+ * Track analytics event (placeholder)
+ */
+function trackAnalytics(event: string, data?: Record<string, unknown>): void {
+  logger.debug(`[Analytics] ${event}`, data);
+}
+
+// ============================================================================
+// HOOK
+// ============================================================================
+
+export interface UseBoardOnboardingOptions {
+  projectPath: string | null;
+}
+
+export interface UseBoardOnboardingResult {
+  // From shared wizard hook
+  isWizardVisible: boolean;
+  currentStep: number;
+  currentStepData: OnboardingStep | null;
+  totalSteps: number;
+  goToNextStep: () => void;
+  goToPreviousStep: () => void;
+  goToStep: (step: number) => void;
+  startWizard: () => void;
+  completeWizard: () => void;
+  skipWizard: () => void;
+  isCompleted: boolean;
+  isSkipped: boolean;
+
+  // Board-specific
+  hasSampleData: boolean;
+  setHasSampleData: (has: boolean) => void;
+  markQuickStartUsed: () => void;
+
+  // Steps data for component
+  steps: OnboardingStep[];
+}
+
+export function useBoardOnboarding({
+  projectPath,
+}: UseBoardOnboardingOptions): UseBoardOnboardingResult {
+  // Board-specific state for sample data
+  const [boardData, setBoardData] = useState<BoardOnboardingData>(DEFAULT_BOARD_DATA);
+
+  // Create storage key from project path
+  const storageKey = projectPath ? `board:${sanitizeProjectPath(projectPath)}` : 'board:default';
+
+  // Use the shared onboarding wizard hook
+  const wizard = useOnboardingWizard({
+    storageKey,
+    steps: BOARD_WIZARD_STEPS,
+  });
+
+  // Load board-specific data when project changes
+  useEffect(() => {
+    if (!projectPath) {
+      setBoardData(DEFAULT_BOARD_DATA);
+      return;
+    }
+
+    const data = loadBoardData(projectPath);
+    setBoardData(data);
+  }, [projectPath]);
+
+  // Update board data helper
+  const updateBoardData = useCallback(
+    (updates: Partial<BoardOnboardingData>) => {
+      if (!projectPath) return;
+
+      setBoardData((prev) => {
+        const newData = { ...prev, ...updates };
+        saveBoardData(projectPath, newData);
+        return newData;
+      });
+    },
+    [projectPath]
+  );
+
+  // Sample data handlers
+  const setHasSampleData = useCallback(
+    (has: boolean) => {
+      updateBoardData({ hasSampleData: has });
+      if (!has) {
+        trackAnalytics(BOARD_ONBOARDING_ANALYTICS.SAMPLE_DATA_CLEARED, { projectPath });
+      }
+    },
+    [projectPath, updateBoardData]
+  );
+
+  const markQuickStartUsed = useCallback(() => {
+    updateBoardData({ quickStartUsed: true, hasSampleData: true });
+    trackAnalytics(BOARD_ONBOARDING_ANALYTICS.QUICK_START_USED, { projectPath });
+  }, [projectPath, updateBoardData]);
+
+  return {
+    // Spread shared wizard state and actions
+    isWizardVisible: wizard.isVisible,
+    currentStep: wizard.currentStep,
+    currentStepData: wizard.currentStepData,
+    totalSteps: wizard.totalSteps,
+    goToNextStep: wizard.goToNextStep,
+    goToPreviousStep: wizard.goToPreviousStep,
+    goToStep: wizard.goToStep,
+    startWizard: wizard.startWizard,
+    completeWizard: wizard.completeWizard,
+    skipWizard: wizard.skipWizard,
+    isCompleted: wizard.isCompleted,
+    isSkipped: wizard.isSkipped,
+
+    // Board-specific
+    hasSampleData: boardData.hasSampleData,
+    setHasSampleData,
+    markQuickStartUsed,
+
+    // Steps data
+    steps: BOARD_WIZARD_STEPS,
+  };
+}

apps/ui/src/components/views/board-view/kanban-board.tsx

@@ -173,6 +173,7 @@ export function KanbanBoard({
                       onClick={onOpenPipelineSettings}
                       title="Pipeline Settings"
                       data-testid="pipeline-settings-button"
+                      data-onboarding-target="pipeline-settings"
                     >
                       <Settings2 className="w-3.5 h-3.5" />
                     </Button>