Redesign WSL gateway onboarding (stepped, brand-themed, accessible)

[bkudiess]

Draft for review/testing. Presentation-only redesign of the WSL gateway onboarding — no changes to connection, pairing, the install pipeline, credentials, or the gateway protocol.

Rebased onto main and retargeted from master → main (the repo default). Preserves current-main TryNavigateToWizard/CanNavigateToWizard guards and WizardOptionValue wire-value handling. Squashed to one commit; build + SetupEngine (282) / Tray (1123) / Shared (2370) tests green.

What this is

A redesign of the OpenClaw setup/onboarding flow with a power-user lens: clearer, fewer clicks, transparent about what gets installed, brand-themed, and theme-aware (light + dark). The gateway-onboard step reads as a vertical transcript, and the pre-install screen is a short stepped flow that ends in install.

Try it

./build.ps1
$env:OPENCLAW_FORCE_ONBOARDING="1"; ./run-app-local.ps1 -NoBuild -Isolated -AllowNonMaster

Dev-only preview route to jump straight to any screen without a real install (gated to DEBUG builds — inert in Release):

$env:OPENCLAW_SETUP_PREVIEW_PAGE="welcome"   # or: capabilities | progress | wizard | permissions | complete

Screens

1 · Welcome — chooser

2 · Capabilities — stepped flow (steps accrete with checkmarks, like the onboard)

Step 1 — what your agent can do

Step 2 — Windows permissions (merged in from the old standalone step)

Step 3 — review & install

3 · Gateway onboard — vertical transcript

Real end-to-end onboarding walkthrough

Captured from an actual install + gateway onboard run. The transcript accretes as each gateway question is answered, and the active step is always shown with its title.

Onboard begins
Setup mode (transcript building)
Copilot auth method
Web search (with live gateway output)

4 · Progress — tighter steps + "Live activity" ledger that flows below them

5 · All set

Notable changes

• Welcome chooser — Install a local gateway (WSL, recommended) vs. Connect to an existing gateway.
• Merged permissions — "Grant permissions" now lives inline on the capabilities screen; each OS permission row shows only when its capability is enabled. Honors SetupConfig.SkipPermissions (hides the step). The standalone permissions page is dropped from the flow (kept for the preview route).
• Stepped, accreting capabilities flow — each step collapses into a green-checkmark summary above the active step, matching the gateway-onboard transcript.
• Gateway onboard — vertical transcript; auto-scroll keeps the active step's title in view (so long option lists no longer hide the intro).
• Progress — step rows tightened; the "Live activity" ledger flows directly below the steps and opens downward instead of being pinned to the window bottom.
• Brand-red accent, scoped to the setup window only (light + dark). Filled controls (buttons, radios, checkboxes, toggles) use WCAG-AA reds (white text ≥ 5:1). The bright coral #FF5C5C failed AA at 3.03:1, so it's retained only for accent text/links.
• Shared SetupPermissionHelper used by both surfaces; removed the "what changed / how to undo" expander from the Complete page.

Validation

• build.ps1 ✅
• Tests: SetupEngine 282 · Tray 1123 · Shared 2370 — all green, no regressions.

Note on an earlier automated review: the committed step-2/step-3 proof images showed the primary button with dark text on red. That is a capture artifact — those frames were grabbed during a window re-activation flash (and the real-onboard shots during a Teams call). In steady state the button renders white text on red (verified at rest and via UI-Automation navigation: ~247 luminance). No styling defect; the accent foreground override works. Screenshots can be refreshed if desired.

Screenshots are also committed under docs/onboarding-redesign/ (visible in the Files changed tab).

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 23, 2026, 2:58 AM ET / 06:58 UTC.

Summary
The branch redesigns the SetupEngine WSL gateway onboarding into a stepped brand-themed flow, merges permissions into capabilities, adds a DEBUG-only setup preview route, and commits onboarding screenshots.

Reproducibility: not applicable. as a feature PR rather than a bug report. The PR body and screenshots give a real-behavior proof path, and source inspection verified the earlier setup-contract regressions are no longer present on the latest head.

Review metrics: 2 noteworthy metrics.

• Changed Setup Surface: 27 files changed; 1200 additions, 476 deletions. The PR rewrites core first-run setup UI paths, so source-level contract checks and real setup proof matter before merge.
• Committed Proof Assets: 11 PNG screenshots added. The screenshots provide useful visual proof, but they also become reviewer-facing artifacts for contrast and accessibility review.

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:

• [P2] Refresh or add steady-state visual proof for primary-button contrast across light, dark, and high-contrast themes.
• [P2] Get maintainer acceptance for the permissions-in-capabilities flow before merge.

Mantis proof suggestion
A real visual pass would materially help maintainers evaluate this broad first-run setup redesign across themes and keyboard flow. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: verify the WSL setup onboarding redesign in light, dark, and high-contrast themes, including keyboard navigation and the gateway onboard transcript.

Risk before merge

• [P1] The branch changes the normal first-run setup journey and moves permission review before install/wizard completion, so maintainers need to accept that UX and upgrade expectation explicitly.
• [P1] The committed screenshots still show dark text on red primary buttons in some frames while the PR body says this was a capture artifact; refreshed steady-state visual/accessibility proof would reduce merge risk.
• [P1] This read-only review did not independently run the AGENTS.md build and test commands, so merge should still rely on CI or maintainer validation for the exact head.

