Onboarding: Postpone update toast until onboarding finishes

- Add `isOnboarded` boolean to `Settings` (default `false`), persisted via the existing settings store.
- Gate the "update ready" toast in `updater.svelte.ts` on a pure `shouldShowUpdateToast({ onboarded, fdaPromptShowing, status })` predicate. Helper `showUpdateToast()` replaces the two direct `addToast` calls.
- Export `notifyOnboardingComplete()` and `setFdaPromptShowing(value)` for the route to drive. Re-attempts the toast when either gate opens.
- Wire `+page.svelte`: `setFdaPromptShowing(true|false)` around `FullDiskAccessPrompt` (first-run AND `wasRevoked`), `notifyOnboardingComplete()` in `handleFdaComplete()` and the legacy `hasFda === true` branch (covers users who granted FDA before this flag existed).
- Seed `onboarded` from `loadSettings().isOnboarded` on `startUpdateChecker()` start so returning users aren't gated.
- Drop stale "skips in dev mode" comment in `+layout.svelte` (the updater has no dev guard; the CI skip is in Rust).
- Add `updater.test.ts` covering the truth table and both trigger paths (15 tests).
- Update `updates/CLAUDE.md` and `onboarding/CLAUDE.md`.

Author: vdavid

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

@@ -30,6 +30,23 @@ The `wasRevoked` prop switches the copy from "first ask" to "revoked" framing.
    - `'allow'` (but FDA revoked) → show prompt with "revoked" framing.
    - `'deny'` → skip (user previously declined).
 
+## Onboarding flag and deferred update toast
+
+A separate `isOnboarded` boolean lives in `$lib/settings-store.ts` (default `false`). It exists so the auto-update
+"restart to apply" toast doesn't fire during first-launch onboarding (the user just downloaded the app — they'd be
+confused) nor stack on top of the FDA-revoked re-prompt.
+
+`+page.svelte` calls `notifyOnboardingComplete()` from `$lib/updates/updater.svelte` in two places:
+
+- `handleFdaComplete()` — fires whichever way the FDA prompt closes (Allow → restart hint, Deny → setting saved). The
+  helper persists `isOnboarded: true` itself, so the page doesn't double-save.
+- The `hasFda === true` branch — covers users who granted FDA before the flag existed. If `!settings.isOnboarded`, call
+  the helper so they get unblocked too.
+
+Around the same place where `showFdaPrompt = true` is set (both first-run and `wasRevoked`), `+page.svelte` also calls
+`setFdaPromptShowing(true)` so the updater suppresses the toast while the modal is up. `handleFdaComplete()` flips it
+back with `setFdaPromptShowing(false)`. See `$lib/updates/CLAUDE.md` § "Onboarding gating" for the updater side.
+
 ## Key decisions
 
 **Decision**: Three-state setting (`notAskedYet` / `allow` / `deny`) instead of a boolean. **Why**: The app needs to

apps/desktop/src/lib/settings-store.ts

@@ -11,11 +11,13 @@ export type FullDiskAccessChoice = 'allow' | 'deny' | 'notAskedYet'
 export interface Settings {
   showHiddenFiles: boolean
   fullDiskAccessChoice: FullDiskAccessChoice
+  isOnboarded: boolean
 }
 
 const DEFAULT_SETTINGS: Settings = {
   showHiddenFiles: true,
   fullDiskAccessChoice: 'notAskedYet',
+  isOnboarded: false,
 }
 
 let storeInstance: Store | null = null
