Bugfix: Defer AI offer toast until onboarding ends

- Suppress the AI offer toast during the FDA onboarding modal so it doesn't pile on top of the prompt. Usability tests showed the two firing together overwhelmed users.
- Mirror the updater's onboarded gate: `initAiState` seeds `aiState.onboarded` from `loadSettings().isOnboarded`, keeps an `Offer` status `hidden` while not onboarded, and remembers `pendingOffer` for later.
- New `notifyAiOnboardingComplete()` is called from `+page.svelte`'s `handleFdaComplete()` (Allow + Deny paths) and from the two legacy fallbacks for users who already had FDA or denied before the `isOnboarded` flag existed.
- Sticky merge in the seed (`aiState.onboarded || settings.isOnboarded`) keeps the gate open if the hook fires before `loadSettings()` resolves on the legacy paths.
- Tests cover suppress-when-not-onboarded, surface-on-init, surface-via-hook, no-op without pending offer, idempotent across dismiss, install events flowing through, and the race regression.

Author: vdavid

apps/desktop/src/lib/ai/AiNotification.test.ts

@@ -28,6 +28,8 @@ let mockState = {
     baseOverheadBytes: 3500000000,
   },
   downloadToastUserDismissed: false,
+  onboarded: true,
+  pendingOffer: false,
 }
 
 function mountToast() {
@@ -52,6 +54,8 @@ describe('AiToastContent', () => {
         baseOverheadBytes: 3500000000,
       },
       downloadToastUserDismissed: false,
+      onboarded: true,
+      pendingOffer: false,
     }
     vi.mocked(getAiState).mockReturnValue(mockState)
   })

apps/desktop/src/lib/ai/CLAUDE.md

@@ -31,6 +31,21 @@ Settings `ai.provider`, `ai.openaiApiKey`, `ai.openaiBaseUrl`, `ai.openaiModel`,
 `settings-registry.ts`. The main layout calls `configureAi(...)` after `initSettingsApplier()` to push config to
 backend.
 
+### Onboarding gate suppresses the offer toast
+
+While first-launch onboarding (the FDA prompt) is on screen, the AI offer toast is suppressed so it doesn't pile on top
+of the modal. `initAiState()` seeds `aiState.onboarded` from `loadSettings().isOnboarded`. When the backend reports
+`Offer` and `onboarded === false`, `updateNotificationFromStatus()` keeps `notificationState = 'hidden'` and sets
+`aiState.pendingOffer = true`.
+
+`notifyAiOnboardingComplete()` is called from `routes/(main)/+page.svelte` whenever the FDA prompt closes (Allow or Deny
+path) or for legacy users who never saw the prompt. It flips `onboarded` and, if `pendingOffer` is true, surfaces the
+offer right then. The Allow path also restarts the app — on next launch `isOnboarded` is already true so the gate
+doesn't engage at all.
+
+This mirrors the updater module's pattern in `$lib/updates/updater.svelte.ts` (`onboarded` + `notifyOnboardingComplete`)
+— same gate, same opening event, two independent toasts.
+
 ### 7-day dismissal, permanent opt-out
 
 "Not now" hides offer for 7 days (`dismissedUntil` timestamp in state). "I don't want AI" sets `opted_out: true`

apps/desktop/src/lib/ai/ai-state.svelte.ts

@@ -13,6 +13,7 @@ import {
   type AiStatus,
 } from '$lib/tauri-commands'
 import { getSetting, setSetting } from '$lib/settings'
+import { loadSettings } from '$lib/settings-store'
 
 type AiNotificationState = 'hidden' | 'offer' | 'downloading' | 'installing' | 'ready' | 'starting'
 
