docs: add a docs/ book served by GitHub Pages, slim the README

Mirror cocoon's docs layout: topic-named pages plus an index.md landing
(tagline, CLI diagram, Guides + Features lists) under jekyll-theme-primer; keep
the README to a tagline, quickstart, and links. Refresh the image pull section
for the parallel Range download.

Author: CMGS

README.md

@@ -0,0 +1,3 @@
+title: cocoon-macos
+description: macOS VM engine for x86 Linux/KVM, built on cocoon
+theme: jekyll-theme-primer

docs/_config.yml

@@ -0,0 +1,54 @@
+# CLI Reference
+
+The CLI mirrors cocoon's `vm` / `image` command surface, trimmed to the macOS VM path.
+
+## Images
+
+```bash
+# pull the golden qcow2 from ghcr into the local store (cocoon cloudimg; /var/lib/cocoon-macos)
+cocoon-macos image pull ghcr.io/cocoonstack/cocoon-macos/tahoe:26
+cocoon-macos image list        # table (NAME TYPE SIZE DIGEST CREATED); -o json for JSON
+cocoon-macos image inspect <ref>
+cocoon-macos image rm <ref>
+```
+
+See [Images](images.md) for the store layout and the parallel-Range download.
+
+## VMs
+
+```bash
+# clone the golden image into a per-VM overlay and boot it (x86 Linux + /dev/kvm).
+# IMAGE is a store ref or a direct qcow2 path; firmware defaults to the doctor's install.
+cocoon-macos vm run ghcr.io/cocoonstack/cocoon-macos/tahoe:26 \
+  --name m1 --cpus 4 --memory 8192 --ssh-port 2222 --vnc 1 --random-smbios
+
+cocoon-macos vm list           # table (NAME STATE CPU MEM NET VNC SSH IMAGE CREATED); -o json for JSON
+cocoon-macos vm inspect m1     # full record as JSON
+cocoon-macos vm stop m1
+cocoon-macos vm rm m1
+# also: create (no boot), start, console
+```
+
+- `create` scaffolds the VM (overlay, identity, network, record) without booting; `run` = `create` +
+  boot; `start` boots a created/stopped VM.
+- `run` is atomic: if the boot fails it removes everything it just created (no half-made VM left
+  behind).
+
+Networking (`--net`) and VNC (`--vnc` / `--vnc-password`) are covered in
+[Networking & VNC](networking.md); snapshot/clone and `--data-disk` in
+[Snapshot, Clone & Data Disks](snapshots.md).
+
+## What `vm run` does
+
+1. `qemu-img create -b <golden> overlay.qcow2` — instant copy-on-write clone of the golden image.
+2. Copy a per-VM `OVMF_VARS`.
+3. With `--random-smbios`, copy OpenCore per-VM and inject a generated identity into its
+   `config.plist` `PlatformInfo/Generic` via a `qemu-nbd` mount — model stays `iMac19,1` (proven to
+   boot Tahoe), only serial/MLB/UUID/ROM are randomized. The identity is recorded and shown by
+   `vm inspect`.
+4. Launch `qemu-system-x86_64` daemonized with the boot recipe (a `Skylake-Client-v4` CPU spoofing
+   `GenuineIntel`, `isa-applesmc` OSK, OVMF, the LongQT OpenCore loader, and the macOS qcow2). The
+   same recipe boots macOS identically on Intel and AMD; on AMD it also sets `kvm.ignore_msrs=1`
+   (macOS reads MSRs an AMD host lacks). See [Boot, Firmware & GUI](vm.md).
+
+State is recorded under `--state-dir` / `$COCOON_MACOS_HOME` (default `/var/lib/cocoon-macos`).

docs/cli.md

