# Windows Validation Runbook

This runbook is for maintainers validating Nexamas UI on a Windows development machine.

## Prerequisites

Use a Windows machine with:

- Visual Studio / MSBuild capable of building .NET Framework 4.8 projects.
- PowerShell 5.1 or later.
- NuGet available either through `tools/nuget.exe` or system PATH.
- A clean source checkout without local generated folders.

## Important cleanup before running

The commercial gate rejects local/generated source-distribution artifacts. Before running validation, make sure these are absent:

```text
Nexamas.UI.vbproj.user
.vs/
samples/MinimalConsumerApp/bin/
samples/MinimalConsumerApp/obj/
```

The phase 13 project snapshot already removes those local files.

## Fast documentation-only check

```powershell
powershell -ExecutionPolicy Bypass -File .\tools\validation\Invoke-NexamasUIWindowsValidation.ps1 -Mode DocumentationOnly
```

Use this after changing only `.md` files.

## Static quality check

```powershell
powershell -ExecutionPolicy Bypass -File .\tools\validation\Invoke-NexamasUIWindowsValidation.ps1 -Mode StaticQuality -Configuration Release -Platform x64
```

Use this to combine documentation validation with static/source/package quality checks.

## Full release validation

```powershell
powershell -ExecutionPolicy Bypass -File .\tools\validation\Invoke-NexamasUIWindowsValidation.ps1 -Mode FullRelease -Configuration Release -Platform x64
```

Use this for a release candidate. This is the command that should be treated as the next real validation step after the source-verified documentation phases.

## What to send for review

After the command finishes, send the newest archive from:

```text
.artifacts/validation/NexamasUI_WindowsValidation_<timestamp>.zip
```

If the command fails, send the entire failing folder under:

```text
.artifacts/validation/windows-validation-<timestamp>/
```

The important files are:

- `summary.md`
- `summary.json`
- `environment.md`
- `logs/documentation-gate.log`
- `logs/quality-static.log` or `logs/quality-full.log`

## Interpreting failures

- Documentation gate failure: usually broken docs links, invalid claim rows, or documentation/package boundary drift.
- Cleanliness precheck failure: remove local files such as `.vbproj.user`, `.vs`, sample `bin/`, or sample `obj/`.
- Quality runner failure: inspect the named log in `.artifacts/validation/.../logs/` and the quality runner's own `.artifacts/quality/` logs.
- Pack/consumer failure: inspect `.artifacts/nuget/` and the packed consumer proof logs.

## SDK harness platform note

The SDK runtime harness must be built for the same platform as the commercial Nexamas UI assembly. For the current commercial release this means `x64`. Running the harness as AnyCPU/32-bit can produce `BadImageFormatException` when loading `bin\x64\Release\Nexamas.UI.dll`.


## SDK harness path quoting note

The SDK harness runner must pass MSBuild arguments as discrete arguments, not as a single command string. This is required for repositories stored in paths with spaces, for example `D:\My Work Space\...`. If MSBuild reports `MSB1008: Only one project can be specified` and shows `Switch: Work`, the harness runner is not using the path-safe argument-array invocation.