Context

The onboarding wizard exists (welcome → OAuth connect → trust tier picker) but the experience ends after connecting. The user lands on an empty dashboard and waits. The worker polls every N seconds; the first signals trickle in silently. The user has no idea anything is happening.

The trust tier system requires ~10 approved actions before OBSERVER promotes. This is the right safety design, but it feels like friction unless the user can see progress and feel the twin getting smarter.

The first 10 minutes determine whether someone keeps using this or closes the tab.

Claude Code estimate: ~2-3h

Current State (verified 2026-04-04)

• Onboarding page (`apps/web/public/js/pages/onboarding.js`, 18.6 KB): 3-step wizard with Google OAuth, trust tier selection in human-friendly language, user creation via API
• Trust tier auto-promotion (`TrustTierEngine`): promotes at 10/20/50/100 approval thresholds
• Worker signal polling: discovers users with OAuth tokens, creates per-user connectors, forwards signals to API
• Dashboard: shows stats (confidence, accuracy, patterns) but starts empty

Proposed Change

1. Post-connect signal preview

After OAuth callback, show a "Connecting to your accounts..." screen with live status. Pull first batch of signals immediately (synchronous endpoint or worker trigger). Display first 3-5 signals as they arrive.

2. First decision walkthrough

Take the first decision candidate and walk the user through it step by step: what happened → what I'd do → why → what do you think? Same approval card, presented as a guided tutorial.

3. Trust tier progress indicator

Visible progress element on dashboard and approval pages: "Trust level: Watch & Suggest (3 of 10 approvals to unlock routine handling)" with progress bar.

4. "What I learned today" summary

After first 5+ approvals, mini-summary: "From your 5 approvals, I learned: you prefer to archive newsletters, you accept meetings with your team."

Acceptance Criteria

1. After OAuth callback completes → user sees "Connecting to your accounts..." screen (not empty dashboard)
2. First batch of signals appears on screen within 30 seconds of OAuth completion — at least 1 signal visible (email count or calendar event)
3. If user has 0 emails and 0 calendar events → screen shows "No signals yet — I'll check again shortly" (not empty/broken)
4. First decision candidate auto-opens as a guided walkthrough with 4 labeled steps: "Here's what happened", "Here's what I'd do", "Here's why", "What do you think?"
5. User approves or rejects from the walkthrough → approval recorded in DB → walkthrough closes → dashboard loads with updated state
6. Trust tier progress bar visible on dashboard: shows "`N` of 10 approvals" with filled segments
7. Trust tier progress bar visible on approvals page: same data, consistent styling
8. User reaches 10 approvals → progress bar shows completion → celebration message: "I can now handle routine tasks automatically" → message links to Settings page
9. After 5+ approvals in a session → "What I learned" card appears on dashboard with natural-language summary of at least 2 learned preferences
10. "What I learned" summary pulls from `PreferenceEvolutionTracker` — verified by checking that summary text includes preference domains that match the user's feedback history
11. Returning user (already onboarded) → skips onboarding, sees dashboard directly (no re-trigger)
12. All 432 existing tests pass
13. PR passes `/review` before merge

Testing Plan

Files Reference

Out of Scope

• Animated onboarding illustrations or video
• A/B testing different onboarding flows
• Skip-onboarding for API-only users

Related

• Desktop Electron app: native install, tray, process management #13 — Desktop app (first-run happens inside Electron)
• Live notification layer: SSE, approval expiry cron, push alerts #8 — Live notifications (first signals can use SSE if available)
• Part of v0.4 epic (Epic: SkyTwin v0.4 — Local-First Product Completion (HN Launch Ready) #12)

Working Context Protocol

During implementation, maintain two sources of truth to survive context compaction:

1. Local context file: Write progress, decisions, and blockers to .context/issue-9-first-run.md (gitignored). Update this file after each meaningful step. On compaction, re-read this file to restore state.
2. GitHub issue: Post progress comments on #9 at key milestones (subtask complete, blocker hit, design decision made). Reference the issue URL in your conversation so it persists across compaction: Guided first-run: connect → see signals → approve → watch twin learn #9

This ensures no quality loss across compaction events — the local file has granular state, the GitHub issue has durable history.