docs(windows): route main documentation to the Windows release branch

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

@@ -1,7 +1,10 @@
 # Reference: Windows MSVC maintenance lane
 
 Companion to [SKILL.md](SKILL.md). Use this file for quick lookup while
-maintaining the existing build-only Windows MSVC lane.
+maintaining the native Windows MSVC and MXC runtime lane on the
+[`windows` development and release branch](https://github.com/NVIDIA/OpenShell/tree/windows).
+Run the commands below from that branch or a branch based on it, including
+when reading this reference on `main`.
 
 ## Lane Files
 
@@ -33,15 +36,35 @@ For host-native full validation, detect architecture first:
 $arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
 if ($arch -eq [System.Runtime.InteropServices.Architecture]::Arm64) {
     mise run --skip-tools windows:check:arm64
+    if ($LASTEXITCODE -ne 0) { throw "windows:check:arm64 failed." }
     mise run --skip-tools windows:build:arm64
+    if ($LASTEXITCODE -ne 0) { throw "windows:build:arm64 failed." }
     mise run --skip-tools windows:test:arm64
+    if ($LASTEXITCODE -ne 0) { throw "windows:test:arm64 failed." }
     mise run --skip-tools windows:test:unsupported:arm64
+    if ($LASTEXITCODE -ne 0) { throw "windows:test:unsupported:arm64 failed." }
+    mise run --skip-tools windows:test:mxc-real:arm64
+    if ($LASTEXITCODE -ne 0) { throw "windows:test:mxc-real:arm64 failed." }
     mise run --skip-tools windows:artifacts
+    if ($LASTEXITCODE -ne 0) { throw "windows:artifacts failed." }
+    mise run --skip-tools windows:e2e:mxc
+    if ($LASTEXITCODE -ne 0) { throw "MXC E2E validation failed or was incomplete." }
 } else {
     mise run --skip-tools windows:ci
+    if ($LASTEXITCODE -ne 0) { throw "windows:ci failed." }
+    mise run --skip-tools windows:test:mxc-real:x64
+    if ($LASTEXITCODE -ne 0) { throw "windows:test:mxc-real:x64 failed." }
+    mise run --skip-tools windows:e2e:mxc
+    if ($LASTEXITCODE -ne 0) { throw "MXC E2E validation failed or was incomplete." }
 }
 ```
 
+`windows:ci` does not include the real MXC runtime tests or E2E. Run the matching
+`windows:test:mxc-real:*` task and `windows:e2e:mxc` explicitly.
+These tasks can report `SKIP` when the executor or backend is unavailable;
+full validation requires an MXC-capable host. E2E exits nonzero when any
+required runtime scenario fails or skips.
+
 The native test tasks reject a target that does not match the host architecture.
 Do not report x64 compatibility-under-emulation coverage from an ARM64 run.
 
@@ -75,7 +98,7 @@ Ninja to `PATH`, while the crypto crates select `clang-cl`. Use a short
 
 ## Unsupported Driver Rules
 
-Windows is a build target only. These runtimes remain unsupported:
+These Windows runtimes remain unsupported:
 
 - Docker
 - Kubernetes
@@ -115,11 +138,10 @@ top-level workspace targets for check/test:
 ```
 
 The gateway keeps platform configuration and unsupported-operation contracts
-without depending on the Docker, Kubernetes, Podman, sandbox runtime,
-standalone supervisor, supervisor process runtime, VM, or VFIO crates. The MXC
-driver does depend on the cross-platform supervisor network library for its host
-egress proxy. The Kubernetes Secrets and Vault libraries still compile as
-gateway dependencies; only their standalone Unix-socket binaries and
+without depending on the Docker, Kubernetes, Podman, VM, or VFIO runtime crates.
+The MXC runtime compiles the supervisor, supervisor-process library, and sandbox
+boundary on Windows. The Kubernetes Secrets and Vault libraries still compile
+as gateway dependencies; only their standalone Unix-socket binaries and
 package-level tests are excluded as top-level targets.
 
 The supervisor and supervisor-process packages now participate as top-level

.agents/skills/sync-agent-infra/SKILL.md

@@ -28,6 +28,7 @@ Run after adding, removing, or renaming a skill or crate; changing issue or PR c
 | TUI behavior | `tui-development` |
 | Release artifacts or smoke coverage | `test-release-canary` |
 | CI diagnostics | `watch-github-actions` |
+| Native Windows builds, runtime, or release branch guidance | `build-openshell-mxc-windows`; keep Windows implementation links on `windows` even in docs merged to `main` |
 | Gator supervision | `launch-openshell-gator` |
 | SBOM workflow | `sbom` |
 | RFC workflow | `create-rfc` |

AGENTS.md

@@ -50,7 +50,8 @@ Do not rely on this file for a full inventory. The detailed public and contribut
 | `crates/openshell-driver-docker/` | Docker compute driver | In-process `ComputeDriver` backend for local Docker sandbox containers |
 | `crates/openshell-driver-podman/` | Podman compute driver | In-process `ComputeDriver` backend for local Podman sandbox containers |
 | `crates/openshell-driver-vm/` | VM compute driver | Standalone libkrun-backed `ComputeDriver` subprocess (embeds its own rootfs + runtime) |
-| `crates/openshell-driver-mxc/` | Microsoft MXC compute driver | In-process Windows AppContainer and isolation-session compute backend |
+| [`crates/openshell-driver-mxc/`](https://github.com/NVIDIA/OpenShell/tree/windows/crates/openshell-driver-mxc) (`windows` branch) | Microsoft MXC compute driver | Native Windows ProcessContainer backend; see the Windows branch for the maintained implementation |
+| [`crates/openshell-mxc-boundary/`](https://github.com/NVIDIA/OpenShell/tree/windows/crates/openshell-mxc-boundary) (`windows` branch) | Windows sandbox boundary | Dedicated Windows workload boundary paired with the host supervisor |
 | `crates/openshell-prover/` | Policy prover | Policy verification and proof generation |
 | `crates/openshell-prover-cli/` | Policy prover CLI | Standalone local policy boundary checks |
 | `crates/openshell-server-macros/` | Server macros | Compile-time helpers for gateway RPC authorization |

CI.md

@@ -67,11 +67,25 @@ For an intentional minor-train incompatibility, record the Buf finding,
 linked issue, consumer impact, and migration plan in the PR. Keep the finding
 visible; do not disable the job or add a broad Buf ignore rule.
 
-Windows PR checks are opt-in: add `test:windows`, then select **Re-run all jobs**
+### Windows validation
+
+Native Windows implementation and releases use the
+[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows), independently
+of the `main` release train described in this document. Shared documentation on
+`main` must retain that branch placement. See [WINDOWS.md](WINDOWS.md) for the
+native MSVC build and MXC runtime requirements.
+
+The [Windows MSVC workflow on `windows`](https://github.com/NVIDIA/OpenShell/blob/windows/.github/workflows/windows-msvc.yml)
+runs native x64 and ARM64 lanes. Windows PR checks are opt-in: add
+`test:windows`, then select **Re-run all jobs**
 on the current Windows MSVC run. Subsequent mirrored commits run them automatically.
 Windows checks are not required for merging and do not run in merge queues.
-Main and manual runs also build release binaries, with `continue-on-error: true`
-so Windows failures do not fail the workflow.
+Pushes to `windows` and manual runs on that branch seed the lint/test caches and run dependent
+release binary builds. Those jobs use `continue-on-error: true`, so inspect
+their individual results rather than treating a green workflow as qualification.
+The jobs do not upload or publish the binaries. Native Windows packages are
+not supplied through the `main` installer or release train. Real MXC runtime qualification requires a
+capable host and the [Windows runtime tests](https://github.com/NVIDIA/OpenShell/blob/windows/TESTING.md#native-windows-validation).
 
 ### Advisory compatibility review
 

CONTRIBUTING.md

@@ -114,7 +114,7 @@ Contributor and maintainer skills live in `.agents/skills/`. They are marked int
 | Triage          | `apply-triage-action`     | Apply, reject, or defer one explicitly selected triage recommendation                               |
 | Platform        | `helm-dev-environment`    | Start and manage the local Kubernetes development environment                                       |
 | Platform        | `tui-development`         | Development guide for the ratatui-based terminal UI                                                 |
-| Platform        | `build-openshell-mxc-windows` | Maintain and validate the build-only x64 and ARM64 Windows MSVC lane                             |
+| Platform        | `build-openshell-mxc-windows` | Maintain and validate native x64 and ARM64 MSVC builds and MXC runtime on the `windows` branch |
 | Documentation   | `update-docs-from-commits` | Scan recent commits and draft doc updates for user-facing changes                                  |
 | Maintenance     | `sync-agent-infra`        | Detect and fix drift across agent-first infrastructure files                                        |
 | Reference       | `sbom`                    | Generate SBOMs and resolve dependency licenses                                                      |
@@ -141,6 +141,12 @@ When recording a triage outcome, replace the previous assessment state rather th
 
 ## Prerequisites
 
+Native Windows development uses the [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows).
+Follow [Native Windows support](WINDOWS.md) for checkout, MSVC prerequisites,
+runtime requirements, and limitations. Target Windows implementation PRs at
+`windows`. Shared documentation can merge into `main`, but Windows-specific
+source and task links must continue to point to `windows`.
+
 Install [mise](https://mise.jdx.dev/). This is used to set up the development environment.
 
 ```bash
@@ -163,7 +169,7 @@ echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish
 echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
 ```
 
-Project requirements:
+Linux/macOS development requirements:
 
 - Rust 1.94+
 - Python 3.11+
@@ -202,7 +208,7 @@ cargo build -p openshell-prover-cli --features vendored-z3
 Local gateway image and E2E builds enable `vendored-z3` so their
 copied gateway binaries do not need a shared Z3 library in the runtime image.
 
-For x86-64 and ARM64 Windows MSVC builds, use one of these Z3 paths:
+For x86-64 and ARM64 Windows MSVC builds from the `windows` branch, use one of these Z3 paths:
 
 - Prebuilt Z3 (the default for `windows:*` tasks): `z3-sys` downloads the
   pinned Z3 5.1.0 GitHub release for the target architecture on the first
@@ -225,8 +231,10 @@ cargo build -p openshell-prover --target x86_64-pc-windows-msvc --features prebu
 
 ### 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
+Run these commands in a `windows`-based checkout. To build the full set of
+Windows binaries, including `openshell-gateway.exe`, `openshell.exe`,
+`openshell-supervisor.exe`, and `openshell-windows-sandbox.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
@@ -237,6 +245,12 @@ $env:LIBCLANG_PATH='C:\Program Files\Microsoft Visual Studio\2022\<Edition>\VC\T
 mise run --skip-tools windows:build:x64
 ```
 
+For ARM64, use `windows:build:arm64` with ARM64 MSVC components and host-native
+LLVM. Keep the matching `libz3.dll` staged by the build beside the executables.
+See [Windows validation](https://github.com/NVIDIA/OpenShell/blob/windows/TESTING.md#native-windows-validation)
+for native tests and MXC E2E requirements. Docker is not required for the native
+Windows build or MXC runtime.
+
 To use a local x64 Z3 release instead of the prebuilt download, set
 `Z3_LIBRARY_PATH_OVERRIDE` and `Z3_SYS_Z3_HEADER` before running the task:
 
@@ -256,6 +270,9 @@ xcode-select --install
 
 ## Getting Started
 
+The gateway and shell shortcuts below describe Linux/macOS development.
+For native Windows, use the [Windows build and runtime instructions](WINDOWS.md).
+
 ```bash
 # One-time trust
 mise trust

README.md

@@ -27,9 +27,14 @@ OpenShell governs what agents can do in two ways: it instruments the kernel to e
 
 See [Architecture](https://docs.nvidia.com/openshell/latest/about/architecture) for how the gateway, supervisor, and sandbox fit together.
 
+Native Windows has a separate MXC implementation on the
+[`windows` development and release branch](https://github.com/NVIDIA/OpenShell/tree/windows).
+See [Native Windows support](WINDOWS.md) for its runtime architecture and current
+enforcement limitations; the guarantees above do not establish Windows parity.
+
 ## Quickstart
 
-You need Linux, macOS on Apple Silicon, or Windows with WSL 2 (experimental), plus Docker, Podman, or host virtualization. See the [Support Matrix](https://docs.nvidia.com/openshell/latest/about/support-matrix) for details.
+The quickstart below supports Linux and macOS on Apple Silicon, with experimental Linux use inside WSL 2. It requires Docker, Podman, or host virtualization. For native Windows x64 or ARM64, follow [Native Windows support](WINDOWS.md) and build from the [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). Native Windows uses MXC and does not use the installer below. See the [Support Matrix](https://docs.nvidia.com/openshell/latest/about/support-matrix) for details.
 
 ```shell
 curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
@@ -48,6 +53,7 @@ The installer sets up the CLI and a local gateway. The default sandbox image is
 - [Extensibility](https://docs.nvidia.com/openshell/latest/extensibility/overview): middleware, interceptors, and compute drivers.
 - [Tutorials](https://docs.nvidia.com/openshell/latest/tutorials/first-network-policy): step-by-step policy and agent walkthroughs.
 - [Prerelease and development builds](https://docs.nvidia.com/openshell/latest/about/installation#prerelease-and-development-builds): try an upcoming release or the latest commit on `main`.
+- [Native Windows support](WINDOWS.md): build, run, and validate the MXC implementation maintained and released from `windows`, even when this documentation is read on `main`.
 
 ## Agent Skills
 

TESTING.md

@@ -72,6 +72,44 @@ task skips them. Run them on an idle machine with
 
 ### Native Windows validation
 
+Start with the [Windows build prerequisites](WINDOWS.md#build) in a checkout
+based on `windows`. Run the lane matching the native host:
+
+```powershell
+# Native x64 host
+mise run --skip-tools windows:lint:x64
+mise run --skip-tools windows:build:x64
+mise run --skip-tools windows:test:x64
+mise run --skip-tools windows:test:unsupported:x64
+
+# Native ARM64 host
+mise run --skip-tools windows:lint:arm64
+mise run --skip-tools windows:build:arm64
+mise run --skip-tools windows:test:arm64
+mise run --skip-tools windows:test:unsupported:arm64
+```
+
+The test tasks use the CI nextest profile and server test support. They reject
+a target that does not match the host architecture. `windows:ci` is the x64-host
+aggregate, including ARM64 cross-check/build unless explicitly skipped; it
+does not establish native ARM64 test coverage.
+
+For runtime validation, provision a capable MXC host and build its native
+release binaries first. On x64, run:
+
+```powershell
+mise run --skip-tools windows:test:mxc-real:x64
+mise run --skip-tools windows:e2e:mxc
+```
+
+Use `windows:test:mxc-real:arm64` on ARM64. The real-runtime unit tests can
+report `SKIP` when the executor or backend is absent; E2E returns nonzero
+when required runtime coverage is missing. Report passed, failed, and
+skipped/ignored executions separately, including why any probe gated coverage.
+Passing E2E does not qualify the [known Windows enforcement gaps](WINDOWS.md#runtime-and-current-limits).
+See the [Windows test task definitions](https://github.com/NVIDIA/OpenShell/blob/windows/tasks/windows.toml)
+for boundary, loopback, network, and audit suites.
+
 Use `mise run --skip-tools pre-commit` with the existing Rust/MSVC toolchain.
 Windows now checks tracked Cargo lockfiles through PowerShell rather than
 skipping them.