<!-- source-hash: 7a7aa5f6a5049b0fd0108b153da19ff8 -->
Orchestrates a multi-step onboarding walkthrough UI, managing step completion state, skip/dismiss interactions, and syncing external completion checks to persistent localStorage state.

## Key Components

### `OnboardingWalkthrough` (default export)
Main component that renders a header with dismiss/close controls and a list of `OnboardingStepCard` items.

### `OnboardingWalkthroughProps`
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `steps` | `OnboardingStepConfig[]` | — | Step definitions to render |
| `onDismiss` | `() => void` | — | Callback fired after dismissal |
| `storageKey` | `string` | `'openframe-onboarding-state'` | localStorage key for persisted state |
| `completionStatus` | `Record<string, boolean>` | — | External hook-driven completion map |
| `isLoadingCompletion` | `boolean` | `false` | Suppresses auto-marking while checks are in flight |
| `className` / `spacing` | `string` | — | Layout overrides |

### Internal Behaviors
- **Auto-sync** (`useEffect`): Detects changes in `completionStatus` and bulk-marks newly completed steps via `markMultipleComplete`, guarded by refs to prevent race conditions.
- **`handleStepAction`** (`useCallback`): Runs `step.onAction()`, then optionally calls `step.checkComplete()` to verify and mark completion; `knowledge-base` steps are auto-completed without verification.
- **`handleStepSkip`** / **`handleDismiss`**: Delegate to `useOnboardingState` and fire optional callbacks.

## Usage Example

```typescript
import { OnboardingWalkthrough } from './onboarding-walkthrough'
import { useOnboardingCompletion } from '../../../hooks/ui/use-onboarding-completion'

const steps = [
  {
    id: 'knowledge-base',
    title: 'Add Knowledge Base',
    description: 'Upload your docs.',
    onAction: async () => router.push('/knowledge'),
  },
  {
    id: 'connect-psa',
    title: 'Connect PSA',
    description: 'Link your ticketing system.',
    onAction: async () => router.push('/integrations'),
    checkComplete: async () => !!(await fetchPsaStatus()),
    onSkip: () => console.log('PSA skipped'),
  },
]

function Dashboard() {
  const { completionStatus, isLoading } = useOnboardingCompletion()

  return (
    <OnboardingWalkthrough
      steps={steps}
      completionStatus={completionStatus}
      isLoadingCompletion={isLoading}
      onDismiss={() => console.log('dismissed')}
    />
  )
}
```

> **Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/onboarding-walkthrough.tsx)