@@ -0,0 +1,37 @@
+# E2E Regression
+
+`scripts/e2e.sh` is a testbed lifecycle regression (modeled on cocoon's), in two tiers.
+
+## `[DUMMY]` — file-level, no macOS boot
+
+Runs on any x86 Linux/KVM host against a tiny throwaway qcow2 (no macOS boot):
+
+- Image store (`pull`-less `list`/`rm`).
+- `vm create` overlay-on-shared-base.
+- `--random-smbios` serial/MAC uniqueness + MAC == ROM.
+- `snapshot`/`restore` (qcow2-internal tag rollback).
+- `clone` (CoW on the shared base + distinct identity + clone-of-clone backing).
+- `stop` PID-reuse-safe teardown.
+- `--net bridge` auto-TAP create + `tap_owned` + teardown-on-`rm` + user-`--tap` preservation +
+  negative paths.
+
+Post-conditions assert no leaked TAPs/procs and backing-chain integrity. The `--random-smbios` rows
+need `root` + `nbd` + a real `CM_OPENCORE`; the `--net` rows need `root` + a test bridge (they `SKIP`,
+not `FAIL`, otherwise).
+
+## `[REAL]` — boots the golden image
+
+Boots `tahoe:26` from the store, passes the OpenCore picker over the HMP monitor, and asserts
+SSH-ready (`sw_vers` 26.x) + in-guest serial == injected. Testbed-only.
+
+## Running
+
+```bash
+sudo CM_BIN=./cocoon-macos CM_OPENCORE=.../OpenCore.qcow2 ./scripts/e2e.sh          # [DUMMY] (30 rows)
+sudo CM_HOME=~/cm-demo CM_OPENCORE=... CM_OVMF_CODE=... CM_OVMF_VARS=... \
+  ./scripts/e2e.sh --real-only
+```
+
+The `[DUMMY]` tier is the behavioral gate today's CI structurally can't give (CI is pure `go test` /
+`vet` / build — nothing opens `/dev/kvm` or mutates netlink); it belongs on a privileged self-hosted
+KVM runner. `[REAL]` stays a manual/nightly testbed run (~15 GB + cold boot).

docs/e2e.md

@@ -0,0 +1,46 @@
+# CI Image Pipeline
+
+The golden images are built entirely by CI:
+`.github/workflows/build-macos-image.yml` + `scripts/build-qemu-macos.sh`.
+
+It is a `workflow_dispatch` with a `macos` version and a `stage`. This pipeline is **image-only**
+(no Go); the CLI end-to-end (`vm run` + `--random-smbios`) is exercised separately on a KVM testbed,
+keeping image and Go CI apart.
+
+## `macos` — which OS
+
+`macos` selects the OS to build and where it lands on ghcr (the build script derives
+`MACOS_SHORTNAME` / `GHCR_REPO` / `GHCR_TAG` from it):
+
+| `macos` | fetch-macOS shortname | ghcr repo:tag |
+|---------|-----------------------|---------------|
+| `tahoe` (default) | `tahoe` | `…/tahoe:26` — macOS 26, the **last Intel** macOS |
+| `sequoia` | `sequoia` | `…/sequoia:15` — macOS 15 (n-1, still security-supported) |
+
+The same OSX-KVM multi-version OpenCore and the same provision recipe build either OS — only the
+recovery shortname and tag differ.
+
+## `stage` — how far the build goes
+
+Shown for `tahoe:26`; the actual `repo:tag` follows `macos`.
+
+| stage | what |
+|-------|------|
+| `boot` | Smoke: boot OpenCore → macOS Recovery (proves KVM + OpenCore + recovery). |
+| `install` | Full install from scratch → capture → push `<repo>:<tag>-base` (~65 min). |
+| `setup` | Pull `<repo>:<tag>-base` → boot Recovery → `provision-macos.sh` (SA-skip recipe + user + SSH) → push `<repo>:<tag>`. |
+| `slim` | Pull `<repo>:<tag>` → boot → reclaim stale clusters → re-push `<repo>:<tag>` (smaller). |
+| `verify` | Pull `<repo>:<tag>` → boot → confirm login + SSH (`cocoon@localhost`). |
+
+## Automation primitives
+
+- **`scripts/qmp-input.py`** — QMP absolute mouse click/move, keyboard type/chord, **Tesseract + PIL
+  OCR-click and title routing** (drives the macOS GUI installer where buttons can't be reached by the
+  keyboard), and HMP `screendump`.
+- **`scripts/provision-macos.sh`** — runs in the Recovery Terminal against the installed Data volume:
+  offline `dscl -f` user, `.AppleSetupDone`, and a first-boot LaunchDaemon that enables Remote Login.
+
+## Host facts
+
+GitHub `ubuntu-latest` exposes `/dev/kvm` (needs `chmod 666`). macOS Tahoe 26 is the last
+Intel-supporting macOS, so this x86 path has a finite shelf life.

docs/image-pipeline.md

@@ -0,0 +1,40 @@
+# Images
+
+## Golden images on ghcr
+
+The CI pipeline (see [CI Image Pipeline](image-pipeline.md)) publishes two tiers per OS:
+
+| Ref | Contents |
+|-----|----------|
+| `…/tahoe:26-base` | Installed macOS at the first-run Setup Assistant. |
+| `…/tahoe:26` | Provisioned & **SSH-ready**: admin `cocoon`/`cocoon`, complete home, Remote Login on first boot. |
+
+`sequoia:15` / `sequoia:15-base` are the macOS 15 (n-1) equivalents. The image is a single immutable
+qcow2 blob — **qcow2-only**, no OCI layer filesystem.
+
+## Local store
+
+`image pull` imports the golden qcow2 into a **content-addressed store** under
+`<state-dir>/cloudimg` (cocoon's `cloudimg` backend, imported directly). `vm run <ref>` then bakes a
+copy-on-write overlay on the immutable shared base, so many VMs share one on-disk copy.
+
+```bash
+cocoon-macos image pull ghcr.io/cocoonstack/cocoon-macos/tahoe:26
+cocoon-macos image list
+```
+
+## Parallel Range download
+
+A single HTTP/2 stream to ghcr is throttled and often reset mid-transfer on multi-GB blobs. `image
+pull` therefore downloads the qcow2 layer in **8 concurrent HTTP Range chunks** to a temp file, then
+verifies the SHA-256 against the layer digest before importing:
+
+- The `oras-go` SDK resolves the manifest, credentials (from the user's Docker config; public images
+  pull anonymously), and the qcow2 layer descriptor — **no external `oras` binary** is needed.
+- Each chunk is fetched with a `Range` request that follows ghcr's redirect to its presigned CDN URL;
+  the response's `Content-Range` and length are validated per chunk (a misbehaving CDN can't silently
+  corrupt the file), and the assembled file's digest must match before import.
+- If the registry doesn't support `Range`, it falls back to a single stream. The whole pull retries
+  up to 3 times on transient drops.
+
+This is both faster (parallel chunks saturate the link) and more robust than a single stream.

docs/images.md

@@ -0,0 +1,71 @@
+# cocoon-macos
+
+macOS VM engine for x86 Linux/KVM, built on
+[cocoon](https://github.com/cocoonstack/cocoon). Boots real macOS guests
+(Sequoia 15, Tahoe 26) as fully-virtualized [QEMU](https://www.qemu.org/)/KVM
+VMs via [OpenCore](https://github.com/acidanthera/OpenCorePkg) + OVMF. A GitHub
+Action installs macOS from scratch and publishes a golden qcow2 to ghcr; a thin
+Go CLI clones that image and boots VMs from it.
+
+```
+cocoon-macos CLI ──► image: pull the golden macOS qcow2 from ghcr (parallel Range, sha256)
+                 ──► vm: create/run/console/clone ── QEMU + OpenCore + OVMF, CoW disk, CNI real IP
+                 ──► snapshot: save/restore ── offline qcow2-internal, per-VM Apple identity
+```
+
+## Guides
+
+- [Installation](install.md) — host prerequisites, the doctor script (deps +
+  firmware), the state directory, and building the CLI
+- [CLI reference](cli.md) — the `image` and `vm` commands, key flags, and what
+  `vm run` does under the hood
+- [Images](images.md) — golden images on ghcr, the local cloudimg store, and the
+  parallel-Range `image pull`
+- [VM boot & firmware](vm.md) — the OpenCore/OVMF/CPU recipe, the desktop/GUI
+  status, and the Setup-Assistant blocker
+- [Networking & VNC](networking.md) — `--net user/tap/bridge/cni`, TC-redirect
+  real LAN IP, and per-mode / per-start VNC exposure
+- [Snapshots, clone & data disks](snapshots.md) — offline snapshots, CoW clones
+  with a fresh identity, and extra data disks
+- [CI image pipeline](image-pipeline.md) — how the GitHub Action installs macOS
+  and publishes the golden images
+- [E2E regression](e2e.md) — the `e2e.sh` lifecycle regression (`[DUMMY]` +
+  `[REAL]` tiers)
+- [Known issues](known-issues.md) — no-GPU video, display-sleep VNC blanking,
+  and the Setup Assistant
+- [Roadmap](roadmap.md) — what's planned, and what's intentionally out of scope
+
+## Features
+
+- **Fully-automated macOS install** — CI boots OpenCore, erases APFS, drives the
+  installer by OCR, and publishes a golden qcow2 (Tahoe 26 / Sequoia 15) to ghcr
+- **SSH-ready golden images** — `tahoe:26` ships an admin `cocoon`/`cocoon` user,
+  a complete home, and Remote Login on first boot (plus a `-base` tier)
+- **Parallel Range image pull** — the multi-GB qcow2 is pulled in 8 concurrent
+  HTTP Range chunks with an sha256 digest check (oras-go for auth; no `oras` binary)
+- **COW overlays** — an instant copy-on-write clone of the immutable golden base
+  per VM
+- **Per-VM Apple identity** — `--random-smbios` injects a unique serial/MLB/UUID/ROM
+  (guest MAC = ROM) into a per-VM OpenCore, so clones never share a serial
+- **CNI networking with TC redirect** — `--net cni` joins cocoon's forwarding
+  plane so the guest DHCPs a real LAN IP; also `user`/`tap`/`bridge`
+- **Reachable VNC** — loopback VNC on user/tap/bridge; a host-side proxy fronts
+  CNI VNC on the host port (password required); launch-scoped, off by default
+- **Snapshot, clone & restore** — offline qcow2-internal snapshots and CoW clones
+  that cold-boot a fresh Apple identity
+- **Data disks** — up to 4 extra qcow2 data disks on the AHCI ports the OS disk
+  and OpenCore leave free (macOS has no virtio-blk driver)
+- **Intel & AMD** — one boot recipe (Skylake-Client spoofing GenuineIntel + the
+  LongQT OpenCore) boots identically on both; `ignore_msrs` auto-set on AMD
+- **Docker-like CLI** — `create`, `run`, `start`, `stop`, `list`, `inspect`,
+  `console`, `rm`, `snapshot`, `restore`, `clone`
+- **Built on cocoon** — imports cocoon's `cloudimg` store, `network` plane, and
+  copy-on-write conventions rather than reimplementing them
+
+## Repository
+
+Source and issue tracker:
+[github.com/cocoonstack/cocoon-macos](https://github.com/cocoonstack/cocoon-macos).
+Upstream engine:
+[github.com/cocoonstack/cocoon](https://github.com/cocoonstack/cocoon)
+(Lightweight MicroVM engine with Cloud Hypervisor and Firecracker backends).

docs/index.md

@@ -0,0 +1,43 @@
+# Installation
+
+## Prerequisites
+
+- **x86-64 Linux** with **KVM** (`/dev/kvm` present and accessible). Both Intel and AMD hosts work —
+  the same boot recipe applies to both; you never choose "OpenCore vs LongQT".
+- `qemu-system-x86_64`, `qemu-nbd` (from `qemu-utils`), and NBD kernel module support.
+- Enough disk for the golden image (~15 GB) plus per-VM CoW overlays.
+
+## Build the CLI
+
+```bash
+go build -o cocoon-macos .
+```
+
+## Provision the host (`scripts/doctor.sh`)
+
+Run once per host. `doctor.sh`:
+
+1. Checks `/dev/kvm` and installs any missing dependencies (`qemu`, OVMF, `gdisk`, `dosfstools`),
+2. Loads the `nbd` kernel module,
+3. Provisions the **shared firmware** into `<state-dir>/firmware` — it downloads the LongQT OpenCore
+   release and bakes a GPT/ESP `OpenCore.qcow2` plus the 4 MB OVMF `CODE`/`VARS`. Every VM reuses this
+   one firmware install.
+
+```bash
+sudo scripts/doctor.sh
+```
+
+`vm run` fails with a "run scripts/doctor.sh" message when the firmware is absent. You can override
+any piece with `--opencore` / `--ovmf-code` / `--ovmf-vars` on the VM commands.
+
+## State directory
+
+All persistent state lives under `--state-dir` / `$COCOON_MACOS_HOME`, default
+`/var/lib/cocoon-macos` (mirroring cocoon's `/var/lib/cocoon`):
+
+```
+/var/lib/cocoon-macos/
+├── firmware/     # shared OpenCore.qcow2 + OVMF_CODE/VARS (from doctor.sh)
+├── cloudimg/     # content-addressed golden-image store (image pull)
+└── vms/<name>/   # per-VM: disk.qcow2 overlay, OVMF_VARS, OpenCore overlay, vm.json, sockets
+```

docs/install.md

@@ -0,0 +1,32 @@
+# Known Issues
+
+## No GPU → hardware-accelerated video renders black
+
+The display is `-device vmware-svga` (macOS's only supported virtual adapter): a **2D software
+framebuffer with no Metal / GPU / VideoToolbox / IOSurface**. CPU-drawn content renders fine —
+desktop, widgets, window chrome, and *static* images (e.g. a YouTube thumbnail) — but **live video
+playback** uses a GPU-composited hardware overlay (AVPlayerLayer + IOSurface + VideoToolbox) with no
+backing on a GPU-less VM, so the moving picture stays **black even though audio plays and the scrubber
+advances**. Safari has no software-rendering fallback.
+
+- **Workaround:** Chrome with hardware acceleration off (Settings → System → uncheck "Use hardware
+  acceleration when available", relaunch) composites video in software into a layer the framebuffer
+  can draw.
+- **No display-device fix:** `qxl` / `virtio-gpu` / `std` have no macOS driver, so swapping `-vga` /
+  `-device` cannot add acceleration.
+- **Real fix:** GPU passthrough (VFIO `-device vfio-pci`) — see [Roadmap](roadmap.md).
+
+## VNC blanks on display sleep
+
+macOS only repaints the emulated framebuffer while the display is **awake**; once it sleeps (~idle),
+VNC shows a blank white/black screen with just the cursor even though the guest is healthy (SSH works,
+WindowServer is up). A mouse move repaints it — it is *not* a GPU/driver problem. The golden image's
+first-boot daemon runs `pmset -a displaysleep 0 disablesleep 1` system-wide (covering the pre-login
+loginwindow) to keep the framebuffer painted; older images need a `setup`-stage rebuild.
+
+## GUI lands at the Setup Assistant
+
+A fresh macOS 26 clone boots to the system Setup Assistant, which resists every offline marker-based
+skip tried (macOS 14+ broke the classic `.AppleSetupDone` skip). `:26` is SSH/VNC-login-usable, but a
+fully unattended boot-to-desktop needs a mouse/OCR click-through of the SA wizard — see the WIP detail
+in [VM Boot & Firmware](vm.md) and the [Roadmap](roadmap.md).

docs/known-issues.md

@@ -0,0 +1,61 @@
+# Networking & VNC
+
+## Network modes (`--net`)
+
+| Mode | What it does |
+|------|--------------|
+| `user` (default) | User-mode SLIRP. Combine with `--ssh-port N` to forward `localhost:N → guest:22`. Works everywhere. |
+| `tap` | Attach to a pre-created host TAP verbatim (`--tap tap0`) — the bridge/plane owns IP + forwarding. |
+| `bridge` | Auto-create a TAP on an existing Linux bridge (`--bridge br0`) via cocoon's `network/bridge`. |
+| `cni` | Auto-create a TAP inside a per-VM netns via cocoon's `network/cni` (TC-redirect plane). |
+
+`tap`/`bridge`/`cni` make a macOS VM join the **same** forwarding plane as cocoon's Cloud
+Hypervisor / Firecracker VMs on the node, so the guest can DHCP a **real LAN IP** from the upstream
+network. The guest NIC MAC stays equal to the SMBIOS ROM. Auto-create (`bridge`/`cni`) is Linux-only
+(needs `CAP_NET_ADMIN`); `user` and a pre-created `--tap` work everywhere.
+
+### `--net cni` and TC redirect
+
+CNI runs QEMU inside a per-VM network namespace. cocoon's CNI wires the netns veth to the QEMU TAP
+with **TC ingress redirect** (`mirred`), not a bridge — the guest's DHCP/traffic flows
+tap → eth0 → `cni0` → upstream, and it comes back the same way. The guest gets a real ToR IP; SSH
+goes straight to that IP (no port-forward).
+
+## VNC exposure
+
+VNC exposure depends on the net mode:
+
+- **`--net user | tap | bridge`** — QEMU binds VNC **loopback-only** (`127.0.0.1:590<vnc>`). Reach it
+  by tunnelling: `ssh -L 5901:127.0.0.1:5901 <host>`.
+- **`--net cni`** — QEMU runs in a netns, so its `127.0.0.1` bind would be unreachable off-box.
+  Instead VNC rides a unix socket fronted by a small host-side proxy on **all interfaces**
+  (`0.0.0.0:590<vnc>`). Because that is reachable off the host, **`--vnc-password` is required** for
+  `--net cni` — the launch is rejected without it.
+
+VNC is **launch-scoped**: it is off unless `--vnc` is given for that launch, it is cleared on
+`vm stop`, and it is re-enabled per start:
+
+```bash
+cocoon-macos vm start m1 --vnc 1 --vnc-password s3cret   # this run only
+cocoon-macos vm stop  m1                                 # VNC gone with the qemu it belonged to
+```
+
+The VNC password is never written to disk — it is read from the flag on each start.
+
+### macOS Screen Sharing
+
+QEMU's default `None` auth **hangs macOS Screen Sharing**. Pass `--vnc-password <≤8 chars>` (applied
+via the QEMU monitor post-launch, capped at 8 chars by the VNC DES scheme) so Screen Sharing prompts
+and connects. Plain VNC clients (RealVNC/TigerVNC) work without a password on the loopback modes.
+
+> In-guest macOS Screen Sharing (to the guest's own IP) is **not** enabled headlessly — macOS
+> requires the Screen Recording TCC grant from the GUI or MDM. Use QEMU's built-in VNC above instead.
+
+## Display sleep blanks VNC
+
+macOS only repaints the emulated framebuffer while the display is **awake**; once it sleeps (~idle),
+VNC shows a blank white/black screen with just the cursor even though the guest is healthy (SSH works,
+WindowServer is up). It is *not* a GPU/driver problem — a mouse move repaints it. The golden image's
+first-boot daemon runs `pmset -a displaysleep 0 disablesleep 1` system-wide (covering the pre-login
+loginwindow) to keep the framebuffer painted; older images need a `setup`-stage rebuild. See also the
+GPU/video note in [Boot, Firmware & GUI](vm.md).