Repository navigation
Add a first-run setup guide - #5146
Merged
Merged
Conversation
A new install opens a four-step guide in place of the app: connect a coding agent, add projects, pick plugins, and set up devices. Every step can be skipped. Finishing or skipping records onboardingCompletedAt and turns on a "Finish setting up bb" checklist on the home screen. - Agent step: provider health for the primary machine, install through the existing provider CLI installer, and guided sign-in that runs the provider's own login command in a host terminal and lifts the link, one-time code, or paste prompt out of its output. Codex declares a local browser login next to its device-code login; the guide picks by whether the browser is on the machine. - Projects step: new host.discover_repos daemon command (protocol 230), GET /hosts/:id/discovered-repos, sdk.hosts.experimental_discoverRepos, and bb project discover. - Plugins step: curated bb-official catalog entries, enabled in place or installed from the catalog. - Devices step: bb connect settings, Add Machine, mobile downloads. - Settings -> General -> Setup guide and bb settings replay-onboarding show the guide again. Co-Authored-By: Claude Code <noreply@anthropic.com>
SawyerHood
marked this pull request as ready for review
October 7, 2026 22:37
SawyerHood
added a commit
that referenced
this pull request
Oct 8, 2026
## Human comments ## What was wrong The home screen still showed the zero-project welcome page (the glossy bb logo with four actions) in place of the composer. Since the first-run setup guide landed in #5146, that page duplicates it: "Automatically import my projects" is the guide's projects step, "New project" is already in the composer's project picker, and "New thread" only revealed the composer the page was hiding. ## What changed - `apps/app/src/views/RootComposeEmptyWelcome.tsx` is deleted. `RootComposeView.tsx` always renders the composer, so a zero-project home shows the existing "Finish setting up bb" / "No agent is ready" banner above it. - The `startedComposing` state existed only to hide the welcome page and is removed. Prompt deep links (`?prompt=`) relied on it for focus, so that effect now focuses the composer directly. - `SetupChecklistCard`, `SetupChecklist`, and `NoAgentNotice` (the card rendered under the logo) are removed along with `SetupChecklistViews.tsx`. The banner is the only checklist surface left. - The onboarding story's mock home shows the banner instead of the logo and card, and gains a state for the "Finish setting up bb" banner. - Theme Preview's "New thread" view was a mock of the welcome page. It now shows the empty composer, and the fixture-anatomy anchors point at the real composer-only screen. - `docs/api_to_audit.md` no longer lists welcome states as page-level behavior. Behavior lost with the page: the "Learn what bb can do" and "Automatically import my projects" prompt shortcuts. ## How you verified - `pnpm exec turbo run typecheck lint --filter=@bb/app --filter=bb-plugin-theme-preview --continue` passes. - `pnpm exec turbo run test --filter=@bb/app --filter=bb-plugin-theme-preview -- src/views/RootCompose src/components/onboarding src/components/plugin/theme-preview-fixture-anatomy.test.ts src/components/plugin/PluginNewThreadComposer.test.tsx src/hooks/useCreateThreadInEnvironment.test.ts app.test.tsx` passes (13 files / 235 tests in the app, 33 tests in Theme Preview). - Rendered the onboarding and banner stories in Ladle and checked the setup guide steps and both home banners. - Not checked: the zero-project home screen in a running 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.
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
onboardingCompletedAtis null. Four steps, each skippable: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.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_VERSION229 → 230: newhost.discover_reposonline RPC command;provider.healthresults may carry an optionallocalLoginCommand.GET /hosts/:id/discovered-repos,sdk.hosts.experimental_discoverRepos(entry indocs/api_to_audit.md, symbol added to the Plugin Guide), andbb project discover [--machine].onboardingCompletedAtandsetupChecklistVisible; both are optional on write so older clients keep working.bb settings replay-onboardingand Settings → General → Setup guide clear the completion time.0140marks installs that already have a project or a thread as set up, so existing users see neither the guide nor the checklist.claude auth login; Codex reportscodex login --device-authpluslocalLoginCommand: "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.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
GET /hosts/:id/discovered-reposroute, migration0140on fresh and existing stores, CLI output forproject discoverandsettings 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) andturbo run testfor@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.bb-apptarball 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).🤖 Generated with Claude Code