agent-dev-env 0.1.0-canary.2.fbbd044

package/dist/assets/images/ubuntu-arm64-vmware/vars/sandbox-ubuntu-24-04-arm64-vmware.pkrvars.hcl

@@ -0,0 +1,71 @@
+# Ubuntu 24.04 LTS (ARM64) sandbox image — VMware (Fusion) build.
+#
+# Built with the Packer vmware-iso plugin on Apple Silicon (the vmware-iso
+# builder drives VMware Fusion, which virtualizes ARM64 guests natively):
+# Ubuntu Server ARM64 ISO + Subiquity autoinstall (seed served over HTTP).
+# See images/ubuntu-arm64-vmware/README.md for the full build flow — the
+# Ubuntu ISO is bring-your-own (not redistributable via Packer), so it is
+# not part of this repo.
+
+ubuntu_version = "24-04"
+
+# SHA256 of the Ubuntu Server 24.04 ARM64 ISO. Canonical publishes the hash
+# in the release SHA256SUMS (https://cdimage.ubuntu.com/releases/24.04/release/);
+# paste it here to enable integrity verification. Set UBUNTU_ISO_PATH to the
+# local ISO path when building. Empty = skip verification.
+iso_sha256 = "9a6ce6d7e66c8abed24d24944570a495caca80b3b0007df02818e13829f27f32"
+
+# Toolchain versions. Direct downloads are pinned by version + SHA256 here
+# (the hashes come from the vendor's published checksums); nvm (Node) and
+# rustup (Rust) pin the major/minor and resolve the latest patch. apt
+# packages (gcc, git, python3, ...) come from the Ubuntu archive.
+node_version = "26"
+python_version = "3.12"
+github_cli_version = "2.98.0"
+github_cli_sha256 = "bbc4ac7964c2a091fd555cd1758d10a7cfcfdc472e405f0b0fb958f05d535cb6"
+open_code_review_version = "1.9.5"
+go_version = "1.27.0"
+go_sha256 = "51798d2c42d0e1c6ed7fd9f48728b4193abac9e8aad6dbac2fe96a81f5909bda"
+rust_version = "1.95"
+vscode_version = "1.134.0"
+vscode_sha256 = "b30f5bda4855231681cc7fe22d4a59e7dbee2be170b0e4fb04c7e83b9f9affe5"
+
+# Mozilla Firefox: official linux-aarch64 release tarball (en-US), pinned
+# by version + SHA256 (SHA256SUMS from the same FTP directory). No Google
+# Chrome: CfT publishes no linux-arm64 build (only x86_64 linux64) and
+# Ubuntu's chromium is snap-only.
+firefox_version = "154.0"
+firefox_sha256 = "0391a8d072431286fbed8f9ff497a126ff0c9e81c455d4ef04f9fb878fd4bf1f"
+
+# Docker CLI + plugins (client only — the engine is bridged from the host
+# by the sandbox runner). Static aarch64 binaries, hash-pinned.
+docker_version = "29.7.2"
+docker_sha256 = "43d143448adf2c2787704e7d7704fd6d62d367a54c5edaef0a3f75509cb0938d"
+docker_compose_version = "5.5.0"
+docker_compose_sha256 = "ff42489f5a9b879d5d117c5ffea6defc27390b3286da8ad52cbc9c6ab5df590e"
+docker_buildx_version = "0.36.1"
+docker_buildx_sha256 = "5d0cafd9d16afe1a0f0d9529885344ace2cc99efdd531b6c783c5455a6001569"
+
+# VM resources
+disk_size = 100
+cpu_count = 4
+memory_gb = 8
+
+# SSH credentials used for provisioning. They are baked into
+# images/ubuntu-arm64-vmware/autoinstall/user-data (identity: user +
+# password hash) and become the sandbox's login — keep the two files in
+# sync.
+ssh_username = "admin"
+ssh_password = "sandbox1"
+
+# OpenChamber web UI password + port. The runner advertises the UI at
+# http://<guest-ip>:4000 (password "sandbox" by default). OpenChamber
+# refuses to serve on the network without a password.
+openchamber_ui_password = "sandbox"
+openchamber_port = 4000
+
+# Semantic version this image is published under (also the GHCR push tag,
+# besides :latest). For every release: bump it, add a CHANGELOG.md entry,
+# and create the ubuntu-arm64-vmware-v<version> git tag
+# (npx agent-dev-env tag <image>).
+image_version = "1.1.0"

package/dist/assets/images/windows-arm64-qemu/CHANGELOG.md

