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.

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 27, 2026, 6:15 PM ET / 22:15 UTC.

Summary
The PR adds a SwiftUI first-run onboarding flow wired into app launch, provider access detection and selection, menu appearance choices, final settings persistence, and focused SettingsStore tests.

Reproducibility: not applicable. as a bug reproduction; this is a feature PR. The linked recording and source inspection provide high-confidence evidence of the new onboarding flow, and current main does not already have that flow.

Review metrics: 2 noteworthy metrics.

• Diff size: 18 files, +3477/-81. The PR spans app lifecycle, SwiftUI UI, settings persistence, provider detection, and tests, so it needs broad maintainer review.
• New onboarding UI files: 4 added SwiftUI files. The first-run experience is a substantial new user-facing surface beyond a narrow settings tweak.

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:

• Get explicit maintainer sign-off on first-run provider/auth defaults after required checks finish.

Mantis proof suggestion
A clean-profile desktop proof would materially help maintainers validate the first-run UI and settings handoff in a real app session. 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 CodexBar first-run onboarding from a clean profile through Finish Setup opens the status menu and persists selected providers/settings.

Risk before merge

• The PR changes first-run provider detection and persisted provider enablement, so maintainers should explicitly approve the provider-selection defaults and auth-routing implications.
• The final onboarding screen defaults quota alerts, provider status checks, and launch-at-login to enabled, which is product behavior rather than a CI-settled correctness question.
• The latest public status for the head commit is pending and the PR mergeable state is unstable, so merge should wait for required checks to finish.

Maintainer options:

1. Land after provider-default sign-off (recommended)
   Maintainers can accept the first-run provider selection and persisted auth-routing behavior once checks finish and product sign-off is explicit.
2. Request upgrade-default proof first
   If maintainers want more confidence, ask for explicit clean-profile and existing-config proof around provider enablement, notification prompting, and launch-at-login defaults.

Next step before merge
The remaining action is maintainer product/upgrade review for first-run provider defaults plus waiting for required checks, not an automated code repair.

Security
Cleared: No concrete security or supply-chain regression was found; the diff does not add dependencies, workflows, scripts, downloaded code, or secret material.

Review details

Best possible solution:

Land the onboarding feature after maintainer sign-off on first-run provider/auth defaults and completion of the latest required checks.

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

Not applicable as a bug reproduction; this is a feature PR. The linked recording and source inspection provide high-confidence evidence of the new onboarding flow, and current main does not already have that flow.

Is this the best way to solve the issue?

Yes with maintainer sign-off: the branch reuses SettingsStore/provider-detection paths and adds focused regression coverage. The remaining question is approval of first-run defaults and auth/settings behavior, not a concrete patch defect.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P2: This is a normal-priority user-facing feature with bounded but meaningful first-run provider/settings impact.
• merge-risk: 🚨 auth-provider: The PR changes provider access detection, provider enablement persistence, and first-run auth/fetch routing defaults.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (recording): Sufficient recording proof: the prepared contact sheet shows the after-change onboarding flow through Finish Setup and menu opening.
• proof: sufficient: Contributor real behavior proof is sufficient. Sufficient recording proof: the prepared contact sheet shows the after-change onboarding flow through Finish Setup and menu opening.
• proof: 🎥 video: Contributor real behavior proof includes video or recording evidence. Sufficient recording proof: the prepared contact sheet shows the after-change onboarding flow through Finish Setup and menu opening.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was present and read fully; its guidance on focused tests, UI/runtime validation, provider data isolation, and auth-sensitive review applies to this onboarding/provider-settings PR. (AGENTS.md:1, 83ed8e405541)
• Current main lacks first-run onboarding: A current-main search found no first-run onboarding flow; only docs/test wording and Antigravity-specific onboarding logging matched. (83ed8e405541)
• App lifecycle wiring: The PR routes launch through status-controller setup, onboarding display, and conditional startup notification authorization. (Sources/CodexBar/CodexbarApp.swift:379, eddfaba1f7e3)
• Provider enablement persistence: Onboarding completion applies provider detection results to persisted provider configs and marks detection complete. (Sources/CodexBar/SettingsStore+ProviderDetection.swift:110, eddfaba1f7e3)
• Regression coverage: SettingsStore tests cover selected-provider persistence, unavailable default-enabled Codex being disabled when another provider is selected, preview ordering, and notification prompt persistence. (Tests/CodexBarTests/SettingsStoreTests.swift:324, eddfaba1f7e3)
• Real behavior proof inspected: The prepared MP4 manifest and contact sheet show the after-change onboarding flow through permissions, access scan, provider selection, appearance, final settings, Finish Setup, and menu opening. (/home/runner/work/clawsweeper/clawsweeper/artifacts/event/codex/proof-scratch/1194/media-proof-manifest.json:1, eddfaba1f7e3)

Likely related people:

• Peter Steinberger: Local blame and current-main history route the SettingsStore initialization, provider detection, and app lifecycle paths through Peter’s imported v0.30-era history and current main commits. (role: current area history owner; confidence: medium; commits: 81cf30a6d5e1, 83ed8e405541; files: Sources/CodexBar/SettingsStore.swift, Sources/CodexBar/SettingsStore+ProviderDetection.swift, Sources/CodexBar/CodexbarApp.swift)
• 陳柏瑋: GitHub file history shows recent Antigravity OAuth/provider-detection work touching the provider-detection area that this onboarding flow builds on. (role: recent adjacent provider contributor; confidence: medium; commits: e98c8f5e4c0d; files: Sources/CodexBar/SettingsStore+ProviderDetection.swift)
• Yuxin Qiao: GitHub file history shows recent SettingsStore work in the same settings/defaults surface affected by onboarding persistence. (role: recent settings contributor; confidence: low; commits: e9b7e25f851b; files: Sources/CodexBar/SettingsStore.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