Refresh app and developer documentation (#915)

Update release links, project inventory, connection architecture, MCP mode, Windows node testing, and test coverage docs to match current app behavior.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: shanselman

AGENTS.md

@@ -13,6 +13,8 @@ Required steps:
 3. Run tray tests:
    - `dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore`
 
+This is the required local closeout subset for agents. CI also builds and runs additional connection, setup, CLI, UI, integration, and E2E suites; see `docs/TEST_COVERAGE.md` for the broader inventory.
+
 If a command fails:
 
 1. Fix the issue.

DEVELOPMENT.md

@@ -44,10 +44,18 @@ openclaw-windows-hub/
 │   │   ├── Models.cs                 # Data models (SessionInfo, ChannelHealth, etc.)
 │   │   └── IOpenClawLogger.cs        # Logging interface
 │   │
+│   ├── OpenClaw.Connection/          # Gateway registry, credentials, connection manager
+│   │
 │   ├── OpenClaw.Chat/                # Native chat model and reducer
 │   │   ├── ChatModels.cs             # Threads, entries, events, provider contract
 │   │   └── ChatTimelineReducer.cs    # Timeline state transitions
 │   │
+│   ├── OpenClaw.Cli/                 # WebSocket connect/send/probe validator
+│   │
+│   ├── OpenClaw.WinNode.Cli/         # winnode local MCP/Windows-node CLI
+│   │
+│   ├── OpenClaw.SetupEngine/         # Local WSL gateway setup and setup-code support
+│   │
 │   ├── OpenClawTray.FunctionalUI/    # Small in-repo declarative WinUI helper
 │   │   └── FunctionalUI.cs           # Components, hooks, elements, host control
 │   │
@@ -59,8 +67,12 @@ openclaw-windows-hub/
 │   │   └── Helpers/                  # Icon generation, utilities
 │   │
 ├── tests/
-│   ├── OpenClaw.Shared.Tests/        # Unit tests for shared library
-│   └── OpenClaw.Tray.Tests/          # Tests for tray helpers (menu, settings, deep links)
+│   ├── OpenClaw.Shared.Tests/        # Unit tests for shared library/capabilities/MCP
+│   ├── OpenClaw.Connection.Tests/    # Gateway registry and connection manager tests
+│   ├── OpenClaw.Tray.Tests/          # Tests for tray helpers (menu, settings, deep links)
+│   ├── OpenClaw.WinNode.Cli.Tests/   # winnode CLI contract tests
+│   ├── OpenClaw.SetupEngine.Tests/   # Setup engine tests
+│   └── OpenClaw.Tray.UITests/        # Native WinUI/A2UI UI tests
 │
 ├── tools/
 │   └── icongen/                      # Icon generation tool
@@ -76,16 +88,18 @@ openclaw-windows-hub/
 ### Project Dependencies
 
 ```
-OpenClaw.Tray.WinUI  ──depends on──▶  OpenClaw.Shared
-OpenClaw.Shared.Tests  ──tests──▶  OpenClaw.Shared
-OpenClaw.Tray.Tests  ──tests──▶  OpenClaw.Shared
+OpenClaw.Tray.WinUI  ──depends on──▶  OpenClaw.Shared + OpenClaw.Connection + OpenClaw.Chat
+OpenClaw.WinNode.Cli  ──depends on──▶  OpenClaw.Shared
+OpenClaw.SetupEngine  ──supports──▶  local WSL gateway setup
+OpenClaw.*.Tests  ──test──▶  corresponding shared, connection, tray, setup, and CLI surfaces
 ```
 
 ### Key Subsystems
 
 | Subsystem | Location | Purpose |
 |-----------|----------|---------|
 | **Gateway Communication** | `OpenClaw.Shared/OpenClawGatewayClient.cs` | WebSocket client with protocol v3, reconnect/backoff logic |
+| **Connection Management** | `OpenClaw.Connection/` | Gateway registry, credential precedence, pairing, tunnels, and reconnect policy |
 | **Notification System** | `OpenClaw.Tray.WinUI/App.xaml.cs` | Event routing, toast notifications, classification |
 | **WebView2 Integration** | `OpenClaw.Tray.WinUI/Windows/ChatWindow.xaml.cs` | Embedded chat panel with lifecycle management |
 | **Tray Icon Management** | `OpenClaw.Tray.WinUI/Helpers/IconHelper.cs` | GDI handle management, dynamic icon generation |

README.md

@@ -21,20 +21,24 @@ This monorepo contains the Windows hub, shared client libraries, and CLI utiliti
 | Project | Description |
 |---------|-------------|
 | **OpenClaw.Tray.WinUI** | System tray application (WinUI 3) for quick access to OpenClaw |
-| **OpenClaw.Shared** | Shared gateway client library |
+| **OpenClaw.Connection** | Gateway registry, credential resolution, and connection manager |
+| **OpenClaw.Shared** | Shared gateway client library, capabilities, and MCP bridge |
+| **OpenClaw.Chat** | Native chat model and timeline reducer |
 | **OpenClaw.Cli** | CLI validator for WebSocket connect/send/probe using tray settings |
+| **OpenClaw.WinNode.Cli** | `winnode` CLI for invoking local Windows node/MCP capabilities |
+| **OpenClaw.SetupEngine** | Local gateway setup, WSL installation, and setup-code support |
 
 ## 🚀 Quick Start
 
 > **End-user installer?** Download the latest stable x64 or ARM64 installer from the [OpenClaw Windows docs](https://docs.openclaw.ai/platforms/windows), or see [docs/SETUP.md](docs/SETUP.md) for step-by-step installation (no build required).
 >
 > **Managed WSL gateway?** Local setup creates a locked-down app-owned `OpenClawGateway` distro. See [docs/WSL_GATEWAY_ADMIN.md](docs/WSL_GATEWAY_ADMIN.md) for editing `openclaw.json` as the `openclaw` user and using root for protected-file administration.
 
-Direct downloads from the latest OpenClaw release:
+Direct downloads from the latest OpenClaw Windows release:
 
-- [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-x64.exe)
-- [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-arm64.exe)
-- [OpenClawCompanion-SHA256SUMS.txt](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt)
+- [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-x64.exe)
+- [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-arm64.exe)
+- [OpenClawCompanion-SHA256SUMS.txt](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt)
 
 ### Prerequisites
 - Windows 10 (20H2+) or Windows 11
@@ -54,6 +58,9 @@ Use the setup script to install or verify local Windows build prerequisites:
 # Check only; do not install packages or change git safe.directory
 .\scripts\setup-dev.ps1 -CheckOnly
 
+# Install/verify prerequisites without adding the checkout to git safe.directory
+.\scripts\setup-dev.ps1 -NoTrustRepository
+
 # Setup and run the required build/test validation
 .\scripts\setup-dev.ps1 -RunValidation
 ```

build.ps1

@@ -6,7 +6,7 @@
     Builds all projects, checks prerequisites, and provides clear guidance.
 
 .PARAMETER Project
-    Which project to build: All, Tray, WinUI, Shared, Cli
+    Which project to build: All, Tray, WinUI, Shared, Cli, WinNodeCli, SetupEngine
     Default: All
 
 .PARAMETER Configuration

docs/CONNECTION_ARCHITECTURE.md

@@ -69,17 +69,21 @@ Inbound chat and agent timeline events must include the gateway's canonical `ses
 ## Startup wiring (App.xaml.cs)
 
 ```
-1. Create GatewayRegistry(dataDir)
-2. Create CredentialResolver(identityReader)
-3. Create GatewayClientFactory()
-4. Create NodeConnector(logger)
-5. Create SshTunnelManager(tunnelService, logger)
-6. Create GatewayConnectionManager(resolver, factory, registry, ...,
-                                    nodeConnector, tunnelManager)
-7. Subscribe to StateChanged → update tray icon + hub window
-8. Subscribe to OperatorClientChanged → wire/unwire 25+ data event handlers
-9. Subscribe to NodeConnector.ClientCreated → NodeService.AttachClient
-10. Call ConnectAsync() → connects to active gateway
+1. Create GatewayRegistry(SettingsManager.SettingsDirectoryPath)
+2. Load gateway registry from gateways.json
+3. Create CredentialResolver(DeviceIdentityFileReader.Instance)
+4. Create GatewayClientFactory()
+5. Create ConnectionDiagnostics()
+6. Create NodeConnector(logger, diagnostics)
+7. Wire NodeConnector.ClientCreated → NodeService.AttachClient
+8. Create SshTunnelService(logger)
+9. Create GatewayConnectionManager(resolver, factory, registry, logger,
+                                    identityStore, nodeConnector, node mode flag,
+                                    diagnostics, tunnelService)
+10. Subscribe to OperatorClientChanged → wire/unwire 25+ data event handlers
+11. Subscribe to StateChanged → update tray icon + hub window
+12. Ensure NodeService exists before gateway initialization
+13. Call InitializeGatewayClient() → connects to active gateway
 ```
 
 Settings changes are classified by `SettingsChangeClassifier.Classify()` which compares `ConnectionSettingsSnapshot` before/after to determine the minimum reconnect action:
@@ -126,7 +130,7 @@ Idle → Connecting → Connected
 %APPDATA%\OpenClawTray\gateways\<id>\device-key-ed25519.json  — keypair + tokens
 ```
 
-Each `GatewayRecord` contains: `Id`, `Url`, `FriendlyName`, `SharedGatewayToken`, `BootstrapToken`, `LastConnected`, `SshTunnel` config, and an `IdentityDirName`.
+Each `GatewayRecord` contains: `Id`, `Url`, `FriendlyName`, `SharedGatewayToken`, `BootstrapToken`, `LastConnected`, `SshTunnel` config, `IsLocal`, `RequiresV2Signature`, `SetupManagedDistroName`, and `BrowserControlPort`. The `IdentityDirName` property is computed from `Id`.
 
 `SettingsManager` still owns general tray settings (node mode, MCP mode, SSH tunnel toggles, notifications, UI preferences). It may read legacy `Token` / `BootstrapToken` JSON fields into memory for migration, but save must not write those legacy credential fields back.
 
@@ -143,6 +147,13 @@ The invariant is that a paired device token always wins. Do not downgrade a pair
 
 **`CredentialResolver`** implements the precedence for WebSocket connections (operator and node roles).
 
+Node credential precedence follows the same invariant with a distinct stored token:
+
+1. **Stored node device token** in the per-gateway identity directory.
+2. **`GatewayRecord.SharedGatewayToken`** — shared token fallback when no paired node token exists.
+3. **`GatewayRecord.BootstrapToken`** — one-time setup, limited scopes.
+4. **No credential** — caller logs and skips node client init.
+
 **`InteractiveGatewayCredentialResolver`** resolves credentials for HTTP surfaces (chat URL `?token=` auth). It **prefers SharedGatewayToken** over DeviceToken because HTTP endpoints expect the shared token, not the per-device WebSocket token.
 
 ## Client instance lifecycle
@@ -176,7 +187,7 @@ When **another** device or node requests pairing, the gateway broadcasts `device
 
 ## SSH tunnel integration
 
-`SshTunnelService` manages an SSH local port-forward process. `SshTunnelManager` wraps it behind `ISshTunnelManager` for the connection manager.
+`SshTunnelService` manages an SSH local port-forward process and implements `ISshTunnelManager` directly for the connection manager.
 
 When a `GatewayRecord` has `SshTunnel` config, the connection manager starts the tunnel before connecting the WebSocket client to `ws://localhost:<localPort>`. The config stores the SSH daemon port (`sshPort`, default `22`) separately from the remote gateway port forwarded by `-L`.
 
@@ -200,8 +211,9 @@ The `EnableMcpServer=true`, `EnableNodeMode=false` path creates a local-only `No
 Tray actions should never silently no-op on common pairing/configuration issues:
 
 - Chat resolves credentials from the active registry record and per-gateway identity. If no usable credential exists, it opens Connection settings instead.
-- Canvas opens only when the Windows node is initialized and paired; otherwise it opens Connection settings.
+- Canvas opens only when the Windows node is initialized, paired, and the Canvas capability is enabled in settings; otherwise it opens Connection settings.
 - Quick Send uses the live operator client and surfaces scope/pairing errors from gateway calls.
+- `system.run` and `system.run.prepare` are gated by `NodeSystemRunEnabled` (default `true` for backward compatibility). When disabled, those commands are dropped from advertised capabilities and invocations are rejected.
 
 ## Legacy migration
 

docs/MCP_MODE.md

@@ -100,12 +100,12 @@ public bool EnableNodeMode { get; set; }      // open WebSocket to gateway
 public bool EnableMcpServer { get; set; }     // run local MCP HTTP server
 ```
 
-| `EnableNodeMode` | `EnableMcpServer` | Result |
+| `EnableNodeMode` | `EnableMcpServer` | Behavior |
 |---|---|---|
-| off | off | Operator-only (legacy default) |
-| off | on | **MCP server only, no gateway** |
-| on | off | Gateway node, no MCP |
-| on | on | Gateway node + MCP |
+| false | false | Operator-only (legacy default) |
+| false | true | **MCP server only, no gateway** |
+| true | false | Gateway node, no MCP |
+| true | true | Gateway node + MCP |
 
 Settings UI exposes both toggles in the Advanced section, with the live MCP endpoint URL and current status (`Listening` / `Stopped — save and restart to start` / `Disabled`).
 

docs/SETUP.md

@@ -19,9 +19,9 @@ Download the latest stable installer from the canonical OpenClaw release assets:
 
 | File | Architecture |
 |------|-------------|
-| [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-x64.exe) | Intel / AMD (most PCs) |
-| [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-arm64.exe) | ARM64 (Surface Pro X, Snapdragon laptops) |
-| [OpenClawCompanion-SHA256SUMS.txt](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt) | SHA-256 checksums |
+| [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-x64.exe) | Intel / AMD (most PCs) |
+| [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-arm64.exe) | ARM64 (Surface Pro X, Snapdragon laptops) |
+| [OpenClawCompanion-SHA256SUMS.txt](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt) | SHA-256 checksums |
 
 If you're unsure, use the **x64** installer.
 
@@ -188,7 +188,7 @@ Settings are stored at `%APPDATA%\OpenClawTray\settings.json`. If this file is c
 
 ## Updating
 
-OpenClaw Companion checks for updates automatically and shows a notification when a new version is available. Click **Update** to download and apply the update. You can also manually check by re-downloading from the [OpenClaw Windows docs](https://docs.openclaw.ai/platforms/windows) or the [latest OpenClaw release](https://github.com/openclaw/openclaw/releases/latest).
+OpenClaw Companion checks for updates automatically and shows a notification when a new version is available. Click **Update** to download and apply the update. You can also manually check by re-downloading from the [OpenClaw Windows docs](https://docs.openclaw.ai/platforms/windows) or the [latest OpenClaw Windows release](https://github.com/openclaw/openclaw-windows-node/releases/latest).
 
 ## Uninstalling
 

docs/TEST_COVERAGE.md

@@ -1,6 +1,6 @@
 # Test Coverage Summary
 
-**Last audited**: 2026-05-22<br>
+**Last audited**: 2026-07-01<br>
 **Framework**: xUnit / .NET 10.0<br>
 **Required validation status**: passing (`.\build.ps1`, Shared tests, Tray tests)
 
@@ -11,23 +11,24 @@ These are the suites every agent must run after code changes, as documented in
 
 | Suite | Latest runtime result |
 |---|---:|
-| `OpenClaw.Shared.Tests` | 1,920 total: 1,891 passed, 29 skipped |
-| `OpenClaw.Tray.Tests` | 1,178 total: 1,178 passed, 0 skipped |
+| `OpenClaw.Shared.Tests` | 2,720 total: 2,689 passed, 31 skipped |
+| `OpenClaw.Tray.Tests` | 1,452 total: 1,452 passed, 0 skipped |
 
-Runtime totals come from `dotnet test` on 2026-05-22. They are higher than
+Runtime totals come from `dotnet test` on 2026-07-01. They are higher than
 method counts because some `[Theory]` tests expand into multiple cases.
 
 ## Test project inventory
 
 | Project | Primary scope | Test methods |
 |---|---|---:|
-| `OpenClaw.Connection.Tests` | Gateway registry, credential resolution, connection manager/state machine, setup codes, pairing, diagnostics | 189 |
-| `OpenClaw.Shared.Tests` | Shared models, gateway client, capabilities, MCP, exec approval, A2UI security, URL handling, notification categorization | 1,347 |
-| `OpenClaw.Tray.Tests` | Tray state/UI helpers, settings isolation, onboarding, connection page behavior, localization, local gateway setup/uninstall | 786 |
-| `OpenClaw.Tray.UITests` | Native WinUI/A2UI control and rendering coverage | 50 |
-| `OpenClaw.WinNode.Cli.Tests` | Windows node CLI argument parsing, command behavior, JSON output, uninstall flow | 79 |
-| `OpenClawTray.FunctionalUI.Tests` | Functional UI smoke coverage | 8 |
-| `OpenClawTray.OnboardingV2.Tests` | Onboarding V2 page flow and state coverage | 9 |
+| `OpenClaw.Connection.Tests` | Gateway registry, credential resolution, connection manager/state machine, setup codes, pairing, diagnostics | 307 |
+| `OpenClaw.Shared.Tests` | Shared models, gateway client, capabilities, MCP, exec approval, A2UI security, URL handling, notification categorization | 1,932 |
+| `OpenClaw.Tray.Tests` | Tray state/UI helpers, settings isolation, onboarding, connection page behavior, localization, local gateway setup/uninstall | 1,131 |
+| `OpenClaw.Tray.UITests` | Native WinUI/A2UI control and rendering coverage | 61 |
+| `OpenClaw.WinNode.Cli.Tests` | Windows node CLI argument parsing, command behavior, JSON output, uninstall flow | 83 |
+| `OpenClaw.SetupEngine.Tests` | Setup engine, WSL gateway installation, setup-code, and local setup policy coverage | 244 |
+| `OpenClawTray.FunctionalUI.Tests` | Functional UI smoke coverage | 10 |
+| `OpenClaw.E2ETests` | Gateway-mediated setup/connect, revocation recovery, and network recovery suites | 0 |
 | `OpenClaw.Tray.IntegrationTests` | Integration-test project scaffold; no `[Fact]`/`[Theory]` methods currently | 0 |
 
 The method inventory is a source scan of `[Fact]` and `[Theory]` attributes. Use
@@ -57,7 +58,9 @@ The method inventory is a source scan of `[Fact]` and `[Theory]` attributes. Use
 - **OpenClaw.Connection.Tests** keeps connection architecture tests separate from tray UI concerns.
 - **OpenClaw.Tray.UITests** covers A2UI/native WinUI rendering behavior that is awkward to validate through pure unit tests.
 - **OpenClaw.WinNode.Cli.Tests** covers the standalone Windows node CLI contract.
-- **OpenClawTray.OnboardingV2.Tests** and **OpenClawTray.FunctionalUI.Tests** cover newer UI surfaces outside the main tray test project.
+- **OpenClaw.SetupEngine.Tests** covers gateway setup and local WSL installation policy.
+- **OpenClawTray.FunctionalUI.Tests** covers newer UI surfaces outside the main tray test project.
+- **OpenClaw.E2ETests** is exercised by CI with trait filters even though the project currently has no direct `[Fact]`/`[Theory]` method inventory.
 
 ## Formal validation paths