First Launch & Settings

First Launch & Settings

The first launch experience activates on a fresh workspace where the onboarding has not yet been completed. It presents a mandatory sign-in step first. Once authenticated (or if a backend identity already exists), it shows a persona selector, then a 3-step spotlight tour. Selecting a persona and advancing through all steps or pressing “Skip” on any step dismisses the tour and marks the workspace as no longer in first-launch state. After completion or skip, the tour does not reappear on reload. The Settings panel (opened via the sidebar Settings button) exposes an analytics opt-out toggle. Settings state persists across workspace reloads.

Preconditions

• For first-launch scenarios (1–10): the app is opened with a fresh workspace where the onboarding tour has not been completed. This may require resetting the settings fixture or using a dedicated fresh-workspace seed
• For settings scenarios (11–18): any loaded workspace is acceptable; the Settings panel can be opened regardless of onboarding state
• The settings panel is accessible via the “Settings” button in the sidebar footer

Scenarios

Seed: seed.spec.ts

1. Auth step appears first on fresh workspace

When the workspace is opened for the first time (first launch), a full-screen sign-in page appears before any tour content.

Steps:

1. Navigate to the app root on first launch (workspace with onboarding not completed)
2. Observe the screen before any interaction

Expected: A full-screen sign-in page appears. If a backend identity already exists (e.g., in the bridge environment where the bridge seeds a stub identity), the auth step auto-resolves immediately and the persona selector appears instead. In a true fresh environment with no stored identity, the sign-in page must be interacted with before proceeding.

2. Auth step cannot be skipped

The sign-in step has no skip or close button — the user must authenticate to proceed.

Steps:

1. On the auth step, look for skip, close, or dismiss buttons
2. Inspect all visible controls on the sign-in screen

Expected: No skip button, close (X) button, or dismiss affordance is visible. The user cannot bypass the auth step. The only action available is to sign in.

3. Tour starts automatically on fresh workspace

When the workspace is opened for the first time (first launch), the persona selector appears without any user action required (after the auth step auto-resolves or the user signs in).

Steps:

1. Navigate to the app root
2. Wait for the workspace to load (sidebar becomes visible)
3. Do not click anything — observe the screen

Expected: A full-screen modal overlay with a dark semi-transparent backdrop appears on top of the workspace. The heading “Welcome to Inklings!” is visible. Three persona cards are displayed: “Knowledge Builder”, “Writer”, and “Game Designer”. The “Continue” button is present but disabled (greyed out).

4. Persona selection enables the Continue button

Clicking one of the three persona cards changes its visual state and enables the Continue button.

Steps:

1. Wait for the persona selector to appear (scenario 3)
2. Click the “Writer” persona card
3. Observe the card and the Continue button state

Expected: The “Writer” card shows a blue selection border and a check mark indicator. The Continue button changes to an active state with a blue background and a pointer cursor. The “Writer” card is visually distinct from the unselected cards.

5. Selecting a persona and pressing Continue starts the tour

After selecting a persona and clicking Continue, the persona selector is replaced by the first tour step tooltip.

Steps:

1. Click the “Knowledge Builder” persona card
2. Click the “Continue” button

Expected: The persona selector disappears. A tour tooltip appears with a centered position. The tooltip title reads “Your Second Brain Awaits” (the PKM welcome message). The tooltip displays step progress (e.g., “1 of 3” indicator or dot-based progress). A “Next” button and “Skip” button are visible in the tooltip footer.

6. Advancing through all tour steps completes the tour

Clicking “Next” through all 3 steps and clicking “Got it!” on the final step dismisses the tour.

Steps:

1. Complete persona selection (select any persona and click Continue)
2. On step 1 (welcome), click “Next”
3. On step 2 (new-page spotlight), click “Next”
4. On step 3 (page-tree spotlight), click “Got it!”
5. Observe the UI after clicking “Got it!”

Expected: The tour overlay (backdrop and tooltip) disappears. The main workspace UI is fully interactive. No tour-related elements remain visible. After reloading the page, the persona selector and tour do not reappear — the workspace loads directly to the normal sidebar and editor view.

7. Tour shows a spotlight on the “New Page” button at step 2

At the second tour step, a spotlight cutout highlights the + New Page button.

Steps:

1. Complete persona selection
2. Observe step 1 (welcome — centered tooltip, no spotlight target)
3. Click “Next” to advance to step 2

Expected: Step 2 tooltip appears with title “Create Your First Page”. A spotlight effect (blue border glow and surrounding dark overlay) is visible around the + New Page button in the sidebar. The backdrop areas surrounding the spotlight are visibly dimmed.

8. Tour shows a spotlight on the page tree at step 3

At the third tour step, the spotlight moves to highlight the page tree section.

Steps:

1. Complete persona selection
2. Click “Next” twice to reach step 3

Expected: Step 3 tooltip appears with title “Organize Your World”. The spotlight effect is positioned around the page tree area of the sidebar. The tooltip is positioned to the right of the spotlight target.

9. Skip button dismisses the tour mid-way

Pressing the “Skip” button on any tour step dismisses the entire tour immediately.

Steps:

1. Complete persona selection (select “Game Designer” and click Continue)
2. On step 1, click “Skip”
3. Observe the UI after clicking “Skip”

Expected: The tour overlay disappears immediately. No remaining tour steps are shown. The main workspace is interactive. After reloading the page, the tour does not reappear — the workspace loads directly to the normal view.

10. Tour does not appear after completion on reload

Once first launch has been completed or skipped, navigating back to the app (simulating a reload) does not trigger the persona selector or tour again.

Steps:

