fix(onboarding): clarify native gateway update guidance

[natalie-aguinaldo]

What Problem This Solves

Fixes unclear Windows update instructions when native Gateway support is unavailable during onboarding.

User Impact

Users receive three readable, selectively emphasized paragraphs in all six supported languages, including selecting 26H1 under Advanced options, the clean reinstall required to return to 25H2/26H2, device-dependent feature availability, and reopening setup to recheck after updating. Companion does not enroll the device or change Windows update settings automatically.

Why This Change Was Made

Replaces pinned build-number guidance with rollout-aware Windows 11, version 26H1 instructions while retaining the live capability probe as the admission authority. Localized emphasis preserves the complete screen-reader text and safely falls back to plain rendering if translation tokens drift. Architecture and onboarding documentation match the same contract.

Follow-up 3dcf88a1 addresses the adversarial review: enrollment trade-offs, restored recheck guidance, localized copy checks, real WinUI rendering/accessibility-reset coverage, and production rendering in the gallery.

Evidence

Seven real WinUI tests verify complete paragraph text, all six emphasized spans, automation peer names, idempotent rendering, and rich/plain transitions. Six localized copy cases guard the new enrollment, reinstall, rollout, and reopen instructions. The follow-up rubber-duck review found no blocking issue; runtime tests resolved its speculative Text/Inlines and automation-sentinel concerns.

The author's earlier full-window screenshot applies to 3c1e7ff before the follow-up, not the current wording. Current-change renderer evidence is below.

Change Type

• Bug fix
• Feature
• Refactor
• Docs or instructions
• Tests or validation
• Security hardening
• Chore or infrastructure

Scope

• Tray or WinUI UX
• Windows node capability
• Local MCP or winnode
• Gateway, connection, or pairing
• Setup or onboarding
• Permissions, privacy, or security
• Tests, CI, or docs

Required proof pools

• windows-winui-interactive: native Gateway unavailable-state copy and accessibility. Current-change real WinUI control proof collected; full Welcome-window/Narrator proof was not rerun.

Validation

Final source state committed as 3dcf88a1dd8722f969a13bed63776ae21fc20f98, validated locally on native Windows ARM64:

• .\build.ps1: passed, all projects.
• dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore --logger 'console;verbosity=minimal': 4,260 passed, 34 skipped, 0 failed.
• dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore --logger 'console;verbosity=minimal': 4,002 passed, 0 skipped, 0 failed.
• .\scripts\run-proof-tests.ps1 -Project 'tests\OpenClaw.Tray.UITests\OpenClaw.Tray.UITests.csproj' -Filter 'FullyQualifiedName~NativeGatewayEligibilityTextTests' -ResultName 'native-gateway-guidance' -RuntimeIdentifier win-arm64: 7 passed, 0 skipped, 0 failed, including a visible-testhost rerun.
• git diff --cached --check: passed before commit.

OPENCLAW_REPO_ROOT pointed at this worktree; OPENCLAW_TRAY_DATA_DIR used isolated test directories. The capture run also set OPENCLAW_UI_PROOF_DIR, SLOW_UI_TESTS=1, and SLOW_UI_STEP_MS=1. Initial missing Shared test assets were restored. An attempted broad friend-assembly grant caused a duplicate linked-type compilation error and was removed; tests now bind only the production methods under test. All required commands were rerun successfully after corrections.

The author's earlier Dev MSIX packaging result applies to 3c1e7ff0; Dev MSIX packaging was not rerun for this follow-up.

Real Behavior Proof

• Environment tested: native Windows ARM64, .NET 10.0.401 SDK, real WinUI test host with compiled product resources and isolated settings.
• PR head or commit tested: final source state committed as 3dcf88a1dd8722f969a13bed63776ae21fc20f98.
• Exact steps or command run: focused run-proof-tests.ps1 command above; production Apply/ApplyPlain invoked on real TextBlock controls.
• Evidence after fix: current-change renderer capture and runtime diagnostics below.
• Observed result: all three paragraphs preserved, 12 runs with 6 semibold spans, full automation name preserved, and rich/plain reset cases passed.
• Screenshot or artifact links verified? (Yes/No/N/A): Yes. Downloaded the attached image after posting and verified its SHA-256 matches the inspected local image.
• Not verified or blocked: no new full Welcome-window screenshot, Narrator session, Dev MSIX installation, or real Insider enrollment. This control-level proof does not claim complete interactive proof-pool coverage or validate the product's future rollout promise.

Copied runtime output:

