VErsion 1.3.2

docs/30-FRONTEND/STORES.md

@@ -1,7 +1,7 @@
 # Zustand State Management
 
-**Last Verified:** December 27, 2025  
-**Version:** 1.2.0  
+**Last Verified:** January 3, 2026  
+**Version:** 1.3.2  
 **Framework:** Zustand 4 with persist middleware
 
 ---
@@ -15,6 +15,19 @@ All stores in `/frontend/src/store/` use Zustand with TypeScript.
 - Async actions for API calls
 - Selectors for derived state
 
+**Available Stores:**
+- `authStore.ts` - Authentication state
+- `siteStore.ts` - Site selection/management
+- `sectorStore.ts` - Sector management
+- `plannerStore.ts` - Planner module state
+- `billingStore.ts` - Billing/credits
+- `notificationStore.ts` - Notifications
+- `settingsStore.ts` - User preferences
+- `moduleStore.ts` - Module navigation
+- `columnVisibilityStore.ts` - Table column prefs
+- `pageSizeStore.ts` - Table pagination prefs
+- **`onboardingStore.ts`** - Onboarding wizard state (v1.3.2)
+
 ---
 
 ## Auth Store (`authStore.ts`)
@@ -408,11 +421,57 @@ notificationStore (global, polls/syncs independently)
 
 moduleStore (global, loads once per account)
 billingStore (global, loads once per account)
+onboardingStore (global, syncs with UserSettings backend)
 uiStore (local only, no API)
 ```
 
 ---
 
+## Onboarding Store (`onboardingStore.ts`) (v1.3.2)
+
+**Purpose:** Manages onboarding wizard and guide screen state
+
+```typescript
+interface OnboardingState {
+  isGuideDismissed: boolean;
+  isGuideVisible: boolean;
+  isLoading: boolean;
+  lastSyncedAt: Date | null;
+}
+
+interface OnboardingActions {
+  dismissGuide(): Promise<void>;
+  showGuide(): void;
+  toggleGuide(): void;
+  loadFromBackend(): Promise<void>;
+  syncToBackend(dismissed: boolean): Promise<void>;
+}
+```
+
+**Persistence:** 
+- Local: `onboarding-storage` in localStorage
+- Backend: `UserSettings` with key `workflow_guide_dismissed`
+
+**Features:**
+- Cross-device sync via backend UserSettings
+- Rate-limited sync (max every 5 minutes)
+- Graceful fallback if backend unavailable
+
+**Usage:**
+```typescript
+const { isGuideVisible, dismissGuide, showGuide } = useOnboardingStore();
+
+// Show onboarding wizard
+if (isGuideVisible) {
+  return <OnboardingWizard onDismiss={dismissGuide} />;
+}
+
+// Re-show guide button
+<Button onClick={showGuide}>Show Guide</Button>
+```
+
+---
+
 ## Store Files Location
 
 ```