@@ -36,13 +38,15 @@ export async function loadSettings(): Promise<Settings> {
     const store = await getStore()
     const showHiddenFiles = await store.get('showHiddenFiles')
     const fullDiskAccessChoice = await store.get('fullDiskAccessChoice')
+    const isOnboarded = await store.get('isOnboarded')
 
     const validChoices: FullDiskAccessChoice[] = ['allow', 'deny', 'notAskedYet']
     return {
       showHiddenFiles: typeof showHiddenFiles === 'boolean' ? showHiddenFiles : DEFAULT_SETTINGS.showHiddenFiles,
       fullDiskAccessChoice: validChoices.includes(fullDiskAccessChoice as FullDiskAccessChoice)
         ? (fullDiskAccessChoice as FullDiskAccessChoice)
         : DEFAULT_SETTINGS.fullDiskAccessChoice,
+      isOnboarded: typeof isOnboarded === 'boolean' ? isOnboarded : DEFAULT_SETTINGS.isOnboarded,
     }
   } catch {
     // If store fails, return defaults
@@ -62,6 +66,9 @@ export async function saveSettings(settings: Partial<Settings>): Promise<void> {
     if (settings.fullDiskAccessChoice !== undefined) {
       await store.set('fullDiskAccessChoice', settings.fullDiskAccessChoice)
     }
+    if (settings.isOnboarded !== undefined) {
+      await store.set('isOnboarded', settings.isOnboarded)
+    }
     await store.save()
   } catch {
     // Silently fail - persistence is nice-to-have

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

@@ -37,12 +37,31 @@ The frontend branches on platform at the top of `checkForUpdates()`:
 - **Non-macOS**: dynamically imports `@tauri-apps/plugin-updater` and calls `check()` / `downloadAndInstall()`. The
   custom updater Rust module is not compiled on these platforms.
 
-When `status` becomes `'ready'`, the updater calls
-`addToast(UpdateToastContent, { id: 'update', dismissal: 'persistent' })` to show the restart prompt via the global
-toast system. `UpdateToastContent.svelte` renders the toast body, calls `relaunch()` directly from
+When `status` becomes `'ready'`, the updater funnels through the `showUpdateToast()` helper instead of calling
+`addToast` directly. The helper consults `shouldShowUpdateToast({ onboarded, fdaPromptShowing, status })` — a pure,
+unit-tested predicate — and only fires `addToast(UpdateToastContent, { id: 'update', dismissal: 'persistent' })` when
+all three conditions hold. `UpdateToastContent.svelte` renders the toast body, calls `relaunch()` directly from
 `@tauri-apps/plugin-process` for the restart action, and handles the "Later" button by calling `dismissToast('update')`.
 There is no local `$state` dismissed flag — dismissal is managed entirely by the toast infrastructure.
 
+### Onboarding gating
+
+The toast must NOT show during first-launch onboarding (the user just downloaded the app — telling them to "restart to
+update" is confusing) nor while the FDA-revoked re-prompt is on screen (it'd stack two prompts). Two module-level
+`$state` flags drive this:
+
+- `onboarded` — seeded from `loadSettings().isOnboarded` on `startUpdateChecker()` start, then flipped by
+  `notifyOnboardingComplete()` (also persists `isOnboarded: true`).
+- `fdaPromptShowing` — flipped by `setFdaPromptShowing(value)` from `routes/(main)/+page.svelte` whenever the
+  `FullDiskAccessPrompt` opens or closes (any reason — first-run OR `wasRevoked`).
+
+When a gate opens (`notifyOnboardingComplete()` runs, or `setFdaPromptShowing(false)` flips), the helper re-attempts the
+toast. If the download completed during onboarding, `updateState.status` stays `'ready'` and the toast shows on unblock
+— nothing is lost.
+
+Two test-only hooks (`_resetUpdaterStateForTest`, `_setUpdateStatusForTest`) exist for the unit tests in
+`updater.test.ts`. Production code must not call them.
+
 ## Key decisions
 
 **Decision**: Platform branching in the frontend (`navigator.platform` check). **Why**: The custom updater Rust module
@@ -75,7 +94,9 @@ interval is acceptable.
 - The `check_for_update` command returns `None` when `CI` env var is set — no network calls in CI.
 - No retry or backoff on error — the next interval fires a fresh attempt.
 - Default interval: 60 minutes. Configurable in settings from 5 minutes to 24 hours.
-- No tests exist — the module has hard dependencies on Tauri commands and the network.
+- Unit tests in `updater.test.ts` cover the gating logic via the pure `shouldShowUpdateToast` predicate plus the
+  `notifyOnboardingComplete` and `setFdaPromptShowing` triggers. The download-and-install path is still untested — it
+  has hard Tauri/network dependencies.
 - Cleanup is mandatory: the return value of `startUpdateChecker()` must be called in `onDestroy`.
 
 ## Dependencies
@@ -85,4 +106,5 @@ interval is acceptable.
 - `@tauri-apps/plugin-process` — `relaunch()`
 - `@tauri-apps/api/app` — `getVersion()`
 - `$lib/settings/settings-store` — `getSetting`, `onSpecificSettingChange`
+- `$lib/settings-store` — `loadSettings`, `saveSettings` (for the `isOnboarded` flag)
 - `$lib/logging/logger` — `getAppLogger` (logs via unified LogTape bridge)

apps/desktop/src/lib/updates/updater.svelte.ts

@@ -4,6 +4,7 @@ import { getSetting, onSpecificSettingChange } from '$lib/settings/settings-stor
 import { getAppLogger } from '$lib/logging/logger'
 import UpdateToastContent from './UpdateToastContent.svelte'
 import { addToast } from '$lib/ui/toast'
+import { loadSettings, saveSettings } from '$lib/settings-store'
 
 const log = getAppLogger('updater')
 
@@ -33,6 +34,58 @@ const updateState = $state<UpdateState>({
   error: null,
 })
 
+// Module-level gating flags. The toast for "update ready, restart now" must NOT show during onboarding
+// (the user just downloaded the app — they'd be confused) nor while the FDA-revoked re-prompt is on screen.
+let onboarded = $state(false)
+let fdaPromptShowing = $state(false)
+
+/**
+ * Pure predicate for whether the "update ready" toast should show right now.
+ * Exported for unit testing the truth table.
+ */
+export function shouldShowUpdateToast(args: {
+  onboarded: boolean
+  fdaPromptShowing: boolean
+  status: UpdateState['status']
+}): boolean {
+  return args.onboarded && !args.fdaPromptShowing && args.status === 'ready'
+}
+
+/**
+ * Show the update-ready toast, but only if gating allows. Called from the download-complete branches
+ * and from the onboarding/FDA hooks below. When suppressed, we leave `updateState.status === 'ready'`
+ * so the download stays applied — the toast just doesn't render until the gate opens.
+ */
+function showUpdateToast(): void {
+  if (!shouldShowUpdateToast({ onboarded, fdaPromptShowing, status: updateState.status })) {
+    return
+  }
+  addToast(UpdateToastContent, { id: 'update', dismissal: 'persistent' })
+}
+
+/**
+ * Mark onboarding as complete. Persists the flag and, if an update is already ready, shows the toast.
+ * Called by the parent route once FDA onboarding finishes (either Allow or Deny path) or for users
+ * who already had FDA granted before this flag existed.
+ */
+export async function notifyOnboardingComplete(): Promise<void> {
+  onboarded = true
+  await saveSettings({ isOnboarded: true })
+  showUpdateToast()
+}
+
+/**
+ * Track whether the FDA prompt is on screen. While it's up, suppress the update toast so we don't
+ * pile two modals on top of each other. When it closes and an update is ready, re-attempt the toast.
+ */
+export function setFdaPromptShowing(value: boolean): void {
+  const wasShowing = fdaPromptShowing
+  fdaPromptShowing = value
+  if (wasShowing && !value) {
+    showUpdateToast()
+  }
+}
+
 export async function checkForUpdates(): Promise<void> {
   if (updateState.status === 'downloading' || updateState.status === 'ready') {
     return // Don't interrupt ongoing download or ready state
@@ -57,7 +110,7 @@ export async function checkForUpdates(): Promise<void> {
         log.info('v{version} installed, restart to apply', { version: update.version })
         updateState.status = 'ready'
         updateState.update = update
-        addToast(UpdateToastContent, { id: 'update', dismissal: 'persistent' })
+        showUpdateToast()
       } else {
         log.debug('v{version} is up to date', { version: currentVersion })
         updateState.status = 'idle'
@@ -74,7 +127,7 @@ export async function checkForUpdates(): Promise<void> {
         log.info('v{version} installed, restart to apply', { version: update.version })
         updateState.status = 'ready'
         updateState.update = { version: update.version, url: '', signature: '' }
-        addToast(UpdateToastContent, { id: 'update', dismissal: 'persistent' })
+        showUpdateToast()
       } else {
         log.debug('v{version} is up to date', { version: currentVersion })
         updateState.status = 'idle'
@@ -90,6 +143,13 @@ export async function checkForUpdates(): Promise<void> {
 export function startUpdateChecker(): () => void {
   log.debug('Started')
 
+  // Seed onboarded flag from persisted settings so returning users aren't gated.
+  void loadSettings().then((settings) => {
+    onboarded = settings.isOnboarded
+    // Edge case: an interval tick fired and reached 'ready' before this resolved.
+    showUpdateToast()
+  })
+
   // Check immediately on start
   void checkForUpdates()
 
@@ -114,3 +174,21 @@ export function startUpdateChecker(): () => void {
     unsubscribe()
   }
 }
+
+/**
+ * Test-only hook: reset module-level gating flags. Production code should never call this.
+ */
+export function _resetUpdaterStateForTest(): void {
+  onboarded = false
+  fdaPromptShowing = false
+  updateState.status = 'idle'
+  updateState.update = null
+  updateState.error = null
+}
+
+/**
+ * Test-only hook: directly set the update state's status. Production code should never call this.
+ */
+export function _setUpdateStatusForTest(status: UpdateState['status']): void {
+  updateState.status = status
+}