Repository navigation
Delete the newOnboarding experiment and the first-run flow - #2001
Merged
Merged
Conversation
The first-run setup guide shipped behind the default-off `newOnboarding` experiment and was never enabled by default, so it was dead weight across seven packages. This removes the experiment key, the flow, and everything that existed only to serve it. Deleted end to end: - `OnboardingHost`/`OnboardingFlow` and their App mount. - The `newOnboarding` experiment key, its Settings → Experiments toggle, and its client fixtures. - `app_settings.onboarding_completed_at` (migration 0101), its domain field, the Settings → General "Setup guide" replay control, and `bb settings replay-onboarding`. - The five onboarding funnel telemetry events, the `/system/onboarding/event` route, and `sdk.system.onboardingEvent`. - The `/system/onboarding/repos` route, `sdk.system.onboardingRepos`, and the `workspace.discover_repos` daemon command and handler, which had no other caller. HOST_DAEMON_PROTOCOL_VERSION 135 → 136. `getOnboardingAgentOverview` and `/system/onboarding/agents` stay: the root composer resolves an unset provider selection through them, so they are not onboarding-only despite the name. Renaming them is a follow-up. `useOnboardingAgents` loses its now-constant `poll` option. Verified: typecheck and tests green for app, server, cli, host-daemon, desktop, db, domain, sdk, server-contract, host-daemon-contract, templates, and plugin-sdk. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
SawyerHood
added a commit
that referenced
this pull request
Oct 7, 2026
## Human comments ## What was wrong A new bb install drops the user on an empty home screen with nothing to tell them that they need an installed, signed-in agent before a thread can start, and no path to add projects other than prompting an agent that may not exist yet. An earlier first-run flow (#2001) was removed because it sat behind an experiment that was never turned on. ## What changed A first-run setup guide that renders in place of the app routes while `onboardingCompletedAt` is null. Four steps, each skippable: - **Agent** (`apps/app/src/components/onboarding/`): provider health for the primary machine. Install uses the existing provider CLI install store. Sign in runs the provider's login command in a host terminal and shows a guided panel built from that terminal's output (sign-in link, one-time code, or paste-code box), with the raw terminal one click away and shown automatically when no link appears. - **Projects**: git repositories under the home directory with activity in the last 30 days (newest first, capped at 10), imported as projects. "Add a folder" opens the existing project path dialog. - **Plugins**: six bb-official entries that ship disabled, shown with the marketplace card; enabled in place or installed from the catalog. - **Devices**: the bb connect settings section, the Add Machine dialog, and the mobile download links. Closing the guide records completion and turns on a "Finish setting up bb" checklist: a card on the empty home screen, a one-line banner above the composer otherwise. It clears itself when all four items are done and can be dismissed. Wire and API changes: - **`HOST_DAEMON_PROTOCOL_VERSION` 229 → 230**: new `host.discover_repos` online RPC command; `provider.health` results may carry an optional `localLoginCommand`. - `GET /hosts/:id/discovered-repos`, `sdk.hosts.experimental_discoverRepos` (entry in `docs/api_to_audit.md`, symbol added to the Plugin Guide), and `bb project discover [--machine]`. - General settings gain `onboardingCompletedAt` and `setupChecklistVisible`; both are optional on write so older clients keep working. `bb settings replay-onboarding` and Settings → General → Setup guide clear the completion time. - Migration `0140` marks installs that already have a project or a thread as set up, so existing users see neither the guide nor the checklist. - Provider login commands: Claude Code reports `claude auth login`; Codex reports `codex login --device-auth` plus `localLoginCommand: "codex login"`. The guide uses the local command when the browser is on the machine being signed in, and offers a switch between the two. - The bb connect not-paired note is reworded and loses its warning icon. This also changes Settings → bb connect. Docs updated: `bb-guide-projects.md`, `bb-guide-customization.md`, the bb-cli skill (`command-index.md`, `app-settings.md`), `docs/configuration.md`, `docs/platform-support.md`. ## How you verified - New tests: repo discovery handler (walk rules, recency, limit, home-is-a-repo, wide directories, deadline), `GET /hosts/:id/discovered-repos` route, migration `0140` on fresh and existing stores, CLI output for `project discover` and `settings replay-onboarding`, the gate, the checklist host, and the pure model helpers (agent state resolution, sign-in output parsing against captured Claude Code and Codex output, default selection). - `pnpm exec turbo run typecheck lint --continue --filter='...[origin/main]'` (134 tasks) and `turbo run test` for `@bb/app`, `@bb/server`, `@bb/host-daemon`, `@bb/cli`, `@bb/db`, `@bb/sdk`, `@bb/domain`, the contract packages, and the connect, Codex and Claude Code plugins. - A scripted browser pass over every control in the guide against a dev instance (47 checks: gate, both Codex sign-in routes, every projects state, each plugin toggle including the Browser Automation install, devices, home banner, replay, phone width, light theme). - A clean Ubuntu 24.04 VM with no agents installed, running the packed `bb-app` tarball built from this branch (24 checks: not-installed states, real installs of Claude Code, Codex and Pi from the guide, sign-in panels, the skip path and empty-home checklist, CLI commands). - Not covered: completing a real provider sign-in (completion was simulated with a dummy Codex API key), bb connect pairing, macOS, Windows, and the desktop app. 🤖 Generated with [Claude Code](https://claude.com/claude-code) > AGENT GENERATED Co-authored-by: Claude Code <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was wrong
The first-run setup guide shipped behind the
newOnboardingexperiment, which defaults to false (packages/domain/src/experiments.ts) and was never enabled by default. Nobody saw the flow unless they turned the toggle on by hand, so its UI, its telemetry funnel, its persisted completion timestamp, and a dedicated host-daemon command existed to serve a surface that never ran — spread across seven packages.What changed
Deleted the experiment and everything that existed only for it:
OnboardingHost/OnboardingFlow(828 lines) and theirApp.tsxmount.newOnboardingexperiment key, its Settings → Experiments toggle (web andapps/mobile), and every config fixture that listed it.appSettingsSchema.onboardingCompletedAt, the Settings → General "Setup guide" replay control, andbb settings replay-onboarding. No migration is needed: since [codex] Track landing downloads server-side #102 app settings are key/value rows read throughinArray(key, appSettingsKeys), so the retired key's row is ignored. The legacy wideapp_settingstable keeps its column, which is deliberately frozen forseedKeepAwakePluginConfiguration.POST /system/onboarding/event, andsdk.system.onboardingEvent.GET /system/onboarding/repos,sdk.system.onboardingRepos, and — since nothing else sent it — theworkspace.discover_reposdaemon command with its 460-line handler.Wire change:
HOST_DAEMON_PROTOCOL_VERSION137 → 138, because a command left the protocol. The reason is recorded in theprotocol.tsheader.Docs and agent surfaces updated in the same change:
bb-guide-customization.md(regenerated), thebb-cliSKILL and itsapp-settingsreference,bb-plugin-authoring's SDK method table, anddocs/configuration.md.getOnboardingAgentOverviewandGET /system/onboarding/agentsdeliberately stay. Despite the name they are not onboarding-only: the root composer resolves an unset provider selection throughuseOnboardingAgents(useThreadCreationOptions.ts←RootComposeView.tsx), which ships unconditionally. Renaming that endpoint and its SDK method to match its real purpose is a follow-up, not part of a deletion.useOnboardingAgentsdoes lose itspolloption, which became constant once the flow's caller went away.Two test adjustments worth calling out, both because their subject was deleted rather than because they broke:
apps/clihad a test usingonboardingCompletedAtas its nullable-string case forbb settings general.appSettingsSchemanow holds only booleans, so that path has no live key to exercise; the test is trimmed to the unknown-key assertion it also covered. The generic value-parsing code inupdateGeneralSettingis untouched and still acceptsnull.packages/db's key/value migration test no longer asserts a settings field that no longer exists.How you verified
Nothing here is a behavior fix, so the evidence is that removing a never-enabled surface changes nothing else:
pnpm exec turbo run typecheck— 72/72 tasks green.pnpm exec turbo run testfor@bb/app(3037),@bb/server(1787),@bb/mobile(812),@bb/host-daemon(47 files), plus@bb/db,@bb/domain,@bb/sdk,@bb/cli,@bb/desktop,@bb/server-contract,@bb/host-daemon-contract,@bb/templates,@get-bb/plugin-sdk— all green.pnpm exec turbo run lint— 0 errors (144 pre-existing react-compiler warnings in@bb/app, unchanged).packages/host-daemon-contract's protocol-version test pins 138, and its command-fixture map no longer acceptsworkspace.discover_repos, so a stray sender fails the contract test.newOnboarding,onboardingCompletedAt,replay-onboarding,onboardingRepos,onboardingEvent, anddiscover_reposreturns only theprotocol.tschangelog note.No CHANGELOG entry: per
docs/bb-release-process.mdthose sections are written at release-prep time, and this removes nothing a user could see.Fixes: N/A — no linked issue.