feat(onboarding): calmer onboarding + local AI download snackbar (tinyhumansai#134)

* feat(onboarding): calmer onboarding with durable deferral + local AI download snackbar

- Add persisted `onboardingDeferredByUser` state so "Set up later" survives
  across sessions (no more overlay nagging on every launch)
- Add SetupBanner for non-intrusive "Finish setting up" reminder with resume path
- Convert LocalAIStep to fire-and-forget download, advancing immediately
- Add LocalAIDownloadSnackbar (bottom-left, collapsible) for persistent download
  progress that doesn't block the main chrome
- Extract shared helpers (formatBytes, formatEta, progressFromStatus) to localAiHelpers.ts
- Add Vitest tests for overlay gating, banner, and snackbar

Closes tinyhumansai#101

* fix(test): remove per-test config mock that overrode global setup exports

The OnboardingOverlay test mocked utils/config with only DEV_FORCE_ONBOARDING,
which shadowed the global mock from setup.ts and dropped IS_DEV — causing
store/index.ts to fail on CI.

Author: graycyrus

.claude/memory.md

@@ -34,6 +34,16 @@ Quick reference for anyone starting with Claude on this project. Updated by the
 - **Default config maps to Medium tier** (`gemma3:4b-it-qat`). If someone changes `model_ids.rs` defaults, they should keep `presets.rs` in sync.
 - **Daemon binary gotcha** — A daemon process (`openhuman-aarch64-apple-darwin run`) auto-starts on port 7788 and respawns on kill. `yarn tauri dev` reuses it if already running. When adding new RPC methods, you must replace this binary: `cp -f target/debug/openhuman-core app/src-tauri/binaries/openhuman-aarch64-apple-darwin`, then kill the old PID so it respawns with the new binary.
 
+## Onboarding System
+
+- **OnboardingOverlay is a portal, not a route** — mounted in `App.tsx`, renders via `createPortal` at z-[9999]. There is no `/onboarding` route in `AppRoutes.tsx`. Gating is purely Redux + workspace flag.
+- **Deferred onboarding** — `onboardingDeferredByUser` in `authSlice.ts` (persisted via redux-persist) durably tracks when a user clicks "Set up later". `SetupBanner.tsx` provides the resume path.
+- **`selectHasIncompleteOnboarding` is unused** in production code — only tested. Don't use it for new features.
+- **`formatBytes` / `formatEta` / `progressFromStatus`** — shared in `app/src/utils/localAiHelpers.ts`. Home.tsx and LocalModelPanel.tsx still have local copies (can be migrated later).
+- **Notification z-index stacking** — ErrorReportNotification: z-[10000] bottom-right. OnboardingOverlay: z-[9999]. LocalAIDownloadSnackbar: z-[9998] bottom-left.
+- **React Compiler lint** — `useCallback` deps must match the full inferred closure. Using `user?._id` as dep when the closure captures `user` triggers `preserve-manual-memoization`. Use `user` as the dep instead.
+- **`setState` in effects** — ESLint `react-hooks/set-state-in-effect` catches synchronous setState in useEffect bodies. Use lazy initializers, compute at render, or event handlers instead.
+
 ## Environment
 
 - **Core sidecar port** — `7788` (default). Check with `lsof -i :7788`.

app/src/App.tsx

@@ -6,8 +6,10 @@ import { PersistGate } from 'redux-persist/integration/react';
 import AppRoutes from './AppRoutes';
 import ServiceBlockingGate from './components/daemon/ServiceBlockingGate';
 import ErrorFallbackScreen from './components/ErrorFallbackScreen';
+import LocalAIDownloadSnackbar from './components/LocalAIDownloadSnackbar';
 import MiniSidebar from './components/MiniSidebar';
 import OnboardingOverlay from './components/OnboardingOverlay';
+import SetupBanner from './components/SetupBanner';
 import SocketProvider from './providers/SocketProvider';
 import UserProvider from './providers/UserProvider';
 import { tagErrorSource } from './services/errorReportQueue';
@@ -43,6 +45,7 @@ function App() {
                     <div className="flex-1 flex overflow-hidden">
                       <MiniSidebar />
                       <div className="flex flex-col flex-1 relative overflow-hidden">
+                        <SetupBanner />
                         <div className="flex-1 overflow-y-auto">
                           <AppRoutes />
                         </div>
@@ -55,6 +58,7 @@ function App() {
                     </div>
                   </div>
                   <OnboardingOverlay />
+                  <LocalAIDownloadSnackbar />
                 </ServiceBlockingGate>
               </Router>
             </SocketProvider>

app/src/components/LocalAIDownloadSnackbar.tsx

@@ -0,0 +1,179 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import {
+  formatBytes,
+  formatEta,
+  progressFromDownloads,
+  statusLabel,
+} from '../utils/localAiHelpers';
+import {
+  isTauri,
+  type LocalAiDownloadsProgress,
+  type LocalAiStatus,
+  openhumanLocalAiDownloadsProgress,
+  openhumanLocalAiStatus,
+} from '../utils/tauriCommands';
+
+const POLL_INTERVAL = 2000;
+
+/**
+ * Persistent snackbar that shows local AI download progress.
+ * Anchored bottom-left to avoid conflict with ErrorReportNotification (bottom-right).
+ * Dismiss hides the UI but does NOT cancel the download.
+ */
+const LocalAIDownloadSnackbar = () => {
+  const [status, setStatus] = useState<LocalAiStatus | null>(null);
+  const [downloads, setDownloads] = useState<LocalAiDownloadsProgress | null>(null);
+  const [dismissed, setDismissed] = useState(false);
+  const [collapsed, setCollapsed] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setInterval>>(undefined);
+
+  // Check Tauri availability once at init
+  const tauriAvailable = (() => {
+    try {
+      return isTauri();
+    } catch {
+      return false;
+    }
+  })();
+
+  // Poll download status
+  useEffect(() => {
+    if (!tauriAvailable) return;
+
+    const poll = async () => {
+      try {
+        const [statusRes, downloadsRes] = await Promise.all([
+          openhumanLocalAiStatus(),
+          openhumanLocalAiDownloadsProgress(),
+        ]);
+        if (statusRes.result) setStatus(statusRes.result);
+        if (downloadsRes.result) setDownloads(downloadsRes.result);
+      } catch {
+        // Silently ignore — core may not be ready
+      }
+    };
+
+    void poll();
+    timerRef.current = setInterval(poll, POLL_INTERVAL);
+    return () => clearInterval(timerRef.current);
+  }, [tauriAvailable]);
+
+  const isDownloading =
+    status?.state === 'downloading' ||
+    downloads?.state === 'downloading' ||
+    (downloads?.progress != null && downloads.progress > 0 && downloads.progress < 1);
+
+  // Auto-show when a new download starts: track prior state in a ref and
+  // reset dismissed on the transition edge (not-downloading → downloading).
+  const wasDownloadingRef = useRef(false);
+  if (isDownloading && !wasDownloadingRef.current && dismissed) {
+    setDismissed(false);
+  }
+  wasDownloadingRef.current = !!isDownloading;
+
+  const handleDismiss = useCallback(() => setDismissed(true), []);
+  const handleToggleCollapse = useCallback(() => setCollapsed(prev => !prev), []);
+
+  if (!tauriAvailable || !isDownloading || dismissed) return null;
+
+  const progress = progressFromDownloads(downloads);
+  const percent = progress != null ? Math.round(progress * 100) : null;
+  const speed = downloads?.speed_bps;
+  const eta = downloads?.eta_seconds;
+  const downloaded = downloads?.downloaded_bytes;
+  const total = downloads?.total_bytes;
+  const label = statusLabel(downloads?.state ?? status?.state ?? 'downloading');
+
+  // Collapsed: small pill
+  if (collapsed) {
+    return createPortal(
+      <div className="fixed bottom-4 left-4 z-[9998] animate-fade-up">
+        <button
+          onClick={handleToggleCollapse}
+          className="flex items-center gap-2 bg-stone-900 border border-stone-700/50 rounded-full px-3 py-2 shadow-large hover:border-stone-600 transition-colors"
+          aria-label="Expand download progress">
+          <svg
+            className="w-4 h-4 text-primary-400 animate-pulse"
+            viewBox="0 0 20 20"
+            fill="currentColor">
+            <path d="M10.75 2.75a.75.75 0 00-1.5 0v8.614L6.295 8.235a.75.75 0 10-1.09 1.03l4.25 4.5a.75.75 0 001.09 0l4.25-4.5a.75.75 0 00-1.09-1.03l-2.955 3.129V2.75z" />
+            <path d="M3.5 12.75a.75.75 0 00-1.5 0v2.5A2.75 2.75 0 004.75 18h10.5A2.75 2.75 0 0018 15.25v-2.5a.75.75 0 00-1.5 0v2.5c0 .69-.56 1.25-1.25 1.25H4.75c-.69 0-1.25-.56-1.25-1.25v-2.5z" />
+          </svg>
+          <span className="text-xs font-medium text-stone-300">
+            {percent != null ? `${percent}%` : label}
+          </span>
+        </button>
+      </div>,
+      document.body
+    );
+  }
+
+  // Expanded: full snackbar
+  return createPortal(
+    <div className="fixed bottom-4 left-4 z-[9998] w-[320px] animate-fade-up">
+      <div className="bg-stone-900 border border-stone-700/50 rounded-2xl shadow-large overflow-hidden">
+        {/* Header */}
+        <div className="flex items-center justify-between px-4 pt-3 pb-1">
+          <div className="flex items-center gap-2">
+            <svg
+              className="w-4 h-4 text-primary-400 animate-pulse"
+              viewBox="0 0 20 20"
+              fill="currentColor">
+              <path d="M10.75 2.75a.75.75 0 00-1.5 0v8.614L6.295 8.235a.75.75 0 10-1.09 1.03l4.25 4.5a.75.75 0 001.09 0l4.25-4.5a.75.75 0 00-1.09-1.03l-2.955 3.129V2.75z" />
+              <path d="M3.5 12.75a.75.75 0 00-1.5 0v2.5A2.75 2.75 0 004.75 18h10.5A2.75 2.75 0 0018 15.25v-2.5a.75.75 0 00-1.5 0v2.5c0 .69-.56 1.25-1.25 1.25H4.75c-.69 0-1.25-.56-1.25-1.25v-2.5z" />
+            </svg>
+            <span className="text-sm font-medium text-white">{label}</span>
+          </div>
+          <div className="flex items-center gap-1">
+            <button
+              onClick={handleToggleCollapse}
+              className="p-1 text-stone-500 hover:text-stone-300 transition-colors"
+              aria-label="Collapse download progress">
+              <svg className="w-3.5 h-3.5" viewBox="0 0 16 16" fill="currentColor">
+                <path d="M3.75 7.25a.75.75 0 000 1.5h8.5a.75.75 0 000-1.5h-8.5z" />
+              </svg>
+            </button>
+            <button
+              onClick={handleDismiss}
+              className="p-1 text-stone-500 hover:text-stone-300 transition-colors"
+              aria-label="Dismiss download notification">
+              <svg className="w-3.5 h-3.5" viewBox="0 0 16 16" fill="currentColor">
+                <path d="M4.28 3.22a.75.75 0 00-1.06 1.06L6.94 8l-3.72 3.72a.75.75 0 101.06 1.06L8 9.06l3.72 3.72a.75.75 0 101.06-1.06L9.06 8l3.72-3.72a.75.75 0 00-1.06-1.06L8 6.94 4.28 3.22z" />
+              </svg>
+            </button>
+          </div>
+        </div>
+
+        {/* Progress bar */}
+        <div className="px-4 py-2">
+          <div className="h-1.5 w-full rounded-full bg-stone-800 overflow-hidden">
+            <div
+              className="h-full rounded-full bg-gradient-to-r from-primary-500 to-primary-400 transition-all duration-500"
+              style={{ width: `${percent ?? 0}%` }}
+            />
+          </div>
+        </div>
+
+        {/* Details */}
+        <div className="flex items-center justify-between px-4 pb-3 text-xs text-stone-400">
+          <span>
+            {downloaded != null && total != null
+              ? `${formatBytes(downloaded)} / ${formatBytes(total)}`
+              : percent != null
+                ? `${percent}%`
+                : 'Preparing...'}
+          </span>
+          <span>
+            {speed != null && speed > 0 ? `${formatBytes(speed)}/s` : ''}
+            {eta != null && eta > 0 ? ` · ${formatEta(eta)}` : ''}
+          </span>
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+};
+
+export default LocalAIDownloadSnackbar;

app/src/components/OnboardingOverlay.tsx

@@ -2,8 +2,9 @@ import { useCallback, useEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
 
 import Onboarding from '../pages/onboarding/Onboarding';
-import { selectIsOnboarded } from '../store/authSelectors';
-import { useAppSelector } from '../store/hooks';
+import { selectIsOnboarded, selectOnboardingDeferred } from '../store/authSelectors';
+import { setOnboardingDeferredForUser } from '../store/authSlice';
+import { useAppDispatch, useAppSelector } from '../store/hooks';
 import { DEV_FORCE_ONBOARDING } from '../utils/config';
 import {
   DEFAULT_WORKSPACE_ONBOARDING_FLAG,
@@ -18,10 +19,12 @@ import {
  * Waits for the user profile to load before making a decision.
  */
 const OnboardingOverlay = () => {
+  const dispatch = useAppDispatch();
   const token = useAppSelector(state => state.auth.token);
   const isAuthBootstrapComplete = useAppSelector(state => state.auth.isAuthBootstrapComplete);
   const user = useAppSelector(state => state.user.user);
   const isOnboarded = useAppSelector(selectIsOnboarded);
+  const isDeferred = useAppSelector(selectOnboardingDeferred);
   const [hasWorkspaceFlag, setHasWorkspaceFlag] = useState<boolean | null>(null);
   const [dismissed, setDismissed] = useState(false);
 
@@ -50,6 +53,13 @@ const OnboardingOverlay = () => {
     setDismissed(true);
   }, []);
 
+  const handleDefer = useCallback(() => {
+    if (user?._id) {
+      dispatch(setOnboardingDeferredForUser({ userId: user._id, deferred: true }));
+    }
+    setDismissed(true);
+  }, [dispatch, user]);
+
   // Don't show if not logged in, bootstrap not complete, or user not loaded
   if (!token || !isAuthBootstrapComplete || !user?._id) return null;
 
@@ -59,13 +69,13 @@ const OnboardingOverlay = () => {
   // Determine if onboarding should show
   const shouldShow = DEV_FORCE_ONBOARDING
     ? !dismissed
-    : !isOnboarded && !hasWorkspaceFlag && !dismissed;
+    : !isOnboarded && !hasWorkspaceFlag && !isDeferred && !dismissed;
 
   if (!shouldShow) return null;
 
   return createPortal(
     <div className="fixed inset-0 z-[9999] bg-canvas-900/95 backdrop-blur-md flex items-center justify-center">
-      <Onboarding onComplete={handleComplete} />
+      <Onboarding onComplete={handleComplete} onDefer={handleDefer} />
     </div>,
     document.body
   );

app/src/components/SetupBanner.tsx

@@ -0,0 +1,70 @@
+import { useCallback, useState } from 'react';
+
+import { selectIsOnboarded, selectOnboardingDeferred } from '../store/authSelectors';
+import { setOnboardingDeferredForUser } from '../store/authSlice';
+import { useAppDispatch, useAppSelector } from '../store/hooks';
+
+const SESSION_KEY = 'setupBannerDismissed';
+
+/**
+ * Non-intrusive banner shown when a user has deferred onboarding but hasn't completed it.
+ * Provides a clear path to resume setup without blocking the app.
+ */
+const SetupBanner = () => {
+  const dispatch = useAppDispatch();
+  const isOnboarded = useAppSelector(selectIsOnboarded);
+  const isDeferred = useAppSelector(selectOnboardingDeferred);
+  const userId = useAppSelector(state => state.user.user?._id);
+
+  const [sessionDismissed, setSessionDismissed] = useState(
+    () => sessionStorage.getItem(SESSION_KEY) === 'true'
+  );
+
+  const handleResume = useCallback(() => {
+    if (userId) {
+      dispatch(setOnboardingDeferredForUser({ userId, deferred: false }));
+    }
+  }, [dispatch, userId]);
+
+  const handleDismiss = useCallback(() => {
+    sessionStorage.setItem(SESSION_KEY, 'true');
+    setSessionDismissed(true);
+  }, []);
+
+  if (!isDeferred || isOnboarded || sessionDismissed || !userId) return null;
+
+  return (
+    <div className="mx-4 mt-3 mb-1 flex items-center justify-between gap-3 rounded-xl border border-primary-500/20 bg-primary-500/5 px-4 py-2.5">
+      <div className="flex items-center gap-2.5 min-w-0">
+        <svg
+          className="w-4 h-4 text-primary-400 flex-shrink-0"
+          viewBox="0 0 20 20"
+          fill="currentColor">
+          <path
+            fillRule="evenodd"
+            d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a.75.75 0 000 1.5h.253a.25.25 0 01.244.304l-.459 2.066A1.75 1.75 0 0010.747 15H11a.75.75 0 000-1.5h-.253a.25.25 0 01-.244-.304l.459-2.066A1.75 1.75 0 009.253 9H9z"
+            clipRule="evenodd"
+          />
+        </svg>
+        <span className="text-sm text-stone-300 truncate">Finish setting up OpenHuman</span>
+      </div>
+      <div className="flex items-center gap-2 flex-shrink-0">
+        <button
+          onClick={handleResume}
+          className="text-xs font-medium text-primary-400 hover:text-primary-300 transition-colors">
+          Continue Setup
+        </button>
+        <button
+          onClick={handleDismiss}
+          className="p-0.5 text-stone-500 hover:text-stone-300 transition-colors"
+          aria-label="Dismiss setup banner">
+          <svg className="w-3.5 h-3.5" viewBox="0 0 16 16" fill="currentColor">
+            <path d="M4.28 3.22a.75.75 0 00-1.06 1.06L6.94 8l-3.72 3.72a.75.75 0 101.06 1.06L8 9.06l3.72 3.72a.75.75 0 101.06-1.06L9.06 8l3.72-3.72a.75.75 0 00-1.06-1.06L8 6.94 4.28 3.22z" />
+          </svg>
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default SetupBanner;

app/src/components/__tests__/LocalAIDownloadSnackbar.test.tsx

@@ -0,0 +1,44 @@
+import { screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { renderWithProviders } from '../../test/test-utils';
+import LocalAIDownloadSnackbar from '../LocalAIDownloadSnackbar';
+
+// Default: isTauri returns false, so snackbar should not render
+vi.mock('../../utils/tauriCommands', () => ({
+  isTauri: vi.fn(() => false),
+  openhumanLocalAiStatus: vi.fn().mockResolvedValue({ result: null }),
+  openhumanLocalAiDownloadsProgress: vi.fn().mockResolvedValue({ result: null }),
+}));
+
+describe('LocalAIDownloadSnackbar', () => {
+  it('does not render when not in Tauri environment', () => {
+    renderWithProviders(<LocalAIDownloadSnackbar />);
+
+    expect(screen.queryByText('Downloading')).not.toBeInTheDocument();
+    expect(screen.queryByLabelText('Dismiss download notification')).not.toBeInTheDocument();
+  });
+
+  it('does not render when no download is active', async () => {
+    const tauriCommands = await import('../../utils/tauriCommands');
+    vi.mocked(tauriCommands.isTauri).mockReturnValue(true);
+    vi.mocked(tauriCommands.openhumanLocalAiStatus).mockResolvedValue({
+      result: { state: 'ready' } as never,
+      logs: [],
+    });
+    vi.mocked(tauriCommands.openhumanLocalAiDownloadsProgress).mockResolvedValue({
+      result: { state: 'idle', progress: null } as never,
+      logs: [],
+    });
+
+    renderWithProviders(<LocalAIDownloadSnackbar />);
+
+    // Wait for poll cycle
+    await vi.waitFor(() => {
+      expect(screen.queryByText('Downloading')).not.toBeInTheDocument();
+    });
+
+    // Reset mock
+    vi.mocked(tauriCommands.isTauri).mockReturnValue(false);
+  });
+});