@@ -0,0 +1,209 @@
+# Changelog
+
+All notable changes to the Windows sandbox images.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The image version lives in the image's vars file (`image_version`); every
+release bumps it, adds an entry below, and tags the release commit
+`<platform>-v<version>` (e.g. `windows-arm64-qemu-v1.0.0`). The
+`[Unreleased]` section on top is never removed — changes land there until
+the next release.
+
+## [Unreleased]
+
+### Added
+
+- `agent-dev-env stop` (windows-qemu) — stops the sandbox: qemu (via the
+  runner's `qemu.pid`) and swtpm, plus the host SSH agent / Docker bridge
+  listeners the runner leaves up. Honors the runner's
+  `SANDBOX_AGENT_PORT` / `SANDBOX_DOCKER_PORT` overrides.
+- `agent-dev-env delete` (windows-qemu) — deletes the sandbox: stops it
+  first (delegating to the stop step), then removes the state dir (working
+  disk overlay + TPM/EFI NVRAM + pulled image cache). Asks before deleting
+  unless `--yes`.
+- The virtual display is now a virtio-gpu-pci (virtio-gpu) instead of
+  ramfb at runtime: the image stages the ARM64 `viogpudo` (virtio-gpu
+  display-only) driver onto the unattend CD, so first logon lands it in
+  the driver store and the runtime VM's virtio-gpu-pci binds it.
+  Resizing the QEMU window now changes the guest's resolution
+  (`VIRTIO_GPU_EVENT_DISPLAY`) instead of only scaling the framebuffer.
+  The image build itself keeps ramfb (WinPE has no display driver).
+
+### Changed
+
+- Node.js is bumped from 22 to 26 (`nodejs_version = "26.8.1"` in the
+  vars file, choco package `nodejs`).
+- The image was renamed from `sandbox-windows-11` to
+  `sandbox-windows-11-arm64-qemu` (vars file, template `vm_name` —
+  `sandbox-windows-<windows_version>-arm64-qemu.qcow2` — the GHCR package
+  name and the runner's `image_name`): the platform is now part of the
+  image name, matching the state-dir naming
+  (`~/Library/Application Support/agent-dev-env/windows-qemu/`).
+  Older releases stay published under the old name.
+- The QEMU runner (`agent-dev-env run`, windows-qemu) boots the guest
+  in a resizable window: it passes `-display cocoa,zoom-to-fit=on` (the
+  cocoa window is fixed-size otherwise) and replaced `-device ramfb` with
+  `-device virtio-gpu-pci`. Full screen is available from the QEMU
+  window's View menu → Enter Fullscreen.
+- The build flow (`agent-dev-env build`) — the EXIT trap no longer prints
+  `stop_watchdog: command not found` when the build aborts before the
+  watchdog function is defined (it now checks before calling it).
+- `agent-dev-env run` (windows-qemu) — the working VM is recreated
+  when the pristine image *changes*, not just when its path changes: the
+  backing marker now records path + size + mtime, and the stale overlay /
+  EFI NVRAM / TPM state are discarded (previously a rebuild that replaced
+  the file at the same path stacked the old overlay on the new base — a
+  corrupt disk that dropped Windows to the UEFI shell). The EFI NVRAM is
+  also seeded from the build output's `efivars.fd` when one exists, so
+  Windows' own Boot0000 is used instead of the empty edk2 template.
+- `agent-dev-env run` (windows-qemu) — the default working-VM state
+  dir now lives under the CLI's data root
+  (`~/Library/Application Support/agent-dev-env/windows-qemu/<image>/`):
+  the platform and image are part of the path, so state from different
+  platforms and images never collides. Override the data root with
+  `AGENT_DEV_ENV_DATA_HOME` (or `XDG_DATA_HOME`) as before.
+- `agent-dev-env run` (windows-qemu) — the summary's stop hints now
+  point at `agent-dev-env stop` instead of a bare
+  `kill $(cat …/qemu.pid)` and a hand-written `lsof | xargs kill` for the
+  bridge listeners.
+
+### Fixed
+
+- The runner's guest bridge setup no longer takes ~5 min per SSH command
+  on a guest whose bridges are already installed: the sshd channel does
+  not close when a PowerShell payload finishes (the guest-side relays
+  hold the console handles and keep trickling output, which resets
+  expect's idle timeout), so every `guest_ps` call used to end only at
+  an alarm (or never, before the hard alarm was added). Each remote
+  command now ends with a unique sentinel echoed by the guest's shell
+  after the payload exits, and expect kills the ssh client on it — step
+  5 finishes in seconds.
+- The image no longer depends on the Chocolatey bootstrapper persisting
+  the machine PATH: the Chocolatey provisioner adds
+  `C:\ProgramData\chocolatey\bin` to the Machine PATH itself and the
+  toolchain + VS provisioners call `choco.exe` by its full path — the
+  bootstrapper's compiled `Install-ChocolateyPath` can silently fail to
+  persist in the elevated WinRM context, so after the reboot the
+  re-read PATH still lacked the choco bin dir ('choco' not recognized).
+  `choco cleanup` in the final verification now redirects inside `cmd`
+  too, so PowerShell 5.1 never turns choco's stderr into a terminating
+  error under `$ErrorActionPreference='Stop'`.
+- The RemoteSigned bake-in no longer aborts the build (observed at the
+  OpenChamber provisioner): the build passes `-ExecutionPolicy Bypass`
+  at Process scope, so `Set-ExecutionPolicy -Scope LocalMachine`
+  emitted its "overridden by a more specific scope" notice, which
+  Windows PowerShell 5.1 under WinRM turned into a terminating error
+  even though the machine policy was updated. The provisioner now sets
+  the Process scope first (no override, no notice) and tolerates a
+  failed machine-policy set.
+- The image now bakes in machine-wide PowerShell `RemoteSigned` instead
+  of shipping Windows' default `Restricted` policy: `opencode` (an npm
+  shim — `opencode.ps1` in `%APPDATA%\npm`) refused to start in a
+  PowerShell session with "running scripts is disabled on this system".
+  The runners' runtime `Set-ExecutionPolicy` stays as a fallback for
+  images built before this change.
+
+## [windows-arm64-qemu-v1.1.0] - 2026-08-24
+
+### Changed
+
+- Build artifacts moved out of the image directory into a top-level
+  `build/windows-arm64-<platform>/` directory: `output/` for
+  the built qcow2, `packer_cache/` for virtio-win.iso/swtpm/watchdog
+  scratch and `drivers/staging/` for the unattend CD driver subset. The
+  template's `output_directory` and the staged `cd_files` path are now
+  variables set by the platform `build.sh` wrapper; the macOS/tart images
+  build no files and have no such directory.
+
+### Added
+
+- The toolchain and VS provisioners re-read PATH from the registry at
+  the start of their scripts: after the tools reboot a fresh WinRM
+  process can inherit a stale PATH (observed once: 'choco' not
+  recognized), and the choco bootstrapper's PATH update must be picked
+  up explicitly.
+- The final verification checks the new toolchains with a check-and-warn
+  loop instead of hard version dumps: a missing helper (e.g.
+  `llvm-config`, not shipped by every LLVM Windows build) no longer
+  fails the build.
+- The build reboots the guest once after the virtio-win guest-tools MSI
+  install (new `windows-restart` provisioner): the MSI leaves a pending
+  reboot, which makes `choco install` return 3010 and makes the .NET
+  Framework 4.8 Developer Pack installer fail with exit code 1 (it
+  refuses to run while a reboot is pending). Choco exit-code checks in
+  the VS phase accept 3010 (success, reboot required).
+- Toolchains from AdGuard's `build-agent-images` Windows image
+  (`windows2022-vs2022` / `windows2022-go`) that were missing: Go, Rust
+  (via rustup — arm64 host toolchain + MSVC targets for
+  x86_64/i686/aarch64), Visual Studio 2022 Build Tools (choco package +
+  `setup.exe` finalizer: .NET 4.8/.NET Core SDKs, VC++ workload
+  x86/x64/ARM/ARM64, CMake, Windows 11 SDK 22621), WiX Toolset, protoc,
+  NASM, LLVM, Vim, NuGet CLI, MinGW-w64 and GNU make. All versions are
+  pinned in the vars file (`go_version`, `rust_version`,
+  `vs_buildtools_version`, `wixtoolset_version`, `protoc_version`,
+  `nasm_version`, `llvm_version`, `vim_version`, `nuget_version`,
+  `mingw_version`, `make_version`); the toolchain provisioner and the
+  final verification dump their versions.
+- Build watchdog: `scripts/watch-build.sh` (+ `watch-build.py` supervisor
+  and `watch-build-ocr.swift` OCR helper). The headless build's
+  boot-command Enter-spam can hit "Cancel" on Windows Setup's "Installing
+  Windows 11" screen, and boot races can land in the UEFI shell — either
+  way the build stalls until something answers. The watchdog polls the
+  VNC framebuffer the Packer plugin exposes (pinned to port 5901 in the
+  template), OCRs each frame with Apple Vision, and auto-dismisses the
+  quit dialog (clicking "No" at the OCR'd button position), answers the
+  "Press any key to boot from CD or DVD" prompt, and boots the ISO from
+  the UEFI shell. `build.sh` starts it around `packer build` and stops it
+  in the cleanup trap; skipped with a warning when `vncdotool` or the
+  Xcode command line tools are missing. Observed during the v1.0.0 build:
+  one cancel dialog dismissed, one EFI-shell boot rescued.
+
+## [windows-arm64-qemu-v1.0.0] - 2026-08-23
+
+### Added
+
+- Windows 11 (ARM64) sandbox image (`sandbox-windows-11`), built with the
+  Packer QEMU plugin on Apple Silicon (HVF accelerator). Windows 11 Pro
+  ARM64 from the official Microsoft ISO (bring-your-own), installed
+  unattended via `autounattend.xml` with swtpm-provided TPM 2.0 and edk2
+  AAVMF UEFI firmware; the ARM64 virtio drivers (viostor/vioscsi/NetKVM)
+  are staged into the unattend CD by `images/windows-arm64-qemu/build.sh`,
+  which
+  wraps `packer build` and also compresses the resulting qcow2 with zstd.
+  `scripts/build.sh` now delegates to a platform's `build.sh` wrapper when
+  one exists.
+- The image ships: Chocolatey + toolchain (Node.js, Python, Git, GitHub
+  CLI, ripgrep, jq, curl — versions pinned in the vars file), Visual
+  Studio Code (native arm64), Chrome (Chrome for Testing snapshot,
+  hash-pinned), Firefox, OpenCode, OpenCodeReview (`ocr`), the OpenChamber
+  web UI as a native service on port 4000, OpenSSH Server + RDP, a Docker
+  CLI client (remote engine via the host bridge), and the bridge tooling
+  (`socat` + `npiperelay`) as utilities.
+- `scripts/run-windows-qemu-sandbox.sh` — the user-facing Windows sandbox
+  runner, landing together with the user guide `docs/windows-qemu.md`: boots
+  the qcow2 under `qemu-system-aarch64` + swtpm (working VM = COW overlay
+  with persistent TPM/NVRAM under `~/Library/Application Support/
+  agent-dev-env/windows-11`), forwards SSH/RDP/WinRM/OpenChamber ports,
+  re-enables Windows auto-logon (the image's `LogonCount=1` disables it
+  after the OOBE boot) so the OpenChamber task fires at boot, and bridges
+  the host's SSH agent and Docker engine into the guest: host-side socat
+  on TCP 4200/4201 (loopback only) + guest-side Node relays serving the
+  `\\.\pipe\openssh-ssh-agent` and `\\.\pipe\docker_engine` named pipes
+  (started detached via a SYSTEM scheduled task — sshd's session job would
+  kill in-session children). Docker context `host` is created and made the
+  default.
+- `images/windows-arm64-qemu/deploy.sh` — platform deploy wrapper that
+  pushes the qcow2 to GHCR as an OCI artifact with `oras`
+  (`ghcr.io/<owner>/sandbox-windows-11:<version>` + `:latest`);
+  `scripts/deploy.sh` delegates to it like `build.sh` does (the macOS
+  `tart push` flow cannot push a qcow2).
+- Known limitations at this stage: no host-folder mount (the virtio-fs
+  driver has no ARM64 Windows build) and Windows runs unactivated with a
+  watermark. The sandbox agent rules (`scripts/agent-rules.md`) are
+  macOS-flavored and not installed into Windows guests yet.
+
+[unreleased]: https://github.com/ameshkov/agent-dev-env/compare/windows-arm64-qemu-v1.1.0...HEAD
+[windows-arm64-qemu-v1.1.0]: https://github.com/ameshkov/agent-dev-env/releases/tag/windows-arm64-qemu-v1.1.0
+[windows-arm64-qemu-v1.0.0]: https://github.com/ameshkov/agent-dev-env/releases/tag/windows-arm64-qemu-v1.0.0

package/dist/assets/images/windows-arm64-qemu/README.md

@@ -0,0 +1,142 @@
+# Windows Sandbox Images
+
+Windows 11 (ARM64) sandbox VM images built with [Packer](https://www.packer.io/)
+and the [QEMU plugin](https://developer.hashicorp.com/packer/integrations/hashicorp/qemu)
+on an Apple Silicon Mac. The output is a qcow2 disk image; the macOS host
+runs it under `qemu-system-aarch64` with the HVF accelerator (near-native
+performance — HVF can only virtualize ARM64 guests, so this image is
+ARM64-only).
+
+See [docs/macos.md](../../docs/macos.md) for the macOS images and
+[docs/windows-qemu.md](../../docs/windows-qemu.md) for the Windows sandbox
+user guide (boot it with `npx agent-dev-env run windows-qemu`).
+
+## Prerequisites
+
+- Apple Silicon Mac (M-series).
+- [QEMU](https://www.qemu.org/): `brew install qemu` (provides
+  `qemu-system-aarch64`, `qemu-img`, and the edk2 AAVMF firmware).
+- [swtpm](https://github.com/stefanberger/swtpm) for the virtual TPM 2.0
+  (Windows 11 system requirement): `brew install swtpm`.
+- [Packer](https://www.packer.io/): `brew install hashicorp/tap/packer`
+  (the QEMU plugin is installed automatically by `packer init`).
+- The **Windows 11 ARM64 ISO** — bring your own, Microsoft does not permit
+  redistribution:
+
+  1. Visit [Download Windows 11 (ARM64)](https://www.microsoft.com/software-download/windows11arm64)
+     and generate a download link (no Insider login required).
+  2. Download the ISO (e.g. `Win11_24H2_English_Arm64.iso`, ~5 GB) and
+     copy the SHA256 shown on the page into `iso_sha256` in the vars file.
+  3. Set `WINDOWS_ISO_PATH` to its absolute path when building.
+
+- **virtio-win.iso** with ARM64 drivers (release 0.1.240 or later). The
+  wrapper downloads it automatically from the URL pinned in the vars file,
+  or you can point `VIRTIO_WIN_ISO_PATH` at a local copy.
+
+## How to Build
+
+```bash
+# From the repository root
+WINDOWS_ISO_PATH=/path/to/Win11_24H2_English_Arm64.iso \
+  npx agent-dev-env build sandbox-windows-11-arm64-qemu
+```
+
+`agent-dev-env` is the CLI shipped by this repo (see
+[docs/cli.md](../../docs/cli.md)). The windows-qemu build flow:
+
+1. Verifies the host (Apple Silicon), the tools, and the Windows ISO
+   (SHA256 against `iso_sha256` from the vars file).
+2. Downloads virtio-win.iso into the build cache unless
+   `VIRTIO_WIN_ISO_PATH` is set.
+3. Mounts virtio-win.iso and stages the ARM64 `viostor` / `vioscsi` /
+   `NetKVM` driver subset into `drivers/staging/`, which Packer packs
+   into the same CD as `autounattend.xml` (WinPE drive-letter
+   enumeration on ARM64 is non-deterministic, so a separate drivers CD
+   would be a guessing game).
+4. Starts `swtpm` (TPM 2.0) and runs `packer init` + `packer build`
+   with the vars file; Packer's `qemu_binary` points at
+   `qemu-with-tpm.sh`, which appends the TPM/ramfb/USB/CD-ROM wiring the
+   plugin's `qemuargs` option cannot express.
+5. Runs a VNC **build watchdog** (bundled `assets/watchdog/`) alongside
+   `packer build`: the headless boot's Enter-spam can hit "Cancel" on
+   Windows Setup's "Installing Windows 11" screen, and boot races can land
+   in the UEFI shell — the watchdog OCRs the VNC framebuffer (Apple
+   Vision, pinned VNC port 5901) and auto-dismisses the dialog, answers
+   the "Press any key" prompt, or boots the ISO from the shell. Needs
+   `pip3 install vncdotool`; skipped with a warning when missing.
+6. Compresses the resulting qcow2 with zstd.
+
+A build takes roughly 30 minutes on an M-series Mac (Windows Setup itself
+dominates; HVF runs the guest at near-native speed). Everything per image
+lives under the CLI's data root:
+`~/Library/Application Support/agent-dev-env/build/windows-qemu/output/`
+(`sandbox-windows-11-arm64-qemu.qcow2`, compressed with zstd), plus
+`packer_cache/` and `drivers/staging/`. The macOS/tart images build no
+files and have no such directory.
+
+## What's in the image
+
+| Component | Detail |
+| --- | --- |
+| Windows 11 Pro (ARM64) | Unactivated (watermark); generic Pro key used for Setup |
+| VirtIO drivers | viostor/vioscsi, NetKVM, viogpudo (virtio-gpu display — drives the runtime VM's virtio-gpu-pci) from the unattend CD; vioserial, balloon + qemu guest agent from virtio-win guest tools |
+| Chocolatey | Community package manager (versions pinned in the vars file) |
+| Node.js, Python, Git, gh, ripgrep, jq, curl | Choco packages (versions from the vars file) |
+| Go, Vim, NuGet, make, MinGW-w64 | Choco packages (versions from the vars file) |
+| Rust | Via rustup (arm64 host toolchain + MSVC targets for x86_64/i686/aarch64), `rust`/`cargo` on PATH |
+| VS2022 Build Tools | Choco + `setup.exe` finalizer: .NET 4.8/.NET Core SDKs, VC++ workload (x86/x64/ARM/ARM64), CMake, Windows 11 SDK |
+| WiX, protoc, NASM, LLVM | Choco packages (versions from the vars file) |
+| Visual Studio Code | Native arm64 build, latest stable, direct download; `code` on PATH |
+| Google Chrome | Chrome for Testing snapshot, hash-pinned (see the vars file); x64, runs under Prism emulation |
+| Firefox | Choco package (x64, runs under Prism emulation) |
+| OpenCode (`opencode-ai`) | npm global |
+| OpenCodeReview (`ocr`) | npm global (`@alibaba-group/open-code-review`) |
+| OpenChamber web UI | npm global (`@openchamber/web`), native service on `0.0.0.0:4000` |
+| OpenSSH Server + RDP | Enabled; Administrator/sandbox1 (see the vars file) |
+| Docker CLI | Client only (`docker` + `docker compose`), remote engine via the host bridge |
+| Bridge tooling | Node relays (in-image `node.exe`, written by the runner) for the SSH-agent/Docker bridges — the host side is the CLI's own forwarder (no socat) |
+
+## Versioning
+
+Same convention as the macOS images: the image version lives in
+`image_version` in the vars file; every release bumps it, adds a
+`CHANGELOG.md` entry, and creates a `windows-arm64-qemu-v<version>` git
+tag via `npx agent-dev-env tag <image>`.
+
+## Running and publishing
+
+- Run the sandbox: `npx agent-dev-env run windows-qemu` — boots the qcow2
+  under QEMU + swtpm in a resizable window, forwards SSH/RDP/OpenChamber
+  ports, and bridges the host's Docker engine and SSH agent into the
+  guest (see [docs/windows-qemu.md](../../docs/windows-qemu.md)).
+- Publish: `npx agent-dev-env deploy sandbox-windows-11-arm64-qemu` pushes
+  the qcow2 to
+  `ghcr.io/<owner>/sandbox-windows-11-arm64-qemu:<version>` + `:latest` as
+  an OCI artifact via `oras` (the CLI pushes the qcow2 directly — no
+  platform wrapper — because `tart push` only works for Tart VMs). Needs
+  `brew install oras` and a GHCR token with `write:packages`
+  (`oras login ghcr.io`).
+
+## Gotchas
+
+- **The Windows ISO is not in the repo.** The build fails fast without
+  `WINDOWS_ISO_PATH`; the sha256 in the vars file protects against a
+  corrupt download.
+- **ARM64 only.** x86_64 Windows under QEMU on Apple Silicon runs on TCG
+  (pure emulation) and is unusably slow; HVF only virtualizes ARM64.
+- **virtio-win ≥ 0.1.240** is required for ARM64 driver builds; older
+  releases fail at the driver-staging step.
+- **No shared folder.** The virtio-fs driver has no ARM64 Windows build
+  (virtio-win issue #1337), so there is no host-directory mount like the
+  macOS image's shared `dev` volume — use git, RDP clipboard, or the
+  OpenChamber web UI instead.
+- **Unactivated Windows.** The image runs indefinitely with a desktop
+  watermark; personalization (wallpaper) is locked.
+- **`qemuargs` replaces, not appends.** Any change that needs extra qemu
+  args belongs in `qemu-with-tpm.sh`, not in the template's `qemuargs`.
+- **USB enumeration order is load-bearing.** The install ISO's
+  usb-storage device must precede virtio-win.iso's, or EDK2 drops to the
+  EFI Shell instead of booting Setup — keep the argv layout in
+  `qemu-with-tpm.sh` intact.
+- **Computer name ≤ 15 chars.** `win11-sandbox` fits; longer names fail
+  the specialize pass even though `xmllint`/`packer validate` pass.