Runs=12; semibold=6; automation name matches full localized text.
Proof tests reported: total=7; Passed=7

The following is a RenderTargetBitmap of the production-rendered, test-hosted TextBlock. Transparent pixels were composited onto white for legibility; it is not a full app-window screenshot.

Security Impact

• New permissions or capabilities? (Yes/No): No
• Secrets or tokens handling changed? (Yes/No): No
• New or changed network calls? (Yes/No): No
• Command or tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any answer is Yes, explain the risk and mitigation: N/A

Compatibility and Migration

• Backward compatible? (Yes/No): Yes
• Config or environment changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, list the exact upgrade steps: N/A. The documented Windows enrollment choice is user-controlled, not an application migration.

Review Conversations

• I replied to or resolved every bot review conversation addressed by this PR.
• I left unresolved only conversations that still need maintainer judgment.

The follow-up comment records the three addressed review concerns and current validation. No formal approval or merge was performed.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed October 7, 2026, 12:45 PM ET / 16:45 UTC (Revision 6).

ClawSweeper review

What this changes

The PR clarifies native Gateway update guidance in six languages, adds accessible text emphasis, and expands onboarding documentation and rendering tests.

Merge readiness

✅ Ready for maintainer review

This PR remains useful: main and the latest release retain the older build-number guidance. The prior copy concerns and merge conflict are resolved, and no introduced correctness defect was found.

Priority: P3
Reviewed head: 497c7dd21490e9ec6430d8d7f51ff9d325224877

Review scores

Measure	Result	What it means
Overall readiness	🦞 diamond lobster (5/6)	Focused implementation, inspected real WinUI evidence, localized regression checks, and addressed review feedback provide strong review confidence.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (screenshot): The inspected production-rendered TextBlock capture and native ARM64 runtime diagnostics demonstrate the revised paragraphs, six emphasized spans, complete automation text, and rich/plain resets. Those production files are unchanged at the merged head. Full-window and Narrator coverage are explicitly unclaimed; no stored-data contract changes.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (screenshot): The inspected production-rendered TextBlock capture and native ARM64 runtime diagnostics demonstrate the revised paragraphs, six emphasized spans, complete automation text, and rich/plain resets. Those production files are unchanged at the merged head. Full-window and Narrator coverage are explicitly unclaimed; no stored-data contract changes.
Evidence reviewed	8 items	Policy and review boundary: Read the complete root AGENTS.md and applicable proof-validation skill. No nested AGENTS.md or maintainer-notes directory was found. Applied architecture, localization, accessibility, and proof guidance; no builds, tests, reviewer helpers, or mutations were performed. Introduced implementation: The pinned introduced delta adds localized emphasis with plain-text fallback and clears accessibility overrides on plain transitions. Eligibility evaluation, gateway selection, and Windows Update launching remain unchanged. Still necessary on main and release: Both fetched main and v2026.9.8 still format the unavailable message using the pinned InsiderBuild value. Neither contains the proposed rich-text renderer.
Findings	None	None.
Security	None	None.

How this fits together

The onboarding Welcome page checks whether Windows supports a local native Gateway. That result controls gateway choices and the update guidance shown to users.

flowchart TD
 A[Welcome page] --> B[Windows capability probe]
 B --> C[Support result]
 C --> D[Gateway choices]
 C --> E[Localized guidance]
 E --> F[Accessible text rendering]
 F --> G[Windows Update action]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	production +154 net lines; tests +247 net lines	Production growth supports localized emphasis and reset handling, with larger regression coverage for the new rendering behavior.

Technical review

Best possible solution:

Keep capability-based admission and present clear, localized update guidance with enrollment consequences and accessible rendering.

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

Not applicable to this guidance improvement. Current main's older copy is directly inspectable, and the supplied native WinUI evidence demonstrates the revised rendering.

Is this the best way to solve the issue?

Yes. The focused presentation helper preserves complete localized text and accessibility while leaving capability checks and user-controlled Windows settings intact.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 5e3fb40bcc89.

