Max Weinbach3/17/2026, 1:06:36 PM

* feat: add desktop-only first-run onboarding flow

Implement a 5-step onboarding overlay for new desktop users:
1. Welcome — explains Cowork, lists setup steps
2. Workspace — reuses addWorkspace() native picker
3. Provider — connect at least one model provider via API key/OAuth
4. Defaults — review/set default provider, model, MCP, backups
5. First thread — starter prompts or blank thread

Key design decisions:
- Entirely desktop-local: no websocket/server/protocol changes
- Persisted onboarding status (pending/dismissed/completed) with
  backwards-compatible schema — missing field defaults safely
- Existing users are never hijacked: auto-detection of workspaces,
  threads, or connected providers suppresses onboarding
- "Not now" dismisses; rerun available from Developer settings page
- Uses existing store actions (addWorkspace, provider auth,
  updateWorkspaceDefaults, newThread) — no new IPC

Files changed (all within apps/desktop/):
- types.ts: OnboardingStatus, PersistedOnboardingState, OnboardingStep
- store.ts, store.helpers.ts: ephemeral UI state + action signatures
- store.actions/onboarding.ts: actions + pure shouldAutoOpen helper
- store.actions/bootstrap.ts: auto-open logic + backfill for upgrades
- persistence.ts, desktopSchemas.ts, electron persistence: schema
- App.tsx: render DesktopOnboarding overlay on both views
- ui/onboarding/DesktopOnboarding.tsx: 5-step overlay component
- DeveloperPage.tsx: "Run onboarding again" button
- 24 new tests covering helpers, actions, persistence, UI, and
  protocol guard

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(onboarding): polish with logo, keyboard nav, polling, animations, and timeout

Six improvements to the desktop onboarding overlay:

1. **SVG logo on Welcome step** — Import the existing Cowork folder
   icon and render it alongside the heading for a branded first
   impression.

2. **Keyboard navigation** — Escape key dismisses onboarding (added
   to App.tsx global handler at highest priority). Focus is trapped
   inside the overlay card so Tab doesn't escape to background.

3. **Provider status polling** — While the provider step is visible,
   poll refreshProviderStatus every 4s so OAuth flows that open a
   browser auto-detect when auth completes.

4. **Multi-workspace rerun support** — When rerunning onboarding
   with existing workspaces, the workspace step shows a Select
   dropdown to pick among them instead of forcing a new folder pick.

5. **Smooth height animation** — Wraps step content in a
   ResizeObserver-backed spring animation so the card smoothly
   resizes between steps of different heights.

6. **Workspace server startup timeout** — After 30s of "Starting...",
   shows a warning with guidance to try a different folder instead
   of an indefinite spinner.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(onboarding): address code review findings

1. Remove redundant ternary `autoOpen ? "welcome" : "welcome"`
2. Fix backfill comparison: compare status by value instead of
   object reference that is always !== for new objects
3. Error recovery path no longer forces onboarding open — existing
   users hitting a transient init failure won't see onboarding
4. Remove unused `PersistedState` import from onboarding.ts
5. Extract `displayProviderName`, `isProviderNameString`, and
   `fallbackAuthMethods` to shared `lib/providerDisplayNames.ts`;
   update ProvidersPage, WorkspacesPage, and DesktopOnboarding to
   import from there instead of duplicating
6. Add `UI_DISABLED_PROVIDERS` filtering to onboarding ProviderStep
   (was missing, unlike ProvidersPage which already filtered)
7. Stop provider status polling once a model provider is connected
   instead of polling indefinitely
8. Add tests for: error path onboarding suppression, shared provider
   utilities (displayProviderName, isProviderNameString, fallback
   auth methods)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(onboarding): mark complete only after thread creation succeeds

Move `complete()` after the `await newThread()` call instead of before
it. If thread creation fails (server startup error, filesystem issue),
the overlay stays open so the user can retry or dismiss manually,
rather than being silently marked as completed with no usable session.

Also adds a loading guard to the FirstThreadStep buttons to prevent
double-clicks while the thread is being created.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(onboarding): gate completion on thread actually being created

newThread() returns early (without throwing) on several failure paths
such as missing workspace server URL. The previous catch-only guard
missed these silent failures, marking onboarding complete even when
no thread was created.

Now compares threads.length before and after the newThread() call.
Onboarding is only marked complete when a thread was actually added
to the store.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Parent2e28ef8