Maintainer options:

1. Run A Maintainer Visual Setup Pass (recommended)
   Review the latest head in a real setup across light, dark, high-contrast, and keyboard flows, and refresh proof for steady-state primary-button contrast before merge.
2. Accept The Permission Timing Change
   Maintainers can intentionally accept that permissions are reviewed inline before installation rather than as a standalone post-wizard step.
3. Pause The Broad Redesign
   If the UX direction is not ready, keep this draft paused or ask for narrower PRs that split preview routing, permission merging, and visual restyling.

Next step before merge

• [P2] The remaining action is maintainer UX/product approval and real setup validation, not a narrow automated code repair.

Security
Cleared: The diff adds a DEBUG-only preview env route and passive permission display without changing credential storage, gateway protocol, install sources, or CI/dependency execution paths.

Review details

Best possible solution:

Land the redesign only after maintainers accept the onboarding UX and permissions timing, verify the real setup flow/accessibility, and keep the current setup guard, retry, and typed wizard-answer contracts intact.

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

Not applicable as a feature PR rather than a bug report. The PR body and screenshots give a real-behavior proof path, and source inspection verified the earlier setup-contract regressions are no longer present on the latest head.

Is this the best way to solve the issue?

Unclear until maintainer review: the implementation now preserves the important current-main setup contracts, but the broad UX, permissions timing, and accessibility direction still need product acceptance.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 260fb90c6dc7.

Label changes

Label changes:

• add P2: This is a normal-priority first-run setup UX improvement with meaningful review surface but no confirmed current blocking defect after the latest head update.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The PR body and committed PNGs show the redesigned pages plus a real install/gateway-onboard walkthrough; refreshed contrast proof would help, but proof is sufficient for the visible UI change.
• remove rating: 🧂 unranked krab: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.
• remove P1: Current review triage priority is P2, so this older priority label is no longer current.

Label justifications:

• P2: This is a normal-priority first-run setup UX improvement with meaningful review surface but no confirmed current blocking defect after the latest head update.
• merge-risk: 🚨 compatibility: The PR changes the normal onboarding sequence and permission-review timing that users and docs currently experience.
• merge-risk: 🚨 availability: The diff touches setup progress and gateway wizard navigation paths that can block first-run setup if the new flow regresses.
• 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 (screenshot): The PR body and committed PNGs show the redesigned pages plus a real install/gateway-onboard walkthrough; refreshed contrast proof would help, but proof is sufficient for the visible UI change.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body and committed PNGs show the redesigned pages plus a real install/gateway-onboard walkthrough; refreshed contrast proof would help, but proof is sufficient for the visible UI change.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body and committed PNGs show the redesigned pages plus a real install/gateway-onboard walkthrough; refreshed contrast proof would help, but proof is sufficient for the visible UI change.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its setup/onboarding guidance and validation expectations informed the review, while the read-only ClawSweeper contract prevented running build/tests. (AGENTS.md:1, 260fb90c6dc7)
• PR source preserves direct wizard guard: The latest PR head keeps CanNavigateToWizard, TryNavigateToWizard, and the guarded NavigateToWizard wrapper that current tray code expects. (src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs:103, 5e5a0e3991d6)
• PR source preserves wizard retry and typed option values: The latest PR head calls CancelCurrentSessionAsync before wizard.start and uses WizardAnswerBuilder/WizardOptionValue.RawValue for select and multiselect answers. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:94, 5e5a0e3991d6)
• Permissions timing changed: The PR moves permission review into CapabilitiesPage before install and skips the standalone PermissionsPage on normal success paths. (src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml.cs:131, 5e5a0e3991d6)
• Proof inspected: Downloaded PR screenshots include visible welcome/progress/complete pages and a real gateway-onboard walkthrough; one inspected onboard image shows the transcript and live gateway output. (docs/onboarding-redesign/10-onboard-4-web-search.png, 5e5a0e3991d6)
• Feature history provenance: History ties the setup guard to 429be9b, typed wizard values to b90ded9, retry cancellation to 80029fe, and the original setup UI baseline to 8bcd0f3. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:94, 260fb90c6dc7)

Likely related people:

• bkudiess: Prior current-main work by this contributor preserved wizard option wire values in the same gateway setup path, and the current PR builds directly on that behavior. (role: feature-history owner; confidence: high; commits: b90ded9a5eea; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine/WizardAnswerBuilder.cs, tests/OpenClaw.SetupEngine.Tests/WizardAnswerBuilderTests.cs)
• ranjeshj: Recent merged setup/tray UX work introduced the direct onboarding guard and contract-test coverage that this PR must preserve. (role: recent adjacent owner; confidence: high; commits: 429be9ba9368; files: src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs, src/OpenClaw.Tray.WinUI/App.xaml.cs, tests/OpenClaw.Tray.Tests/AppRefactorContractTests.cs)
• AlexAlves87: Blame on the central SetupWindow, WizardPage, CapabilitiesPage, ProgressPage, and PermissionsPage baseline traces much of the original setup UI to this commit. (role: original setup UI contributor; confidence: medium; commits: 8bcd0f399abd; files: src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs, src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs)

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.