Labels

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P3: This improves optional native Gateway onboarding guidance without changing capability admission or blocking the existing WSL and external Gateway paths.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The inspected production-rendered TextBlock capture and native ARM64 runtime diagnostics demonstrate the revised paragraphs, six emphasized spans, complete automation text, and rich/plain resets. Those production files are unchanged at the merged head. Full-window and Narrator coverage are explicitly unclaimed; no stored-data contract changes.
• proof: sufficient: Contributor real behavior proof is sufficient. The inspected production-rendered TextBlock capture and native ARM64 runtime diagnostics demonstrate the revised paragraphs, six emphasized spans, complete automation text, and rich/plain resets. Those production files are unchanged at the merged head. Full-window and Narrator coverage are explicitly unclaimed; no stored-data contract changes.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The inspected production-rendered TextBlock capture and native ARM64 runtime diagnostics demonstrate the revised paragraphs, six emphasized spans, complete automation text, and rich/plain resets. Those production files are unchanged at the merged head. Full-window and Narrator coverage are explicitly unclaimed; no stored-data contract changes.

Evidence

What I checked:

• Policy and review boundary: Read the complete root AGENTS.md and applicable proof-validation skill. No nested AGENTS.md or maintainer-notes directory was found. Applied architecture, localization, accessibility, and proof guidance; no builds, tests, reviewer helpers, or mutations were performed. (AGENTS.md, 497c7dd21490)
• Introduced implementation: The pinned introduced delta adds localized emphasis with plain-text fallback and clears accessibility overrides on plain transitions. Eligibility evaluation, gateway selection, and Windows Update launching remain unchanged. (src/OpenClaw.SetupEngine.UI/NativeGatewayEligibilityText.cs:30, 497c7dd21490)
• Still necessary on main and release: Both fetched main and v2026.9.8 still format the unavailable message using the pinned InsiderBuild value. Neither contains the proposed rich-text renderer. (src/OpenClaw.SetupEngine.UI/NativeGatewayEligibilityText.cs:8, 5e3fb40bcc89)
• Prior review follow-ups: The collaborator's follow-up at fix(onboarding): clarify native gateway update guidance #1654 (comment) records Advanced options, the clean-reinstall warning, restored recheck instructions, localized checks, and seven real WinUI tests. These changes are present in the reviewed delta. (src/OpenClaw.Tray.WinUI/Strings/en-us/Resources.resw:7780, 497c7dd21490)
• Inspected real rendering proof: Inspected both prepared images. The newer attachment, https://github.com/user-attachments/assets/6ade0064-7155-40a5-b37a-b4995adec812, visibly shows the revised paragraphs and emphasis. The captured body associates it with production rendering on native Windows ARM64 and reports 12 runs, six semibold spans, complete automation text, and seven passing WinUI tests. It expressly excludes full-window, Narrator, and Insider-enrollment claims. (tests/OpenClaw.Tray.UITests/NativeGatewayEligibilityTextTests.cs:18, 3dcf88a1dd87)
• Proof continuity after merge: Comparison against the previously proven commit shows no changes to the renderer, emphasis helper, Welcome page, localized resources, or focused rendering tests. The verified test merge has the pinned main and head as its two parents, resolving the former conflict concern without attributing incoming main work to this PR. (src/OpenClaw.SetupEngine.UI/NativeGatewayEligibilityText.cs:30, 497c7dd21490)

Likely related people:

• Karen: Raw commit dba8121 adds src/OpenClaw.SetupEngine/NativeGatewaySetupEligibility.cs:16 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: dba81213371c; files: src/OpenClaw.SetupEngine/NativeGatewaySetupEligibility.cs)
• RomneyDa: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (5 earlier review cycles)

• reviewed 2026-10-06T23:17:30.001Z sha 3c1e7ff :: needs maintainer review before merge. :: none
• reviewed 2026-10-06T23:21:41.793Z sha 3c1e7ff :: needs maintainer review before merge. :: none
• reviewed 2026-10-07T15:09:09.264Z sha 3c1e7ff :: needs changes before merge. :: [P2] Complete the 26H1 enrollment instructions before recommending it
• reviewed 2026-10-07T15:43:23.264Z sha 3dcf88a :: needs changes before merge. :: none
• reviewed 2026-10-07T16:06:29.820Z sha 3dcf88a :: needs changes before merge. :: none

[karkarl]

Adversarial dual-model review

Verdict: approve with nits. No blocking correctness findings. Claude Opus 5.5 and GPT-6 Astra independently reviewed all 17 changed files using the same brief, then their findings were reconciled.

Reviewed head: 3c1e7ff065542d73d669969f74636a1a5671c16e, against merge base 791574ddf557aeed3b6aceb36827bada9de8633b.

Both reviewers found the rendering/fallback logic, complete localized text preservation, automation-name resets, and unchanged capability admission sound at source level. Opus raised the non-blocking concerns below; GPT reported no actionable findings.

Both models agree: HIGH consensus

