Onboarding: post-setup first-success moment — starter collection + panel tour

[malpern]

Onboarding: post-setup first-success path

Product decisions — approved

After first-ever successful setup, guide a new user through a small progression that proves value before introducing general-purpose editing:

1. Caps Lock → Escape — offer one-click enable of the existing starter collection. Explain the immediate payoff: press Caps Lock and it behaves as Escape.
2. Hold for Hyper — add a second, optional step that teaches a hold behavior and creates a Hyper key. Explain that Hyper is a clean modifier combination for personal shortcuts.
3. App launching — use the Hyper key to teach one practical launcher action, so the user sees a real automation rather than an abstract key definition.
4. Make your own remapping — point to the Rules sidebar and guide the user to the custom-rule editor, framing it as the place to create or change keyboard behavior.

Each step must be optional, skippable, and reversible. Do not make the tour a setup gate.

Trigger

First-ever successful completion: wizard closes healthy (.wizardStartupRevalidate / .wizardClosed) on a run where the welcome page was shown. Reuse wizard_has_seen_welcome plus a new one-shot onboarding_first_success_shown flag.

Implementation constraints

• Reuse existing collection, Hyper, launcher, and Rules-sidebar machinery where possible.
• Each step should verify its immediate result before advancing.
• Do not change permission detection, installer execution, or runtime semantics as part of this onboarding work.
• Preserve accessibility identifiers and add them to any new interactive controls.

Acceptance criteria

• A first-time successful setup can lead a user from Caps Lock → Escape through Hyper and an app-launch action, then into the Rules sidebar.
• Every step is optional, skippable, and reversible.
• A user can understand the purpose of Hyper without prior keyboard-customization knowledge.
• Existing users and subsequent wizard completions do not see the one-shot experience.
• Focused tests cover trigger/one-shot state and the progression's actions.