docs: rewrite README for clarity and professionalism

[samanthamsong]

Summary

Rewrite the README around the shipped OpenClaw Companion experience. The normal setup path now directs users through Companion Settings, Connection, Sandbox, Permissions, Command Center, and the schema-guided Config page instead of asking them to edit openclaw.json by hand.

Changes

• Keep the pull request scoped to README.md only
• Add concise install links and an app-first Windows node setup flow
• Describe capabilities using the labels shown on the Permissions page
• Explain pairing, reapproval, gateway allowlists, and privacy-sensitive opt-ins
• Correct MXC sandbox and host-fallback guidance
• Keep raw allowlist JSON in a collapsed advanced reference for externally managed gateways
• Summarize features, useful deep links, local data paths, and project ownership
• Correct contributor build, feature-branch launch, linked-worktree, and test commands
• Remove references to outdated screenshots

Validation

• ./build.ps1
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj: 3,399 passed, 32 skipped
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj: 2,037 passed
• Final repository-aware review: clean

Real behavior proof

• Current head: 92f28a424a3c7a8fab66ba23bf86857135d9887a
• The net pull request diff contains only README.md
• The current README was rendered locally in Visual Studio Code to verify Markdown structure and relative links

[clawsweeper]

Codex review: needs changes before merge. Reviewed August 5, 2026, 6:45 PM ET / 22:45 UTC.

ClawSweeper review

What this changes

The PR rewrites the README, adds a title icon, and adds a tray navigation route for a sandbox-session prototype page.

Merge readiness

⛔ Blocked by patch quality or review findings - 4 items remain

Keep open. The current head still references an undefined page type, so it cannot compile. Likely related people: Barbara Kudiess (high confidence) and Karen (medium confidence) from recent tray-window history.

Priority: P2
Reviewed head: 6f61a7a3a1cbf716d43d63bc40a6261e58fa15c7

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	PR readiness rating was derived from proof quality, review findings, security review, and reviewer confidence.
Proof confidence	🌊 off-meta tidepool	Not applicable: Real behavior proof is not required for maintainer- or bot-authored pull requests.
Patch quality	🧂 unranked krab (1/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: Real behavior proof is not required for maintainer- or bot-authored pull requests.
Evidence reviewed	5 items	Undefined page route in PR head: The PR adds a sandbox-sessions route resolving to SandboxSessionPrototypePage, but does not add that page. Current main has no target page: A repository-wide source search found no SandboxSessionPrototypePage definition on current main. Navigation contract: The tray resolves every selected tag through TagToPageType before navigating, so an undefined type is a compile-time failure.
Findings	1 actionable finding	[P1] Remove the nonexistent prototype page route
Security	None	None.

How this fits together

The README guides users and contributors into the Windows companion app. The tray window maps navigation selections to WinUI pages, so each added menu item must resolve to an implemented page.

flowchart LR
  A[User or contributor] --> B[README]
  B --> C[Windows companion setup]
  D[Tray menu selection] --> E[Navigation route]
  E --> F[WinUI page]
  F --> G[Sandbox experience]

Loading

Before merge

• Remove the nonexistent prototype page route (P1) - SandboxSessionPrototypePage is not defined on current main and this PR does not add it. Selecting the new entry therefore cannot resolve a page; remove the route and matching navigation item, or implement and validate the page in a separate UI PR.
• Resolve merge risk (P1) - The PR describes itself as documentation-only although it also changes tray navigation, obscuring the required UI validation and proof scope.
• Complete next step (P2) - Remove the two unrelated navigation lines as a narrow mechanical repair, then review the README rewrite on its own merits.
• Improve patch quality - Address the highest-priority review finding and re-run the changed-surface validation.

Findings

• [P1] Remove the nonexistent prototype page route — src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs:1173

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Changed surface	4 files affected: README and icon, plus 2 tray UI files	The two non-documentation files introduce a runtime dependency outside the stated documentation scope.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Keep the README rewrite scoped to documentation by removing the prototype route and menu item, or submit a separate UI PR that implements and validates the complete page.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Keep the README rewrite scoped to documentation by removing the prototype route and menu item, or submit a separate UI PR that implements and validates the complete page.

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

Yes. Current source lacks the page named by the new route, and building the tray project would establish the resulting compile failure.

Is this the best way to solve the issue?

No. A README-focused PR should not add an unresolved navigation route; remove it or move a complete, validated page into a dedicated UI PR.

Full review comments:

• [P1] Remove the nonexistent prototype page route — src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs:1173
SandboxSessionPrototypePage is not defined on current main and this PR does not add it. Selecting the new entry therefore cannot resolve a page; remove the route and matching navigation item, or implement and validate the page in a separate UI PR.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: The PR has a deterministic, limited-scope tray build blocker that must be corrected before merge.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🌊 off-meta tidepool and patch quality is 🧂 unranked krab.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required for maintainer- or bot-authored pull requests.

Evidence

Acceptance criteria:

• [P1] ./build.ps1.
• [P1] dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore.
• [P1] dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore.

What I checked:

• Undefined page route in PR head: The PR adds a sandbox-sessions route resolving to SandboxSessionPrototypePage, but does not add that page. (src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs:1173, 6f61a7a3a1cb)
• Current main has no target page: A repository-wide source search found no SandboxSessionPrototypePage definition on current main. (d2de6150753b)
• Navigation contract: The tray resolves every selected tag through TagToPageType before navigating, so an undefined type is a compile-time failure. (src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs:1159, d2de6150753b)
• Prior review remains applicable: The prior ClawSweeper review raised this same blocker on the unchanged current PR head. (src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs:1173, 6f61a7a3a1cb)
• Recent area history: Barbara Kudiess and Karen have recent substantive commits on the tray window path. (src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs, d2638ddbef57)

Likely related people:

• Barbara Kudiess: Recent tray refactor and execution-approval work touched the HubWindow navigation path. (role: recent area contributor; confidence: high; commits: d2638ddbef57, 4806eaac7c24; files: src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml, src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs)
• Karen: Recent HubWindow UI work is present in the current history for the affected file. (role: recent area contributor; confidence: medium; commits: ff1901275a41, 4d09797c927f; files: src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs)

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 (1 earlier review cycle)

• reviewed 2026-08-05T21:08:24.820Z sha 6f61a7a :: needs changes before merge. :: [P1] Remove the nonexistent prototype page route