@@ -27,6 +28,19 @@ interface AiStateData {
    * flag resets whenever a new download run starts (on transition into `'downloading'`).
    */
   downloadToastUserDismissed: boolean
+  /**
+   * True once first-launch onboarding (FDA prompt) has finished. While false, an `Offer` status
+   * from the backend is suppressed so the AI toast doesn't pile on top of the FDA modal. Seeded
+   * from `loadSettings().isOnboarded` in `initAiState`; flipped by `notifyAiOnboardingComplete`.
+   */
+  onboarded: boolean
+  /**
+   * True when the backend reported `Offer` but the toast was suppressed because onboarding wasn't
+   * complete. `notifyAiOnboardingComplete` reads this to surface the offer once the gate opens.
+   * Cleared by user-driven exits from the offer (`dismiss`, `optOut`, `download`) so the gate
+   * doesn't resurrect a decision the user has already made.
+   */
+  pendingOffer: boolean
 }
 
 const aiState = $state<AiStateData>({
@@ -35,6 +49,8 @@ const aiState = $state<AiStateData>({
   progressText: '',
   modelInfo: null,
   downloadToastUserDismissed: false,
+  onboarded: false,
+  pendingOffer: false,
 })
 
 export function getAiState(): AiStateData {
@@ -48,6 +64,8 @@ export function resetForTesting(): void {
   aiState.progressText = ''
   aiState.modelInfo = null
   aiState.downloadToastUserDismissed = false
+  aiState.onboarded = false
+  aiState.pendingOffer = false
 }
 
 /** Marks the downloading toast as user-dismissed for the current download run. */
@@ -62,6 +80,17 @@ export async function initAiState(): Promise<() => void> {
     return () => {}
   }
 
+  // Seed the onboarded gate from persisted settings. While `false`, an Offer status stays
+  // hidden — the FDA modal owns the screen during first launch. Returning users (isOnboarded
+  // already true) skip the gate entirely.
+  //
+  // Sticky merge instead of plain assignment: `+page.svelte` may have already called
+  // `notifyAiOnboardingComplete()` while `loadSettings()` was in flight (legacy fallback paths
+  // run no user input gate). A plain assignment would overwrite the hook's `true` back to a
+  // stale `false` if disk hadn't synced yet.
+  const settings = await loadSettings()
+  aiState.onboarded = aiState.onboarded || settings.isOnboarded
+
   // Fetch model info and status in parallel
   const [status, modelInfo] = await Promise.all([getAiStatus(), getAiModelInfo()])
   aiState.modelInfo = modelInfo
@@ -143,13 +172,37 @@ function updateNotificationFromStatus(status: AiStatus): void {
       aiState.notificationState = 'hidden' // Already installed, don't show anything
       break
     case 'offer':
-      aiState.notificationState = 'offer'
+      // Suppress the offer until first-launch onboarding is done. The pending flag lets
+      // `notifyAiOnboardingComplete` surface it the moment the gate opens.
+      if (aiState.onboarded) {
+        aiState.notificationState = 'offer'
+        aiState.pendingOffer = false
+      } else {
+        aiState.notificationState = 'hidden'
+        aiState.pendingOffer = true
+      }
       break
     default:
       aiState.notificationState = 'hidden'
   }
 }
 
+/**
+ * Marks first-launch onboarding as complete so a deferred AI offer can finally surface.
+ * Called from `routes/(main)/+page.svelte` once the FDA prompt closes (Allow or Deny path).
+ *
+ * The Allow path lands on `isOnboarded: true` via `notifyOnboardingComplete()`, so the next
+ * launch reads onboarded=true and skips the gate entirely. The Deny path needs this hook to
+ * reveal the offer in the same session.
+ */
+export function notifyAiOnboardingComplete(): void {
+  aiState.onboarded = true
+  if (aiState.pendingOffer) {
+    aiState.notificationState = 'offer'
+    aiState.pendingOffer = false
+  }
+}
+
 function formatProgressText(progress: AiDownloadProgress): string {
   if (progress.totalBytes === 0) return 'Starting download...'
   const percent = Math.round((progress.bytesDownloaded / progress.totalBytes) * 100)

apps/desktop/src/lib/ai/ai-state.test.ts

@@ -15,14 +15,20 @@ vi.mock('$lib/tauri-commands', async () => {
   }
 })
 
+vi.mock('$lib/settings-store', () => ({
+  loadSettings: vi.fn(),
+}))
+
 import { getAiStatus, getAiModelInfo, startAiDownload, cancelAiDownload, dismissAiOffer } from '$lib/tauri-commands'
+import { loadSettings } from '$lib/settings-store'
 import {
   getAiState,
   initAiState,
   handleDownload,
   handleCancel,
   handleDismiss,
   handleGotIt,
+  notifyAiOnboardingComplete,
   resetForTesting,
 } from './ai-state.svelte'
 
@@ -35,10 +41,24 @@ const mockModelInfo = {
   baseOverheadBytes: 3500000000,
 }
 
+const ONBOARDED = {
+  showHiddenFiles: true,
+  fullDiskAccessChoice: 'allow' as const,
+  isOnboarded: true,
+}
+
+const NOT_ONBOARDED = {
+  showHiddenFiles: true,
+  fullDiskAccessChoice: 'notAskedYet' as const,
+  isOnboarded: false,
+}
+
 describe('ai-state', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     resetForTesting()
+    // Default: existing tests assume the user is past onboarding so the offer surfaces.
+    vi.mocked(loadSettings).mockResolvedValue(ONBOARDED)
   })
 
   describe('getAiState', () => {
@@ -266,4 +286,140 @@ describe('ai-state', () => {
       expect(state.downloadProgress).toBeNull()
     })
   })
+
+  describe('onboarding gate', () => {
+    it('suppresses Offer when isOnboarded is false', async () => {
+      vi.mocked(loadSettings).mockResolvedValue(NOT_ONBOARDED)
+      vi.mocked(getAiStatus).mockResolvedValue('offer')
+      vi.mocked(getAiModelInfo).mockResolvedValue(mockModelInfo)
+
+      await initAiState()
+
+      const state = getAiState()
+      expect(state.notificationState).toBe('hidden')
+      expect(state.pendingOffer).toBe(true)
+      expect(state.onboarded).toBe(false)
+    })
+
+    it('surfaces Offer immediately when isOnboarded is true at init', async () => {
+      vi.mocked(loadSettings).mockResolvedValue(ONBOARDED)
+      vi.mocked(getAiStatus).mockResolvedValue('offer')
+      vi.mocked(getAiModelInfo).mockResolvedValue(mockModelInfo)
+
+      await initAiState()
+
+      const state = getAiState()
+      expect(state.notificationState).toBe('offer')
+      expect(state.pendingOffer).toBe(false)
+      expect(state.onboarded).toBe(true)
+    })
+
+    it('surfaces a deferred Offer when notifyAiOnboardingComplete is called', async () => {
+      vi.mocked(loadSettings).mockResolvedValue(NOT_ONBOARDED)
+      vi.mocked(getAiStatus).mockResolvedValue('offer')
+      vi.mocked(getAiModelInfo).mockResolvedValue(mockModelInfo)
+
+      await initAiState()
+      expect(getAiState().notificationState).toBe('hidden')
+
+      notifyAiOnboardingComplete()
+
+      const state = getAiState()
+      expect(state.notificationState).toBe('offer')
+      expect(state.pendingOffer).toBe(false)
+      expect(state.onboarded).toBe(true)
+    })
+
+    it('does not flip state to Offer when there is no pending offer', async () => {
+      // Backend says Available — model already installed, no offer to surface.
+      vi.mocked(loadSettings).mockResolvedValue(NOT_ONBOARDED)
+      vi.mocked(getAiStatus).mockResolvedValue('available')
+      vi.mocked(getAiModelInfo).mockResolvedValue(mockModelInfo)
+
+      await initAiState()
+      expect(getAiState().notificationState).toBe('hidden')
+
+      notifyAiOnboardingComplete()
+
+      const state = getAiState()
+      expect(state.notificationState).toBe('hidden')
+      expect(state.onboarded).toBe(true)
+    })
+
+    it('is idempotent — second call does not re-trigger the offer', async () => {
+      vi.mocked(loadSettings).mockResolvedValue(NOT_ONBOARDED)
+      vi.mocked(getAiStatus).mockResolvedValue('offer')
+      vi.mocked(getAiModelInfo).mockResolvedValue(mockModelInfo)
+
+      await initAiState()
+      notifyAiOnboardingComplete()
+      // User dismisses the offer.
+      vi.mocked(dismissAiOffer).mockResolvedValue(undefined)
+      await handleDismiss()
+      expect(getAiState().notificationState).toBe('hidden')
+
+      // A second onboarding-complete signal must NOT resurrect the dismissed offer.
+      notifyAiOnboardingComplete()
+
+      expect(getAiState().notificationState).toBe('hidden')
+    })
+
+    it('does not regress onboarded=true if notifyAiOnboardingComplete fires while loadSettings is in flight', async () => {
+      // Race: legacy fallback paths in `+page.svelte` (hasFda + !isOnboarded, deny + !isOnboarded)
+      // call `notifyAiOnboardingComplete()` without any user gate. If `initAiState` is still
+      // awaiting `loadSettings()` when that hook fires — and disk hasn't synced the
+      // `notifyOnboardingComplete()` save yet — a plain assignment in initAiState would clobber
+      // the hook's `onboarded = true` back to a stale `false`, leaving the offer permanently gated.
+      let resolveSettings: ((value: typeof NOT_ONBOARDED) => void) | undefined
+      vi.mocked(loadSettings).mockImplementation(
+        () =>
+          new Promise<typeof NOT_ONBOARDED>((resolve) => {
+            resolveSettings = resolve
+          }),
+      )
+      vi.mocked(getAiStatus).mockResolvedValue('offer')
+      vi.mocked(getAiModelInfo).mockResolvedValue(mockModelInfo)
+
+      const initPromise = initAiState()
+
+      // Simulate the legacy fallback firing the hook before loadSettings resolves.
+      notifyAiOnboardingComplete()
+      expect(getAiState().onboarded).toBe(true)
+
+      // Now resolve loadSettings with stale `isOnboarded: false` (disk not yet synced).
+      resolveSettings?.(NOT_ONBOARDED)
+      await initPromise
+
+      const state = getAiState()
+      expect(state.onboarded).toBe(true)
+      // Status is `offer` and onboarded is sticky-true, so the offer surfaces directly.
+      expect(state.notificationState).toBe('offer')
+      expect(state.pendingOffer).toBe(false)
+    })
+
+    it('does not gate downloading state — install events flow through even when not onboarded', async () => {
+      // Edge case: user starts onboarding, app keeps running, backend somehow emits installing/ready.
+      // The gate only suppresses the initial Offer, not in-flight install signals (which can only
+      // arise after the user accepted the offer somewhere).
+      vi.mocked(loadSettings).mockResolvedValue(NOT_ONBOARDED)
+      vi.mocked(getAiStatus).mockResolvedValue('offer')
+      vi.mocked(getAiModelInfo).mockResolvedValue(mockModelInfo)
+      let installingCallback: (() => void) | undefined
+      let completeCallback: (() => void) | undefined
+      vi.mocked(listen).mockImplementation((event, callback) => {
+        if (event === 'ai-installing') installingCallback = callback as () => void
+        if (event === 'ai-install-complete') completeCallback = callback as () => void
+        return Promise.resolve(() => {})
+      })
+
+      await initAiState()
+      expect(getAiState().notificationState).toBe('hidden')
+
+      installingCallback?.()
+      expect(getAiState().notificationState).toBe('installing')
+
+      completeCallback?.()
+      expect(getAiState().notificationState).toBe('ready')
+    })
+  })
 })

