Add first-run onboarding

[vyctorbrzezowski]

Summary

• Add a first-run SwiftUI onboarding flow for CodexBar.app: permissions, local access detection, provider selection, appearance, and final settings.
• Wire onboarding into the real app lifecycle so first GUI launch opens onboarding, completion starts background work, and the status menu opens after setup.
• Persist provider detection, provider choices, appearance settings, and final onboarding settings without changing install artifacts or standalone CLI behavior.
• Reuse existing provider SVG resources and provider branding colors; no new provider image assets.
• Align the onboarding visuals with the current codexbar.app design language, including the background treatment, gradients, buttons, and overall surface styling.

Demo

https://karma-dory-nytv.here.now/codexbar-onboarding-demo.mp4

Screenshots

Notes

• Install model is unchanged: GitHub zip, Sparkle, Homebrew Cask, and CLI artifacts still install bits only.
• Onboarding runs on first GUI launch of CodexBar.app; the standalone CLI remains headless.
• Existing users with prior config/settings are marked as already onboarded so updates do not unexpectedly show onboarding.
• After Finish Setup, CodexBar starts background work and opens the menu bar popover automatically.
• The first button creates an explicit user action before macOS prompts. Notification authorization can be requested directly; Keychain/browser/session prompts still appear only when the real access attempt requires them.

Validation

• swift build
• swift test
• swift test --filter 'CodexBarTests.SettingsStoreTests'
• make check
• git diff --check
• codex review --base origin/main

Codex review found a P3 preview issue where the Appearance preview kept Codex active even when only another provider was selected; fixed by driving the preview from selected providers and falling back to Codex only when the selection is empty.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed May 28, 2026, 9:53 AM ET / 13:53 UTC.

Summary
Adds a SwiftUI first-run onboarding flow wired into app launch, provider access detection and selection, appearance/final settings persistence, notification prompting, and focused settings tests.

Reproducibility: not applicable. this is a feature PR, not a bug report. The contributor supplied after-change video proof showing the onboarding flow in a real app session.

Review metrics: 3 noteworthy metrics.

• Changed Surface: 18 files, 3477 added, 81 removed. The PR is a broad first-run setup change spanning app lifecycle, settings, provider detection, UI, localization, and tests.
• Proof Media: 1 MP4, 39.3s, 1920x1080. The recording directly shows the user-visible onboarding flow after the change.
• Branch Base: merge-base 83ed8e4; current main c3bc1ad. Maintainers should ensure final checks run on a refreshed merge with current main.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Confirm the first-run provider/default policy, including close-window behavior and existing-user skip behavior.
• Run required checks against a refreshed current-main merge before landing.

Mantis proof suggestion
A clean-profile visual smoke would materially help maintainer review of first-launch onboarding and post-finish menu behavior. A maintainer can ask Mantis to capture proof by posting a new PR comment that starts with the OpenClaw Mantis account mention, followed by:

visual task: verify a clean first launch shows onboarding, detected providers can be selected, Finish Setup starts CodexBar and opens the menu.

Risk before merge

• [P1] The PR changes first-run provider enablement and persists selected providers based on local detection/configured access; maintainers should explicitly confirm those defaults and the close-window auto-completion behavior are intended.
• [P1] The branch was based before current main, and the fetched GitHub merge ref was not current-main-based; required checks and final review should run against the refreshed merge so recent Bedrock/current-main changes stay covered.

Maintainer options:

1. Confirm Provider Setup Policy (recommended)
   Before merge, maintainers should confirm that detected/configured providers, the Codex fallback, notification handling, and close-window auto-completion are the intended first-run policy.
2. Accept The Default Selection Behavior
   Maintainers can intentionally accept the current provider auto-selection behavior if the video proof and tests are enough for the first release of onboarding.
3. Pause For A Narrower Onboarding Slice
   If the setup policy is still unsettled, pause this PR and split visual onboarding from provider enablement persistence.

Next step before merge

• [P2] The remaining action is maintainer product and upgrade review for first-run provider/default behavior, not a narrow automated repair.

Security
Cleared: The diff does not add dependencies, workflows, download/execute paths, or secret exposure; provider detection reports sanitized/configured access and local file presence rather than raw credentials.

Review details

Best possible solution:

