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: found issues before merge. Reviewed June 27, 2026, 7:40 PM ET / 23:40 UTC.

Summary
The branch redesigns the SetupEngine WSL gateway onboarding into a stepped brand-themed flow, moves permissions into the capabilities screen, restyles progress/wizard/complete pages, adds a DEBUG-only setup preview route, and commits screenshot proof assets.

Reproducibility: yes. for the review finding from source: the default config keeps SkipWizard=false and SkipPermissions=false, the PR adds inline permissions before install, and the wizard success path still routes to the standalone permissions page. I did not run the WinUI flow in this read-only review.

Review metrics: 2 noteworthy metrics.

• Changed Setup Surface: 27 files changed; +1193/-467. The PR rewrites core first-run setup UI paths, so route contracts and proof matter before merge.
• Committed Proof Assets: 11 PNG screenshots added. The screenshots are useful real-behavior proof and also become the evidence maintainers use for accessibility review.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

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

Rank-up moves:

• Remove the duplicate post-wizard permissions page or remove the inline permissions step, then update proof for the default setup path.
• [P2] Refresh steady-state light/dark/high-contrast screenshots for primary-button contrast after the routing fix.

Mantis proof suggestion
A visual setup pass would materially help verify the broad onboarding redesign, permission routing, contrast, 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 through the default flow, confirming permissions are not shown twice and light/dark/high-contrast buttons remain readable.

Risk before merge

• [P1] The default first-run path can show the user a permissions review before install and then the legacy standalone permissions page again after the gateway wizard.
• [P1] Moving permission review into capabilities changes the normal onboarding sequence and still needs maintainer UX/product acceptance before merge.
• [P1] The committed screenshots still show dark text on red primary buttons in some frames while the PR body calls this a capture artifact, so refreshed steady-state accessibility proof would reduce merge risk.

Maintainer options:

1. Converge Permission Routing (recommended)
   Before merge, choose inline permissions or the standalone page as the single normal-flow permission review and add proof for the default SkipWizard=false, SkipPermissions=false path.
2. Accept Duplicate Review Explicitly
   Maintainers could intentionally accept two permission screens, but the PR body, screenshots, and tests should then describe that as the intended UX.
3. Pause The Broad Redesign
   If the onboarding direction is not ready, keep the draft paused or split preview routing, permission timing, and visual restyling into narrower PRs.

Next step before merge

• [P2] The next step is maintainer/product review plus a contributor fix for permission routing; automation should not choose the final onboarding UX direction for this draft PR.

Security
Cleared: The diff is setup-UI focused and the DEBUG-only preview route does not change release credential storage, gateway protocol, dependency sources, CI, or install script execution paths.

Review findings

• [P1] Remove the duplicate permissions stop after the wizard — src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs:126

Review details

Best possible solution:

Keep exactly one permissions review in the normal onboarding path, preserve the existing setup guard and wizard contracts, then land only after maintainer UX approval and current-head visual/setup proof.

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

Yes for the review finding from source: the default config keeps SkipWizard=false and SkipPermissions=false, the PR adds inline permissions before install, and the wizard success path still routes to the standalone permissions page. I did not run the WinUI flow in this read-only review.

Is this the best way to solve the issue?

No, not yet: the redesign may be a good direction, but the current patch does not fully remove or replace the standalone permissions stop and still needs maintainer approval for the permission-timing change.

Full review comments:

• [P1] Remove the duplicate permissions stop after the wizard — src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs:126
  This PR adds Windows permissions as step 2 before installation, but the default setup config still runs the gateway wizard with SkipPermissions=false, and successful wizard completion still navigates to the standalone PermissionsPage. Normal first-run users will review permissions before install and then see the legacy permissions page again, so choose one permission surface and update the default route/proof accordingly.
  Confidence: 0.88

Overall correctness: patch is incorrect
Overall confidence: 0.84

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P2: This is a meaningful setup UX PR with a concrete default-flow blocker, but it is still an unmerged draft rather than a live user regression.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (screenshot): The PR body and committed screenshots show the redesigned pages plus a live gateway onboard walkthrough; refreshed steady-state contrast proof would help, but real visual proof is present.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
• remove status: 👀 ready for maintainer look: Current PR status label is status: ⏳ waiting on author.
• remove P1: Current review triage priority is P2, so this older priority label is no longer current.
• remove merge-risk: 🚨 availability: Current PR review merge-risk labels are merge-risk: 🚨 compatibility.

Label justifications:

• P2: This is a meaningful setup UX PR with a concrete default-flow blocker, but it is still an unmerged draft rather than a live user regression.
• merge-risk: 🚨 compatibility: The PR changes the normal first-run onboarding sequence and permission-review timing that existing setup users experience.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (screenshot): The PR body and committed screenshots show the redesigned pages plus a live gateway onboard walkthrough; refreshed steady-state contrast proof would help, but real visual proof is present.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body and committed screenshots show the redesigned pages plus a live gateway onboard walkthrough; refreshed steady-state contrast proof would help, but real visual proof is present.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body and committed screenshots show the redesigned pages plus a live gateway onboard walkthrough; refreshed steady-state contrast proof would help, but real visual proof is present.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully, and its onboarding proof and required setup validation guidance applies to this PR review. (AGENTS.md:1, d08a3e749973)
• PR scope: GitHub reports 27 changed files with 1193 additions and 467 deletions on head 6d89068, including SetupEngine UI pages and 11 committed PNG proof assets. (6d8906871941)
• Default setup path still includes wizard and permissions: The current default setup config has SkipPermissions=false and SkipWizard=false, so the normal first-run path exercises both the wizard and permission routing. (src/OpenClaw.SetupEngine/default-config.json:16, d08a3e749973)
• Inline permissions added before install: The PR's capabilities flow routes from step 1 into the new Windows permissions step when SkipPermissions is false. (src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs:126, 6d8906871941)
• Post-wizard route still shows standalone permissions: The PR head still sends successful wizard completion to NavigateToPermissions() whenever SkipPermissions is false, so the newly inline permission review is duplicated on the default path. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:236, 6d8906871941)
• Proof inspected: Downloaded PR screenshots include the redesigned capabilities page and a gateway onboard walkthrough with live gateway output; the proof is useful, but some frames still show dark text on red buttons. (docs/onboarding-redesign/10-onboard-4-web-search.png, 6d8906871941)

Likely related people:

• bkudiess: Recent merged history by this author changed the gateway wizard protocol handling and preserved wizard option wire values in the same SetupEngine UI path. (role: recent setup wizard feature-history owner; confidence: high; commits: 84d2e6ab80c8, 1e6951331f1c, b90ded9a5eea; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine/WizardAnswerBuilder.cs, tests/OpenClaw.SetupEngine.Tests/WizardAnswerBuilderTests.cs)
• christineyan4: Recent merged work fixed install wizard rendering in the same WizardPage area, making this a useful routing candidate for onboarding review context. (role: recent adjacent contributor; confidence: medium; commits: 992da748c31b; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs)
• ranjeshj: Recent merged setup/tray UX work added the direct onboarding guard and contract coverage that this PR explicitly preserves. (role: recent adjacent owner; confidence: medium; commits: 429be9ba9368; files: src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs, src/OpenClaw.Tray.WinUI/App.xaml.cs, tests/OpenClaw.Tray.Tests/AppRefactorContractTests.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.