docs(windows): add runtime architecture overview

.agents/skills/build-openshell-mxc-windows/SKILL.md

@@ -32,7 +32,8 @@ The Windows build lane is implemented by these tracked files:
 | `tasks/rust.toml`, `tasks/test.toml`, and `tasks/markdown.toml` | Windows routing for compiler-bearing checks, explicit Unix-only test skips, and Markdown dependency setup. |
 | `tasks/scripts/windows-msvc.ps1` | PowerShell wrapper that enters the Visual Studio developer environment and invokes Cargo. |
 | `.github/workflows/windows-msvc.yml` | Opt-in PR lint and test plus advisory main/manual cache seeding and dependent binary builds on native x64 and ARM64 runners. |
-| `architecture/windows-msvc-build.md` | Design notes and validation contract. |
+| `CONTRIBUTING.md` | Human-facing Windows build prerequisites and command summary. |
+| `architecture/windows.md` | Stable Windows/MXC runtime and cross-architecture boundaries. |
 | `.agents/skills/build-openshell-mxc-windows/` | This skill and companion reference material. |
 
 Use the code that is already in the repo. Do not generate a parallel Windows
@@ -120,6 +121,7 @@ The lane targets a Windows host with Visual Studio Build Tools and rustup.
 | Windows SDK | `where.exe rc.exe` from a Developer PowerShell | Install an SDK containing target libraries and ARM64 tools. |
 | Rust via rustup | `rustc --version` | Add each target being validated: `x86_64-pc-windows-msvc` and/or `aarch64-pc-windows-msvc`. The wrapper also adds the selected target. |
 | mise | `mise --version` | Used as a task runner only. |
+| cargo-nextest | `cargo nextest --version` | Required by `windows:test:*` and `windows:ci`. Install the pinned version with `mise install --locked github:nextest-rs/nextest` before running tasks with `--skip-tools`. |
 | Git | `git --version` | Needed for checkout and sync work. |
 | PowerShell | `$PSVersionTable.PSVersion` | Windows PowerShell 5.1 works; PowerShell 7 is quieter with mise shell hooks. |
 
@@ -261,8 +263,8 @@ crypto dependency builds.
 |---|---|
 | `windows:check:x64` | `cargo check --workspace` for `x86_64-pc-windows-msvc`, excluding unsupported Windows packages as top-level workspace targets. |
 | `windows:check:arm64` | `cargo check --workspace` for `aarch64-pc-windows-msvc`, with the same top-level exclusions. |
-| `windows:build:x64` | Release-builds `openshell-gateway.exe` and `openshell.exe` for x64. |
-| `windows:build:arm64` | Release-builds `openshell-gateway.exe` and `openshell.exe` for ARM64. |
+| `windows:build:x64` | Release-builds `openshell-gateway.exe`, `openshell.exe`, and `openshell-supervisor-relay.exe` for x64. |
+| `windows:build:arm64` | Release-builds `openshell-gateway.exe`, `openshell.exe`, and `openshell-supervisor-relay.exe` for ARM64. |
 | `windows:test:x64` | Runs native x64 workspace tests with `--no-fail-fast`, excluding unsupported Windows packages as top-level workspace targets. |
 | `windows:test:arm64` | Runs native ARM64 workspace tests with `--no-fail-fast` and the same package exclusions. Rejects non-ARM64 hosts. |
 | `windows:test:unsupported:x64` | Re-runs focused `openshell-gateway` tests for unsupported Windows driver behavior. |

.agents/skills/build-openshell-mxc-windows/reference.md

@@ -9,11 +9,18 @@ maintaining the existing build-only Windows MSVC lane.
 |---|---|
 | `tasks/windows.toml` | Mise task definitions for `windows:*`. |
 | `tasks/scripts/windows-msvc.ps1` | Visual Studio environment discovery, rustup target setup, Cargo invocation, logs, artifact report. |
-| `.github/workflows/windows-msvc.yml` | PR/merge-queue lint and test plus main/manual cache seeding and dependent binary builds on native x64 and ARM64 runners. |
-| `architecture/windows-msvc-build.md` | Human-readable design contract. |
+| `.github/workflows/windows-msvc.yml` | Opt-in PR lint and test plus advisory main/manual cache seeding and dependent binary builds on native x64 and ARM64 runners. |
+| `CONTRIBUTING.md` | Human-readable Windows build prerequisites and commands. |
+| `architecture/windows.md` | Stable Windows/MXC runtime and cross-architecture boundaries. |
 
 ## Commands
 
+Install the pinned test runner once before using test-bearing tasks:
+
+```powershell
+mise install --locked github:nextest-rs/nextest
+```
+
 Use `--skip-tools` for all Windows mise tasks:
 
 ```powershell

CONTRIBUTING.md

@@ -361,14 +361,49 @@ just this crate does not require `LIBCLANG_PATH`:
 cargo build -p openshell-prover --target x86_64-pc-windows-msvc --features bundled-z3
 ```
 
