Skip to content

First-run onboarding: welcome, guided empty states and a Get started checklist - #91

Merged
marcellosso merged 3 commits into
mainfrom
feat/onboarding
Nov 13, 2026
Merged

marcellosso merged 3 commits into
mainfrom
feat/onboarding

Conversation

@marcellosso

Copy link
Copy Markdown
Owner

Closes #90

What changed

A short first run in both apps, with the same words, step order and timing in each.

Welcome (first launch only). Three steps in a sheet, each with a small mock of the window and no version numbers:

  1. A project is a folder
  2. A service is a command that keeps running, like pnpm dev or docker compose up
  3. The port tells localhost it's up

It has Skip (Not Now on the last step), Back and Continue. The last step's primary action is Add Project…, which opens the existing Add Project sheet (scan + Suggestions review). Escape, Skip, Not Now and finishing all mark it seen, so it never opens again. It opens after the unreadable-files and Orphans questions, never on top of them.

Guided empty states.

  • No Projects: the title is Add Your First Project, with one line on what a Project is and one primary Add Project… button. Import Project… and Connect Your Agents… are now quieter links under it.
  • Project without Services: Detect Services… / Add Service… stay as they were, with the same concept wording as the welcome.
  • Sidebar +: macOS now opens the same menu as Linux/Windows (New Project…, Import Project…). ⌘N and the File menu are unchanged.

Get started checklist. Shown at the foot of the sidebar, above the telemetry notice, once a Project exists. Its rows: Add a project, Add a service, Start your first service, Connect your agents (optional).

  • Rows tick from real state: Projects and Services from the core, "Start" once a Service on this computer is Running (it stays ticked after that), and agents from AgentSetup's statuses (re-read whenever a sheet closes).
  • An open row takes you there: Detect Services on the selected or first Project without Services, select a Project to start, or open Connect your agents.
  • × hides it for good, and it also goes away for good once every row is ticked.
  • Ticks use the accent colour, since green belongs to Service State.

Connect your agents no longer opens by itself at the first launch. It's offered from the checklist and is still in Settings › Agents, the command palette and the empty state.

Where the state lives

App settings only, never Project Configuration, Project files or the user's folders:

  • Linux/Windows: an onboarding object (hasSeenWelcome, isChecklistDone, hasStartedService) in the app's settings.json, through two commands, onboarding / save_onboarding. These replace take_connect_agents_offer.
  • macOS: three UserDefaults keys: onboardingHasSeenWelcome, onboardingChecklistDone, onboardingHasStartedService.

Existing users

The record is decided once, at the first launch of this version, and saved:

  • Opened before: someone who had Projects, or whom an earlier version had already sent through the old auto-opened Connect your agents (hasOfferedAgents / hasOfferedConnectAgents; on Linux/Windows also the close explanation), is marked done. They see neither the welcome nor the checklist.
  • New: a new user gets the welcome. If they add a Project some other way before the welcome could show (e.g. an Orphans question was up), the welcome is skipped but the checklist stays.

Telemetry

No events added. The core documents app_first_open and app_opened as the only events, and the notice and Settings say data is sent "when localhost opens". The issue keeps that notice unchanged, so adding onboarding events would make it inaccurate. docs/analytics.md and the privacy page are unchanged. This would be easy to add later, together with new notice wording.

Docs

  • quick-start.md: describes the first run, and step 1 now starts from Add Project… / the + menu.
  • mcp.md and the README: no longer say the agents sheet opens by itself.
  • configuration.md: the + menu now exists on both platforms.
  • AGENTS.md: a product rule for the first run.

No changelog entry.

How it was checked

  • apps/desktop: pnpm typecheck, pnpm test (128 tests, including new ones), pnpm build.
    • onboarding.test.ts: first launch vs. opened before vs. already has Projects, never again once seen, the checklist ticking from real state (Starting doesn't count, Running stays ticked), and agents counting.
    • Onboarding.test.tsx: walking the welcome to Add Project…, Escape, the checklist actions, auto-hide when complete, ×, and nothing for existing users.
  • src-tauri: cargo test (new settings tests, including reading an earlier version's settings.json), cargo clippy --all-targets -D warnings, cargo fmt --check. bindings.ts regenerated.
  • macOS: scripts/build-core.sh debug and an xcodebuild Debug build. The app has no test target, so its logic mirrors onboarding.ts in Onboarding.swift, and the Tauri tests cover the rules.
  • Ran both UIs in light and dark and took screenshots of each welcome step, the no-Projects empty state and the checklist. For Linux/Windows this was the real React app in Chrome with mocked bindings; for macOS, the Debug build on a temporary storage root. Screenshots are added in a comment below.
  • Not done: a VoiceOver/Orca pass, and running on Linux/Windows hardware.

Reset onboarding to test it

Use LOCALHOST_STORAGE_ROOT=/tmp/localhost-dev so you have no Projects. Then:

  • macOS: defaults delete io.github.marcellosso.localhost onboardingHasSeenWelcome; defaults delete io.github.marcellosso.localhost onboardingChecklistDone; defaults delete io.github.marcellosso.localhost onboardingHasStartedService; defaults delete io.github.marcellosso.localhost hasOfferedConnectAgents. You can also launch with -onboardingHasSeenWelcome NO -onboardingChecklistDone NO -onboardingHasStartedService NO -hasOfferedConnectAgents NO to override without writing.
  • Linux/Windows: remove the onboarding, hasOfferedAgents and hasExplainedClose keys from settings.json in the app's config folder (~/.config/io.github.marcellosso.localhost.desktop/, %APPDATA%\io.github.marcellosso.localhost.desktop\).

Left out

Machines in first-run, a sample Project, sign-in, coach marks, changes to the telemetry notice, and telemetry events (see above).

@vercel

vercel Bot commented Nov 13, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
localhost-web Ready Ready Preview Nov 13, 2026 3:02am UTC

@marcellosso
marcellosso merged commit 6594c5e into main Nov 13, 2026
12 checks passed
@marcellosso
marcellosso deleted the feat/onboarding branch November 13, 2026 03:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

First-run onboarding: guide new users to their first Project and Service

1 participant