Merge pull request 'Specify an AVX2-capable CPU type at VM creation' (#15) from cpu-type into main

Reviewed-on: #15
Reviewed-by: branderson <brad@branderson.io>

proxmox/README.md

@@ -109,6 +109,7 @@ before you flip it rather than after.
 | System | Qemu Agent | ✓ — and see the note below, the tick alone does nothing |
 | Disks | Size | 128 GB. A devbox accumulates checkouts, container images and build caches, and it is not rebuilt on a schedule to clear them |
 | CPU | Cores | 4 |
+| CPU | **Type** | **`x86-64-v3` or better — not the default.** See below; the default cannot run at least one of dejima's harnesses, which requires AVX2 capability |
 | Memory | | 16384 MB. dejima builds its image and runs sessions; 8 GB works and is tight |
 | Network | Bridge | your normal bridge |
 | Network | **Firewall** | **✓ — this is the checkbox everything else depends on** |
@@ -125,6 +126,36 @@ channel the agent has nothing to attach to, the Summary pane shows no address,
 `qm shutdown` falls back to hoping ACPI is acted on, and a snapshot of a
 running VM stays crash-consistent.
 
+**AVX2 is needed if you want support for Cline.** Proxmox defaults a new VM to
+`x86-64-v2-AES`, which tops out at SSE4.2 and has no AVX at all. The Cline
+harness's CLI ships as a Bun-embedded compiled binary whose stock build needs
+AVX2. You'll need a CPU type which supports AVX2 if you plan to run Cline in the
+VM, and the minimum CPU type which supports this is `x86-64-v3`.
+
+On a v2 guest the binary dies on SIGILL, exit 132, before printing anything, and
+Cline publishes no baseline build to fall back to, so the harness being
+unavailable is not something the failure tells you.
+
+Three ways to get this wrong:
+
+- **`host` also works and costs more than it looks.** It pins the guest to the
+  exact CPU of the node it was created on, so live migration to any node that
+  differs stops working. `x86-64-v3` is the portable floor that still carries
+  AVX2, and any reasonably modern node meets it.
+- **A flags allowlist will not do it.** `cpu: <model>,flags=...` toggles a
+  small fixed set and AVX2 is not in it. It has to be the CPU *model*.
+- **Changing it on an existing VM needs a full stop and start.** A reboot from
+  inside the guest keeps the same QEMU process and therefore the same CPU
+  model, which presents as the setting not having taken.
+
+Worth checking rather than assuming, once the guest is up — and worth running
+on any devbox built before this section existed, since the alternative is
+discovering it as a crash with no output:
+
+```sh
+grep -qw avx2 /proc/cpuinfo && echo "  avx2 present" || echo "  NO AVX2 - fix the VM's CPU type"
+```
+
 **What a moving address does *not* break.** Not the firewall. Every rule in the
 next section keys on a *destination*, except the two inbound rules, which key
 on *your* client subnets — and Proxmox applies the whole set to this VM's tap