-### Windows full build
-
-To build the full set of Windows binaries, including `openshell-gateway.exe`
-and `openshell.exe`, use the `windows:build:x64` mise task instead of a
-single-crate `cargo build`. It downloads the pinned prebuilt Z3 release by default. A
-full build also compiles crates that use `bindgen` (e.g. the MXC driver on
-Windows), so it requires `libclang.dll`; if LLVM is not on the default search
-path, set `LIBCLANG_PATH` to the directory containing `libclang.dll`:
+### Windows build and validation
+
+Use the platform-native `windows:*` mise tasks for Windows MSVC development.
+The lane supports x64 and ARM64 and builds `openshell-gateway.exe`,
+`openshell.exe`, and `openshell-supervisor-relay.exe`. It does not enable
+Docker, Kubernetes, Podman, or VM-backed execution on Windows.
+
+Install Visual Studio C++ Build Tools, a compatible Windows SDK, Rust through
+rustup, mise, and the Visual Studio LLVM tools used by `bindgen`. Test-bearing
+tasks also require the pinned `cargo-nextest` tool. Install it once through
+mise:
+
+```powershell
+mise install --locked github:nextest-rs/nextest
+```
+
+Run every task with `--skip-tools`; mise orchestrates the commands but does not
+install the Windows compiler toolchain.
+
+| Task | Purpose |
+|---|---|
+| `windows:lint:<x64\|arm64>` | Run Clippy for the Windows-supported workspace on the selected target architecture. |
+| `windows:build:<x64\|arm64>` | Build the three Windows release executables. |
+| `windows:test:<x64\|arm64>` | Run the workspace suite natively; the target must match the host architecture. |
+| `windows:test:unsupported:<x64\|arm64>` | Run the focused unsupported-driver contracts. |
+| `windows:test:mxc-real:<x64\|arm64>` | Run the probe-gated real-`wxc-exec` integration suite on the matching host. |
+| `windows:artifacts` | Report sizes and SHA256 hashes for release artifacts. |
+| `windows:ci` | Run the aggregate x64-host check, build, test, contract, and artifact workflow. |
+
+The task definitions in [`tasks/windows.toml`](tasks/windows.toml), the
+PowerShell implementation in
+[`tasks/scripts/windows-msvc.ps1`](tasks/scripts/windows-msvc.ps1), and the
+hosted workflow in
+[`.github/workflows/windows-msvc.yml`](.github/workflows/windows-msvc.yml) are
+the executable sources of truth. See
+[`architecture/windows.md`](architecture/windows.md) for the stable Windows/MXC
+runtime and enforcement boundaries.
+
+To build x64 locally, use `windows:build:x64` instead of a single-crate Cargo
+build. It downloads the pinned prebuilt Z3 release by default. A full build also
+compiles crates that use `bindgen`, including the MXC driver, so it requires
+`libclang.dll`. If LLVM is not on the default search path, set `LIBCLANG_PATH`
+to the directory containing `libclang.dll`:
 
 ```powershell
 $env:LIBCLANG_PATH='C:\Program Files\Microsoft Visual Studio\2022\<Edition>\VC\Tools\Llvm\x64\bin'

architecture/README.md

@@ -2,16 +2,17 @@
 
 OpenShell runs autonomous AI agents in sandboxed environments with explicit
 policy, credential, identity, and network boundaries. The target architecture is
-built around three stable runtime components: the **CLI**, the **Gateway**, and
-the **Supervisor**.
+built around stable user, control-plane, and runtime boundaries. Most runtimes
+place the runtime boundary in the **Supervisor**; driver-controlled runtimes such
+as Windows MXC enforce it through platform-native isolation and host services.
 
 The CLI, SDK, and TUI provide user-facing access. The gateway is the
 authenticated control plane: it owns API access, durable state, policy and
 settings delivery, provider configuration and attachments, and relay
-coordination. The supervisor runs inside every sandbox workload and is the local
-security boundary. It launches the agent as a restricted child process and
-enforces policy where process identity, filesystem access, network egress, and
-runtime credentials are visible.
+coordination. In supervisor-based runtimes, the supervisor runs inside the
+sandbox workload and launches the agent as a restricted child process. A
+driver-controlled runtime owns the equivalent lifecycle and enforcement duties
+without embedding the standard supervisor.
 
 Infrastructure-specific work sits behind integration boundaries. Compute,
 credentials, control-plane identity, and sandbox identity each have a driver or
@@ -42,6 +43,7 @@ flowchart TB
 
     subgraph INFRA["Integrated Infrastructure"]
         RUNTIME["Docker / Podman / Kubernetes / VM"]
+        MXC["Windows MXC"]
         SECRETSTORE["Eg: Keychain / Secret Service / Vault / Kubernetes Secrets"]
         IDP["Eg: mTLS / OIDC / Local identity"]
         WORKLOADID["Eg: SPIFFE / Gateway-issued workload identity"]
@@ -54,6 +56,11 @@ flowchart TB
         AGENT["Restricted agent process"]
     end
 
+    subgraph WINDP["Windows MXC Data Plane"]
+        MXCAGENT["MXC-isolated agent process"]
+        MXCPROXY["Host policy proxy (ProcessContainer only)"]
+    end
+
     CLI -->|"gRPC / HTTP"| GW
     SDK -->|"gRPC / HTTP"| GW
     TUI -->|"gRPC / HTTP"| GW
@@ -70,10 +77,13 @@ flowchart TB
     SIDENT -->|"gRPC / UDS"| SIDRV
 
     CDRV --> RUNTIME
+    CDRV --> MXC
     CRDRV --> SECRETSTORE
     CPIDRV --> IDP
     SIDRV --> WORKLOADID
     RUNTIME -->|"provisions workload"| SUP
+    MXC -->|"driver-controlled launch"| MXCAGENT
+    MXCAGENT -. "governed egress" .-> MXCPROXY
 
     SUP -->|"outbound control, config, logs, relay"| GW
     SUP -->|"spawn + restrict"| AGENT
@@ -93,8 +103,8 @@ flowchart TB
 | Credentials subsystem | Logical provider and credential resolution. Secret storage and platform-native credential access belong to credentials drivers. |
 | Control-plane identity | Authentication and authorization for users, operators, and API clients. External identity verification belongs to identity drivers. |
 | Sandbox identity | Workload identity for supervisors and sandbox-to-sandbox authorization. Identity issuance or verification belongs to sandbox identity drivers. |
-| Supervisor | Sandbox-local security boundary. It prepares isolation, fetches config, injects credentials, runs relay endpoints, starts the proxy, and launches restricted agent processes. |
-| Policy proxy | Mandatory egress path for agent traffic. It enforces destination, binary identity, SSRF, TLS/L7, and endpoint-bound provider credential injection. |
+| Supervisor | Sandbox-local security boundary for supervisor-based runtimes. It prepares isolation, fetches config, injects credentials, runs relay endpoints, starts the proxy, and launches restricted agent processes. Driver-controlled runtimes must enforce supported behavior and explicitly define or reject unsupported behavior. |
+| Policy proxy | Mandatory path for policy-governed egress. It enforces destination, binary identity, SSRF, TLS/L7, and endpoint-bound provider credential injection. |
 
 ## Integrating with the Ecosystem
 
@@ -111,10 +121,12 @@ operations. They should stay thin, preserve
 native behavior by default, and report platform lifecycle events back through
 the shared contracts.
 
-The supervisor owns OpenShell sandbox semantics. Filesystem policy, process
-privilege reduction, network proxying, endpoint-bound credential injection,
-security logging, and gateway relay behavior should remain
-consistent across runtimes.
+The supervisor owns OpenShell sandbox semantics on supervisor-based runtimes.
+Driver-controlled runtimes own the corresponding platform-specific semantics
+and must explicitly define or reject policy they cannot enforce. Filesystem
+policy, process privilege reduction, network proxying, endpoint-bound credential
+injection, security logging, and gateway relay behavior should remain consistent
+where the runtime advertises those capabilities.
 
 This keeps OpenShell usable in local single-player setups, Kubernetes
 deployments, VM-backed sandboxes, and future third-party environments. A new
@@ -142,9 +154,11 @@ The compute-driver capability contract identifies whether a driver reports
 runtime readiness. Most drivers use the supervisor session model above. A
 driver that sets `driver_reports_runtime_readiness` may self-report readiness
 without a supervisor session. Every driver receives the canonical create-time
-policy in `DriverSandboxSpec`; drivers without a supervisor use the existing
-sandbox configuration API for later revisions. The Windows MXC driver reports
-its own readiness and does not expose interactive connect or governed egress.
+policy in `DriverSandboxSpec`; drivers without a supervisor may use the sandbox
+configuration API when they advertise live-update support. The Windows MXC
+driver reports its own readiness, does not support live updates, and does not
+expose interactive connect. ProcessContainer can establish governed egress at
+create time; IsolationSession rejects governed network policies.
 
 The gateway delivers desired state; the sandbox applies it locally. Policy,
 settings, provider attachments, and credential bindings flow from the gateway
@@ -173,7 +187,7 @@ that crate's `README.md`.
 | [Compute Runtimes](compute-runtimes.md) | Docker, Podman, Kubernetes, VM, sandbox images, and runtime-specific responsibilities. |
 | [Build](build.md) | Build artifacts, CI/E2E, docs site validation, and release packaging. |
 | [Google Vertex AI Provider](google-vertex-ai-provider.md) | Implementation reference for the `google-vertex-ai` provider, from CLI through gateway to sandbox. |
-| [Windows MSVC Build](windows-msvc-build.md) | Build-only native Windows MSVC lane (x64/ARM64) and unsupported-runtime behavior on Windows. |
+| [Windows](windows.md) | Windows/MXC runtime architecture, policy enforcement, networking, relay, audit, and trust boundaries. |
 
 ## `rfc/` vs `architecture/`