feat(desktop): skippable v2 onboarding + Settings re-run entry

Merged
KI
5mo ago
+139-39

Summary

  • Add a Skip for now button to the onboarding footer, available on every step (including the GitHub-CLI step) — the whole flow is escapable, not just the gh-cli gate that #4834 already ungated.
  • Add a Settings → Experimental → Run setup again entry so already-onboarded users can re-open the flow to connect agents / add another project.
  • Align the onboarding footer to the same column as step content and group actions Linear-style (meta/help left, flow actions right).

Why / Context

#4834 shipped on main while this branch was in flight and removed the Continue-button gate on the GitHub-CLI step — a different fix for the same "non-blocking" goal. Two gaps remained:

  1. The GH-CLI step is still the only step that's effectively skippable. There's no way to escape onboarding from the project step without actually creating a project, and no way to bail out mid-setup.
  2. Once a user is onboarded, there's no way to re-open the setup flow to connect a provider they skipped or add another project from a guided UI.

This PR closes both gaps. The Skip button + Settings re-run also make the onboarding genuinely non-blocking end-to-end, so we never have to add another targeted gate-removal patch later.

How It Works

Skip button — OnboardingNavigation gets an optional onSkip prop. The layout's handleSkip calls apiTrpcClient.user.completeOnboarding.mutate() (same mutation finish() uses on the project step — stamps onboardedAt), reactively refetches the session so the _authenticated guard sees the new value, then navigates to /v2-workspaces. Tracked as track("onboarding_finished", { outcome: "skipped" }).

Settings re-run — A small transient Zustand store (stores/onboarding-rerun.ts) holds isRerun: boolean with startRerun / endRerun actions. The onboarding layout's existing guard (onboardedAt → Navigate /) now makes an exception when isRerun is true. A useEffect cleanup calls endRerun when the layout unmounts, so leaving onboarding always clears the flag. The store is deliberately not persisted — if the app relaunches mid-rerun, a restored /onboarding route falls back to the redirect rather than trapping an onboarded user. Re-running does not clear onboardedAt; completeOnboarding is idempotent on a subsequent finish/skip.

Settings entry — Registered as EXPERIMENTAL_RERUN_ONBOARDING in settings-search.ts with variant "v2" (the row never shows for v1 users) and search keywords (onboarding, setup, rerun, getting started, github cli, …). Sits alongside the existing v2/migration rows in ExperimentalSettings.

Footer alignment — Footer wrapper now uses max-w-2xl px-8 matching the step content's column, with a top border-t border-border separating the sticky footer from the scroll area. Three-section flex keeps pagination dots centered. Left cluster: Back + icon-only "Get support" (tooltip-labelled). Right cluster: Skip for now (muted ghost) + Continue (primary). Dropped the fixed w-[160px] button widths.

Merge note — During rebase against main, the GH-CLI ungating from #4834 conflicted with this branch's edits to layout.tsx. Resolved by keeping main's removal of ghReady / continueDisabled and layering this branch's skipping / isRerun / handleSkip on top. The now-dead continueDisabled prop was removed from OnboardingNavigation to match.

Manual QA Checklist

Skip on a fresh user

  • Sign up a new user → app redirects to /onboarding
  • Step 1: "Skip for now" is visible in the footer right-cluster, enabled even though GitHub CLI is unauthenticated
  • Click Skip → toast doesn't fire, lands on /v2-workspaces
  • Reopen the app — no redirect back to /onboarding (i.e. onboardedAt was set)
  • Step 2: navigate to /onboarding/project from step 1 first, then Skip → same result

Settings re-run

  • As an onboarded user, open Settings → Experimental → "Run setup again" → "Open setup" button is present
  • Click it → lands on /onboarding step 1 (not bounced back to /)
  • Use Skip or finish via project step → lands on dashboard
  • Click Open setup again → flow re-opens (idempotent)
  • Open setup → relaunch the app while still on /onboarding → on relaunch, the route is restored but the guard redirects to / (rerun flag is non-persistent — verifies the user isn't trapped)
  • Settings search for "onboarding" / "setup" / "rerun" surfaces the row
  • Row does not appear for a v1-only user (variant "v2")

Footer alignment

  • Back button's left edge aligns with content column's left edge
  • Continue button's right edge aligns with content column's right edge
  • Hairline divider above the footer
  • Pagination dots stay centered as you move between steps
  • "Get support" is now an icon-only button with a "Get support" tooltip on hover; clicking it still opens the report-issue URL

Regression sanity

  • First-time onboarding via the project step still works (Open folder + Clone repo paths both finish onboarding and open the new-workspace modal)
  • Back button on step 2 returns to step 1

Testing

  • bun run typecheck ✅
  • bun run lint ✅
  • bun test src/renderer/routes/_authenticated/settings/utils/settings-search/settings-search.test.ts ✅ (7/7)
  • Manual QA pending in this review

Design Decisions

  • Transient store over URL search param for re-run state. A ?rerun=true param would persist in the persistent-hash-history localStorage entry, so an onboarded user who quit mid-rerun would be re-dropped into onboarding on next launch. A non-persistent store resets on launch — restored route falls back to the redirect.
  • Skip doesn't clear onboardedAt. Re-running is a UI convenience, not an unboarding. Keeps the _authenticated launch gate honest and avoids a new tRPC mutation.
  • Placement in Experimental. Sits next to "Try Superset v2" and "V1 to V2 Migration" (both rerun-style v2-coupled actions). Variant "v2" hides it from v1 users automatically.

Known Limitations

  • No confirmation dialog before Skip. Intentional — the request was for genuinely non-blocking setup. Add one if telemetry shows accidental skips.
  • Settings rerun navigates to step 1 every time; there's no "resume where I left off". Step 1 is fast to re-tick if already connected.

Follow-ups

  • Consider surfacing the Settings entry from an empty workspace state (discoverability for users who skipped on step 1 and never re-find the flow).
Open in Stage

Summary by cubic

Make v2 onboarding skippable from any step and add a Settings entry to re-run the flow via a ?rerun=true param. This makes setup non‑blocking and lets users reconnect providers or add projects later.

  • New Features

    • Added “Skip for now” on every step (including GitHub CLI). Completes onboarding, refetches the session, and routes to /v2-workspaces.
    • Added Settings → Experimental → “Run setup again” to reopen /onboarding for onboarded users using ?rerun=true.
    • Aligned the onboarding footer with the content column and grouped actions: left = Back + icon-only “Get support” (with tooltip), center = pagination dots, right = Skip for now + Continue.

  • Refactors

    • Replaced the transient zustand rerun store with a route search param (?rerun=true) to bypass the onboarded redirect only when explicitly re-launched.
    • Refreshed bun.lock to remove a stale nested @superset/host-service/@xterm/headless entry, fixing desktop packaging.

Summary by CodeRabbit

  • New Features

    • Added "Skip for now" option in the onboarding flow
    • Added ability to rerun setup from experimental settings with "Run setup again" option
    • Improved support button UI with icon-only design and tooltip

  • Style

    • Enhanced onboarding layout with updated styling and improved component alignment

Review Change Stack