Land the onboarding after maintainer approval of the first-run provider/default policy and a refreshed current-main check, preserving existing users' settings while keeping the new-user setup flow explicit.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature PR, not a bug report. The contributor supplied after-change video proof showing the onboarding flow in a real app session.

Is this the best way to solve the issue?

Unclear until maintainer product review: the implementation reuses SettingsStore/provider detection and focused tests, but the first-run defaults and automatic completion policy are maintainer decisions rather than pure correctness questions.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against c3bc1adcfafc.

Label changes

Label changes:

• add feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A polished first-run onboarding flow is an unusually high-leverage user-facing improvement for CodexBar setup.

Label justifications:

• P2: This is a normal-priority user-facing onboarding feature with meaningful setup impact but no emergency production regression.
• merge-risk: 🚨 auth-provider: Merging changes first-run provider detection, provider enablement persistence, and notification/auth-adjacent setup flow.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A polished first-run onboarding flow is an unusually high-leverage user-facing improvement for CodexBar setup.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (recording): The inspected MP4 proof and generated contact sheet show the after-change onboarding flow through finish and menu opening in a real app session.
• proof: sufficient: Contributor real behavior proof is sufficient. The inspected MP4 proof and generated contact sheet show the after-change onboarding flow through finish and menu opening in a real app session.
• proof: 🎥 video: Contributor real behavior proof includes video or recording evidence. The inspected MP4 proof and generated contact sheet show the after-change onboarding flow through finish and menu opening in a real app session.

Evidence reviewed

What I checked:

• Repository policy read: Read the full target AGENTS.md and applied its SwiftPM, focused-test, no-Keychain-prompt, and provider-data-separation guidance to the review. (AGENTS.md:1, c3bc1adcfafc)
• Current main does not already have this onboarding flow: Current main has no OnboardingWindowController/onboardingCompleted/Set Up CodexBar implementation hits; only an unrelated Claude docs first-run mention appeared. (c3bc1adcfafc)
• App lifecycle wiring: The PR routes application launch through showOnboardingIfNeeded and defers startup notification prompting until onboarding state is known. (Sources/CodexBar/CodexbarApp.swift:379, eddfaba1f7e3)
• Onboarding completion persists provider setup: The PR applies display/final preferences and then calls completeOnboarding with the selected providers; provider detection only enables selectable selected providers and marks detection complete. (Sources/CodexBar/OnboardingView.swift:511, eddfaba1f7e3)
• Focused tests cover the new settings/provider behavior: SettingsStoreTests cover suggestion priority, saved credential detection, conservative startup detection, selected provider persistence, disabling unavailable Codex, preview ordering, and notification choice persistence. (Tests/CodexBarTests/SettingsStoreTests.swift:198, eddfaba1f7e3)
• Real behavior proof inspected: The prepared proof manifest and contact sheet show a 39.3s 1920x1080 MP4 walking through onboarding, appearance choices, final settings, and the menu opening after finish.

Likely related people:

• Peter Steinberger: Introduced the provider detection/settings path and is the dominant contributor across the app lifecycle, settings, usage store, and provider icon files sampled. (role: feature-history owner and recent area contributor; confidence: high; commits: a1b94b48df4e, 3dc23821a850, 589b77ca83a3; files: Sources/CodexBar/SettingsStore+ProviderDetection.swift, Sources/CodexBar/CodexbarApp.swift, Sources/CodexBar/UsageStore.swift)
• 陳柏瑋: Added Antigravity OAuth-backed remote usage and the Antigravity credential/running-state detection that the onboarding provider scan now incorporates. (role: adjacent provider-auth contributor; confidence: medium; commits: e98c8f5e4c0d; files: Sources/CodexBar/SettingsStore+ProviderDetection.swift, Sources/CodexBarCore/Providers/Antigravity/AntigravityOAuthCredentialsStore.swift)
• Perry Story: Recently changed background credits/dashboard refresh behavior in UsageStore, which is adjacent to the PR's delayed background-work startup path. (role: recent adjacent UsageStore contributor; confidence: medium; commits: c2b63a01bae4, d5bf26974b85; files: Sources/CodexBar/UsageStore.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[vyctorbrzezowski]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26541678709
• Updated: 2026-05-27T22:15:25.322Z