Issue	Opus	GPT	Fix confidence
No shared actionable findings	None	None	N/A

Only one model flagged: LOW consensus

Consensus describes reviewer agreement, not severity. Fix confidence estimates confidence in the proposed remediation.

Issue	Opus	GPT	Fix confidence
26H1 guidance omits the Advanced options step and clean-reinstall consequence	MEDIUM	—	90%
Removed instruction to reopen setup after updating	LOW	—	99%
Automated real-TextBlock rich/plain transition coverage is missing; initial-render concern partially disputed by existing screenshot	LOW	—	90%

1. Clarify the enrollment trade-off. The new guidance, repeated across six locales and the docs, directs users to 26H1 without mentioning Advanced options or that returning to 25H2/26H2 requires a clean reinstall. Microsoft's current flighting documentation confirms both facts. Consider adding the selection step and a brief warning or explanatory link. This is a guidance concern, not a claim that 26H1 Insider enrollment is unavailable: the documented Beta/Experimental route does exist. The live capability gate remains authoritative. The universal "coming soon to all devices" promise was not independently verified, but no evidence establishes it as false.

2. Restore the recheck instruction. The same resource replacement removes "then reopen this page," although reopening remains the documented way to rerun the probe and Welcome has no Check again button. A short sentence would preserve discoverability. Impact is low, especially when a Windows update already requires restarting.

3. Optional runtime regression coverage, not a demonstrated defect. The gallery test substitutes synthetic plain text rather than exercising the real renderer. However, the existing author-provided screenshot, inspected during reconciliation, already demonstrates the three paragraphs, selective emphasis, and Windows Update action. That resolves the suggestion to obtain initial-render screenshot proof. A WinUI test checking joined inline text and automation-name clearing across rich/plain transitions would still improve regression protection.

Verification

• 27 passed, 0 failed, 0 skipped: dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --filter "FullyQualifiedName~NativeGatewayEmphasisRangesTests|FullyQualifiedName~NativeGatewaySetupUxContractTests" --logger "console;verbosity=normal". OPENCLAW_REPO_ROOT was set to this worktree and OPENCLAW_TRAY_DATA_DIR to an isolated review directory. The initial --no-restore attempt failed because the fresh worktree lacked assets; the successful command restored them.
• Passed: git --no-pager diff --check 791574ddf557aeed3b6aceb36827bada9de8633b..HEAD.
• Existing CI verified: run 37545220960 completed successfully for the exact reviewed head.
• This review did not rerun the full local build, complete Shared/Tray suites, live UI, or Narrator. The screenshot is author-supplied evidence, not a newly captured runtime check. No source changes were made.

[karkarl]

Implemented the review follow-ups in 3dcf88a1, pushed to this PR's existing branch.

• All six locales now explain selecting 26H1 under Advanced options, the clean reinstall required to return to 25H2/26H2, device-dependent feature availability, and reopening setup after updating.
• Added localized copy regression checks and seven real WinUI tests covering complete paragraph text, six emphasized spans, the automation peer's name, repeated rendering, and rich/plain resets. The gallery now uses the production renderer instead of synthetic text.
• Updated the three related architecture/onboarding documents. The live capability gate is unchanged.

Validation: full .\build.ps1 passed; Shared tests 4,260 passed / 34 skipped / 0 failed; Tray tests 4,002 passed / 0 failed; focused WinUI tests 7 passed / 0 skipped / 0 failed. Rubber-duck follow-up found no blocking issue; its speculative Text/Inlines and automation-sentinel concerns were resolved by the passing runtime tests.

Current-change UI evidence: the production renderer and compiled product resources ran on real native ARM64 WinUI controls. The capture below is a RenderTargetBitmap of the test-hosted TextBlock, with transparent pixels composited onto white for legibility. It is not a full Welcome-window screenshot or Windows enrollment proof. The runtime also reported Runs=12; semibold=6; automation name matches full localized text. Full Welcome-window/Narrator proof and real Insider enrollment were not rerun.

[karkarl]

Global triage: HOLD_FOR_AUTHOR. Take confidence 10%; recommendation confidence 99%; effort medium; risk high.

Reviewed exact head 497c7dd21490. GitHub currently reports BLOCKED with 22 passing, 1 failing, and 0 pending checks. proof label is sufficient. Durable automated signal: Codex review: needs maintainer review before merge..

Author: update from current main, resolve conflicts or branch-policy blockers, then rerun exact-head validation and request review.

This is a triage classification, not a merge action. No branch changes were made.