apps/desktop/src/routes/(main)/+page.svelte

@@ -28,6 +28,7 @@
     import { SOFT_DIALOG_REGISTRY } from '$lib/ui/dialog-registry'
     import { loadSettings, saveSettings } from '$lib/settings-store'
     import { notifyOnboardingComplete, setFdaPromptShowing } from '$lib/updates/updater.svelte'
+    import { notifyAiOnboardingComplete } from '$lib/ai/ai-state.svelte'
     import { openSettingsWindow } from '$lib/settings/settings-window'
     import { openFileViewer } from '$lib/file-viewer/open-viewer'
     import {
@@ -401,6 +402,7 @@
             // not yet flagged as onboarded, mark them so now (and unblock the update toast).
             if (!settings.isOnboarded) {
                 await notifyOnboardingComplete()
+                notifyAiOnboardingComplete()
             }
             showApp = true
         } else if (settings.fullDiskAccessChoice === 'notAskedYet') {
@@ -413,7 +415,13 @@
             fdaWasRevoked = true
             setFdaPromptShowing(true)
         } else {
-            // User explicitly denied - proceed without prompting
+            // User explicitly denied - proceed without prompting. Cover legacy users who denied
+            // before the `isOnboarded` flag existed so the AI offer (and update toast) aren't
+            // permanently gated.
+            if (!settings.isOnboarded) {
+                await notifyOnboardingComplete()
+                notifyAiOnboardingComplete()
+            }
             showApp = true
         }
 
@@ -488,6 +496,9 @@
         // Mark onboarding as complete and (if an update is already ready) trigger the deferred toast.
         // notifyOnboardingComplete persists `isOnboarded: true` itself — no double-save needed.
         void notifyOnboardingComplete()
+        // Surface a deferred AI offer too. Same gate, same opening event — without this, the offer
+        // would only show on next launch, even on the Deny path where the user stays in the session.
+        notifyAiOnboardingComplete()
     }
 
     function handleExpirationModalClose() {