First Launch Experience

Phase: MVP (Phase 1) Depends On: Workspace System, Page System, Command Palette, User Settings

---

Overview

The First Launch Experience provides non-blocking onboarding that introduces key features while allowing immediate use. It follows the “Creation, not configuration” principle by auto-creating a workspace and using overlay tooltips instead of blocking wizards.

Flow Diagram

Key Design Decisions

1. Hybrid Approach

Combines two strategies:

• Auto-creation: Default workspace created automatically
• Tour overlay: Non-blocking tooltips highlight features

2. Non-Blocking

Users can interact with the app during the tour. The tour doesn’t prevent any action - it’s purely educational.

3. Progressive Disclosure

Instead of showing everything at once:

1. Initial tooltip points to Command Palette
2. After using palette, highlight page creation
3. After creating page, highlight sidebar navigation

4. Skippable and Dismissible

• “Skip tour” button always visible
• “Don’t show again” option
• Tour state persisted in User Settings

Tour Flow

App Launch (first time)
    │
    ├── Auto-create workspace (silent)
    │
    ├── Show welcome tooltip
    │   "Welcome to Inklings! Press Cmd+K to get started"
    │
    └── User presses Cmd+K
        │
        ├── Highlight Command Palette
        │   "Search pages, run actions, or ask AI"
        │
        └── User creates first page
            │
            ├── Highlight sidebar
            │   "Your pages appear here. Drag to organize."
            │
            └── Tour complete
                │
                └── Set first_launch_completed: true

UX Design

Tooltip Component

┌─────────────────────────────────────────┐
│ 💡 Welcome to Inklings!                 │
│                                         │
│ Press Cmd+K to open the Command         │
│ Palette and start creating.             │
│                                         │
│ [Got it]              [Skip tour]       │
└─────────────────────────────────────────┘
         ▼ (pointer to relevant UI)

Visual Design

• Semi-transparent backdrop (optional, click-through)
• Tooltip positioned near target element
• Subtle pulse animation on target
• Progress indicator (1 of 3, 2 of 3, etc.)

Tour Steps

Step	Target	Message	Trigger for Next
1	Welcome	”Welcome! Press Cmd+K to start”	Cmd+K pressed
2	Command Palette	”Search, navigate, or create”	Page created
3	Sidebar	”Your pages live here”	Click “Got it”

State Management

Tour State

interface TourState {
  active: boolean;
  currentStep: number;
  completed: boolean;
  skipped: boolean;
}

Persistence

Tour completion stored in User Settings:

{
  "first_launch_completed": true
}

API Surface

React Context

interface TourContextValue {
  isActive: boolean;
  currentStep: TourStep | null;
  nextStep: () => void;
  skipTour: () => void;
  completeTour: () => void;
}

const TourContext = createContext<TourContextValue | null>(null);

Tauri Commands

Uses User Settings commands:

• is_first_launch() - Check if tour should show
• complete_first_launch() - Mark tour as done

Component Structure

FirstLaunch/
├── TourProvider.tsx        # Context provider
├── TourOverlay.tsx         # Backdrop and positioning
├── TourTooltip.tsx         # Individual tooltip
├── TourProgress.tsx        # Step indicator (1/3)
├── useTour.ts              # Tour state logic
└── steps.ts                # Tour step definitions

Edge Cases

Scenario	Handling
User closes app during tour	Resume from current step
User manually creates workspace	Skip auto-creation step
Tour tooltip target not visible	Skip to next step
User clicks “Skip”	Mark complete, don’t show again

Testing Strategy

• Unit: Tour state machine
• Component: Tooltip positioning, step progression
• E2E: Full tour flow from first launch

---

This is the integration epic that ties the user experience together. Depends on all core systems.

See also: Agent Setup Guided Flow in the User Settings System — agent-specific first-time configuration shown when agent settings are null.