1. Complete or skip the tour (scenario 6 or 9)
2. Navigate to the app root again (browser reload or re-navigation)
3. Wait for the workspace to load

Expected: The persona selector does not appear. No tour overlay is shown. The workspace loads directly to the normal sidebar and editor view.

11. Settings panel opens from the sidebar Settings button

The Settings button in the sidebar footer opens a slide-in settings panel.

Steps:

1. Ensure a workspace is loaded (dismiss tour if active)
2. Locate the “Settings” button at the bottom of the sidebar
3. Click the “Settings” button

Expected: A slide-in panel appears from the right side of the screen with aria-label="Settings" and role="dialog". The panel heading reads “Settings”. Sections visible include “Templates”, “Types”, “MCP Server”, “Privacy”, and “Devices”.

12. Analytics opt-out toggle is initially in the “on” state

When opening settings for a fresh workspace, the analytics toggle reflects the default opted-in state.

Steps:

1. Open the Settings panel
2. Scroll to the “Privacy” section
3. Observe the analytics toggle (role="switch")

Expected: The toggle has aria-checked="true" indicating analytics are enabled (opted in). The toggle visual indicator is in the “on” (right) position.

13. Toggling analytics off opts out of analytics

Clicking the analytics toggle when it is currently “on” updates the toggle to the off state.

Steps:

1. Open the Settings panel and scroll to the “Privacy” section
2. Confirm the toggle is aria-checked="true"
3. Click the toggle button

Expected: The toggle changes to aria-checked="false". The visual indicator moves to the left (off) position. The toggle is no longer displayed with the accent color. No error toast appears.

14. Toggling analytics back on opts back in

Clicking the analytics toggle when it is currently “off” restores the opted-in state.

Steps:

1. Open the Settings panel
2. Opt out via the toggle (scenario 11)
3. Click the toggle button a second time

Expected: The toggle changes back to aria-checked="true". The visual indicator moves to the right (on) position. The accent color is restored.

15. Analytics preference persists across settings panel close/reopen

The opted-out state is not reset when the settings panel is closed and reopened during the same session.

Steps:

1. Open Settings, click the analytics toggle to opt out (toggle off)
2. Close the Settings panel by clicking the X button
3. Click the “Settings” button again to reopen the panel
4. Scroll to the “Privacy” section

Expected: The analytics toggle still shows aria-checked="false" (opted out). The state has not reverted to the default.

16. Settings panel closes with the X button

The settings panel has a close button in the header that dismisses it.

Steps:

1. Open the Settings panel
2. Click the X (close) button in the panel header

Expected: The Settings panel disappears. The main workspace layout is fully visible. Focus returns to the main content area.

17. Settings panel closes when pressing Escape

The settings panel responds to the Escape key as a close trigger.

Steps:

1. Open the Settings panel
2. Press the Escape key

Expected: The Settings panel closes. This matches the same behavior as clicking the X button.

18. Settings panel closes when clicking the backdrop

Clicking the semi-transparent backdrop outside the settings panel closes it.

Steps:

1. Open the Settings panel
2. Click on the backdrop overlay to the left of the panel

Expected: The Settings panel closes. The workspace is interactive.

19. Continue button stays disabled without persona selection

The Continue button on the persona selector cannot be activated until a persona card is selected.

Steps:

1. On first launch, observe the persona selector
2. Attempt to click the “Continue” button without selecting any persona card

Expected: The Continue button does not trigger navigation to the tour. It appears with aria-disabled="true" or cursor-not-allowed styling and does not respond to click events. No tour step is shown.

20. Persona selection is reflected in tour messaging

The content of tour tooltips is customized to match the selected persona.

Steps:

1. Select “Game Designer” persona and click Continue
2. Observe the welcome step tooltip title and message

Expected: The tooltip title reads “Build Your Game World”. The message body contains game-designer-specific copy, not the writer or PKM variant.

Test Data

Key	Value	Notes
fresh_workspace_flag	Requires onboarding-not-completed fixture	Workspace must have first-launch state active
persona_pkm	Knowledge Builder	PKM / second-brain persona
persona_writer	Writer	Writer / creative persona
persona_game_designer	Game Designer	Game designer persona
tour_step_count	3	Steps: welcome, new-page spotlight, page-tree spotlight
welcome_title_pkm	Your Second Brain Awaits	Expected tooltip heading for Knowledge Builder persona
welcome_title_writer	Your Creative Companion	Expected tooltip heading for Writer persona
welcome_title_game	Build Your Game World	Expected tooltip heading for Game Designer persona
settings_panel_label	Settings	aria-label on the settings dialog

Notes

• First-launch scenarios (1–8) require a workspace seeded in a state where the onboarding has not been completed. The standard seed.spec.ts workspace may have already completed first launch — a dedicated fixture or seed flag may be needed
• The tour tooltip is rendered above the command palette and settings panel in z-order; if any of these overlap, the tour should win
• The tour activates silently on mount; if the backend call to check launch state fails, the tour does not activate. A non-responsive backend is not a tour failure
• The Continue button communicates its disabled state via aria-disabled="true" and aria-label — use these attributes in assertions
• If the persona call to the backend fails, the tour still proceeds using the locally selected persona. A backend error should not block the user from advancing
• The Settings panel is a position: fixed overlay dialog, not a navigation route. All settings state is reflected immediately in the UI when the toggle is clicked
• Settings persistence across panel close/reopen (scenario 15) is intra-session. Persistence across full page reloads depends on the settings file on disk — this is covered by backend integration tests
• In the HTTP bridge environment, the auth step auto-completes because the bridge seeds a backend identity via IdentityStore. Tests should account for this by waiting for the PersonaSelector to appear (the auth step resolves in <100ms)