[Feature] Onboarding experience: first-time install to first task in ≤3 minutes

[Astro-Han]

Goal

User goes from downloading the installer to completing their first task in under 3 minutes. No API key configuration, no model selection required.

Why now

• PawWork positioning (Astro-Han 2026-05-11 DM): open-source free Codex App / Claude Code Desktop, out-of-the-box, ships its own free model + search, beginner-friendly.
• Promotion path (task flaky(windows): nested directory snapshot revert assertion fails #12 research): the slack of "等 [Feature] Rewrite packages/ui + packages/app visual layer against PawWork design system (incremental PR series) #440 视觉重塑 + onboarding 完成" is being compressed. Promotion can start once core experience + visual + onboarding are in place.
• 17a slice in [Feature] Rewrite packages/ui + packages/app visual layer against PawWork design system (incremental PR series) #440 lands the home shell (hero + composer + starters). Onboarding sits on top of that home as a first-run guide layer.

Key UX

• First-launch quick tour: 3 steps max, skippable. Introduces the composer, the starter cards, and the session timeline.
• Free model + search out of the box: no API key required to run the first task. PawWork ships a default model and search backend the user does not have to configure.
• Demo task one-click: a "Hello PawWork" starter that triggers a real model call + real search + writes a small file, so the user sees end-to-end capability within minutes.
• Zero-assumption copy: no "API", "token", "context window" jargon on the first-run path. Everything is plain language.
• Skip path: power users can dismiss onboarding without seeing it again.

Acceptance

• Fresh macOS install completes "Hello PawWork" in ≤ 3 minutes without opening Settings.
• Fresh Windows install same.
• First-run tour can be re-opened from the command palette (feat: redesign command palette IA and session navigation #522).
• Telemetry (or local marker): record whether first-run tour was completed or skipped, no PII.

Dependencies

• [Feature] Rewrite packages/ui + packages/app visual layer against PawWork design system (incremental PR series) #440 slice 17a (home shell with composer + starters) must land first.
• Default free model + search backend must be wired and stable. If not yet shipped, list the gap in this issue's checklist and split into a sub-task.
• Copy material in docs/content_strategy/ can be reused.

Non-goals (v1)

• Account creation / login flow.
• Paid plan upsell (positioning is open-source free).
• Multi-language onboarding beyond en/zh (matches current i18n coverage).
• Power-user features (worktrees, custom skills, etc.) — those live in their own discovery paths.

Owner

To be assigned after #440 slice 17a lands. Design spec + copy prep can start now in parallel.

Related

• task flaky(windows): nested directory snapshot revert assertion fails #12 promotion research (#PawWork:8732f499)
• [Feature] Rewrite packages/ui + packages/app visual layer against PawWork design system (incremental PR series) #440 visual refresh (slice 17a)
• feat: redesign command palette IA and session navigation #522 command palette IA (merged)
• docs/content_strategy/ (existing copy basis)

[Astro-Han]

Linking this onboarding issue back to the current UI rewrite launch contract in #599. For the May launch train, onboarding is part of the complete UI rewrite experience, not a minimum prompt-only loop.\n\nWorking split for this track:\n\n- CC leads product and UI implementation for the first-run onboarding surface.\n- Codex supports with boundary checks, review, focused E2E, Electron desktop manual verification, perf risk checks, and integration quality.\n- The final acceptance path should be verified on latest dev: first launch -> onboarding -> first successful task -> main conversation flow.\n\nKeep the detailed onboarding UX and acceptance here; use #599 as the umbrella launch contract.