Summary
Introduce a first-run experience (FRE) that launches when a user opens the app for the first time after a fresh installation. The experience should help the user complete the minimum setup required to use MicroClaw successfully and provide a guided tour of the app's primary capabilities.
Problem
After a fresh install, users currently need to discover required setup steps and core product functionality on their own. This creates avoidable friction at the moment when users are forming their first impression of the app, and it may leave the app in a state where key experiences cannot work because essential configuration, such as model setup, is incomplete.
Proposed Experience
The FRE should:
- Trigger automatically on the first app launch after a fresh installation.
- Guide the user through essential setup, including model configuration and any other prerequisites required for the core experience.
- Clearly communicate setup progress, validation errors, and successful completion.
- Include a guided product tour that introduces the main app surfaces and core workflows.
- Allow users to move backward and forward through the flow without losing completed setup.
- Define an appropriate skip or defer experience for non-blocking steps, while keeping required setup explicit.
- Persist completion state so the FRE does not appear on every launch.
- Provide a discoverable way to revisit the product tour or relevant setup later.
- Meet accessibility, localization, keyboard navigation, and screen-reader requirements.
Design Questions
- Which setup steps are mandatory before the user can enter the main app experience?
- Should model setup be embedded directly in the FRE or reuse the existing settings experience?
- Which product capabilities should be included in the initial tour, and should the tour be interactive or instructional?
- What should happen when setup is interrupted, fails, or the app is closed mid-flow?
- How should completion state behave after app updates, resets, or reinstalls?
Acceptance Criteria
- A fresh installation launches the FRE before the user enters the normal app experience.
- The user can complete and validate the required model setup from the FRE.
- The user receives a guided introduction to the app's primary features and workflows.
- Required and optional steps are clearly distinguished.
- Progress is preserved if the FRE is interrupted.
- Once completed, the FRE does not launch again unless the app's first-run state is reset.
- Users can revisit setup guidance or the product tour from within the app.
- The experience has approved UX specifications and meets accessibility and localization requirements.
Summary
Introduce a first-run experience (FRE) that launches when a user opens the app for the first time after a fresh installation. The experience should help the user complete the minimum setup required to use MicroClaw successfully and provide a guided tour of the app's primary capabilities.
Problem
After a fresh install, users currently need to discover required setup steps and core product functionality on their own. This creates avoidable friction at the moment when users are forming their first impression of the app, and it may leave the app in a state where key experiences cannot work because essential configuration, such as model setup, is incomplete.
Proposed Experience
The FRE should:
Design Questions
Acceptance Criteria