feat: scripts/vminstall.sh installs an ssh-ready test VM unattended; TESTPLAN.md; vm-install skill

.claude/skills/cachyos-vm-testing/SKILL.md

@@ -69,6 +69,43 @@ the steam-machine-testing skill). From the Mac:
 - A fresh install has no `/media`: the guest setup is
   `sudo mkdir -p /media && sudo mount -t 9p -o trans=virtio,version=9p2000.L vmtools /media && /media/guest-ssh-setup.sh`.
 
+## No VM yet
+
+Create one with `scripts/vminstall.sh` (the vm-install skill): unattended,
+ends with the snapshots `clean` and `ssh-ready`. Pass its `VM_DIR` to every
+script. Login by hand: your host username, password `steamify`.
+
+## Test plan
+
+`TESTPLAN.md` (repo root) lists what to test per release (regression,
+features, Steam Machine only) and logs every run. Follow it, add a section
+for every new feature, and add a line to its results log after each run.
+
+## Start of every session: update the snapshot first
+
+A snapshot's package databases age quickly: the mirrors drop the versions it
+knows (404s, then "signature is invalid" on partial downloads) and the
+conversion's package install fails, which looks like a wizard bug. So once
+per session, before any test, bring `ssh-ready` up to date and overwrite it
+(visibly, in a Konsole on the VM's desktop):
+
+```bash
+scripts/vmreset.sh --fremont
+# in the guest (Konsole): keyrings first, then everything else
+sudo pacman -Sy --noconfirm archlinux-keyring cachyos-keyring
+sudo pacman -Su --noconfirm --needed tmux shellcheck
+sudo pacman -Scc --noconfirm
+sudo systemctl poweroff
+# on the host, in the VM dir, once QEMU is gone:
+qemu-img snapshot -d ssh-ready disk.qcow2
+qemu-img snapshot -c ssh-ready disk.qcow2 && cp vars.fd vars.ssh-ready.fd
+```
+
+Keep `/etc/plasmalogin.conf.d/00-test-autologin.conf` in the snapshot: the
+VM then logs in at boot. After a plasmalogin update, restarting it from a
+booted greeter fails (`HELPER_TTY_ERROR`, start-limit-hit), so `vmreset.sh`
+only restarts it when Plasma isn't up yet.
+
 ## Quick start (the usual loop)
 
 ```bash
@@ -126,7 +163,8 @@ qemu-img snapshot -c my-state disk.qcow2 && cp vars.fd vars.my-state.fd       #
 ```
 
 Existing snapshots: `clean` (fresh install) and `ssh-ready` (sshd + host key +
-passwordless sudo). Reset to `ssh-ready` before each full test run.
+passwordless sudo, test autologin; brought up to date at the start of each
+session, see above). Reset to `ssh-ready` before each full test run.
 
 ## First-time guest setup
 

.claude/skills/steam-machine-iso/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: steam-machine-iso
-description: Use when working on the Steam Machine CachyOS ISO (repo steammachine-cachyos-live-iso) or Steamify's install-time mode (steamify.sh --defaults, --first-login) - building the ISO in podman on the Steam Machine, the Calamares Steamify step, simulating the installer in the test VM, and testing the first desktop login.
+description: Use when working on the Steam Machine CachyOS ISO (repo steammachine-cachyos-live-iso) or Steamify's install-time mode (steamify.sh --defaults, --first-login) - building the ISO in podman (in the test VM, or on the Steam Machine), the Calamares Steamify step, simulating the installer in the test VM, and testing the first desktop login.
 ---
 
 # Steam Machine ISO and Steamify's install-time mode
@@ -57,6 +57,26 @@ ssh steammachine bash -c "'export XDG_RUNTIME_DIR=/run/user/1000 DBUS_SESSION_BU
   `--wait`). Without KillMode=process QEMU dies with the unit; without REPO
   QEMU fails on the old repo path and the script waits 5 minutes for SSH.
 
+## Building the ISO in the test VM (preferred)
+
+The build needs no real hardware: run it in the test VM (CachyOS; create it
+with the vm-install skill), not on the Steam Machine. Not tried yet in the
+VM: note what differs here. In the VM (`vm_ssh`, visibly in a Konsole there):
+
+```bash
+sudo pacman -S --needed --noconfirm podman git
+git clone https://github.com/theupriser/steammachine-cachyos-live-iso ~/projects/steammachine-cachyos-live-iso
+sudo mount -t 9p -o trans=virtio,version=9p2000.L repo /mnt     # the Steamify checkout (REPO)
+cd ~/projects/steammachine-cachyos-live-iso && git checkout feat/steamify && ./steamify-prepare.sh /mnt
+```
+
+then the same `podman run` as below (paths in the VM; `~/projects/iso-build.log`).
+The ISO (~3.2 GB) fits the 60G disk; copy it out with
+`vm_scp "$VM_USER@$VM_HOST:~/projects/steammachine-cachyos-live-iso/out/desktop/*.iso" .`
+(`scripts/common.sh`), then install it with `scripts/vminstall.sh --iso`.
+Give the VM more room with a bigger disk if `out/`, `build/` and the package
+cache grow over several builds (`sudo rm -rf build out` between builds).
+
 ## Building the ISO (podman on the Steam Machine)
 
 Only podman is installed on the Steam Machine itself; the build tools live in
@@ -119,6 +139,11 @@ First desktop login as that user:
 
 ## Testing the ISO itself
 
+Unattended: `VM_DIR=~/projects/iso-vm scripts/vminstall.sh --iso <built iso> --fremont`
+(vm-install skill) installs it with the ISO's headless `cachyos-installer`;
+Calamares and its Steamify step don't run then, so run `steamify-install`
+from the live script for that part. Through Calamares by hand, as below.
+
 Install the built ISO in a **new** VM (`~/projects/iso-vm`: copy of run.sh,
 `share` symlink, `cachyos.iso` symlink to the build, own disk/vars; power the
 test VM off first, both use port 2222; `run.sh install --fremont` as a user

.claude/skills/vm-install/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: vm-install
+description: Use when there is no Steamify test VM yet, the VM should be reinstalled from scratch, or an ISO (CachyOS, later the Steamify CachyOS ISO) should be installed unattended into a VM - scripts/vminstall.sh installs it without any manual step and leaves the snapshots clean and ssh-ready.
+---
+
+# Installing the test VM unattended
+
+`scripts/vminstall.sh` turns an ISO into a ready test VM, no clicking:
+
+```bash
+VM_DIR=~/vms/steamify-vm scripts/vminstall.sh --fremont     # run.sh flags pass through
+VM_DIR=~/vms/iso-vm scripts/vminstall.sh --iso ~/Downloads/steamify-cachyos-<date>-x86_64.iso
+```
+
+Result in `$VM_DIR`: `disk.qcow2` with the snapshots `clean` (just
+installed) and `ssh-ready` (booted once, SSH/sudo/Plasma checked), their
+`vars.*.fd`, `run.sh` (this repo's), `vm-user`, `ssh-key`, `repo-path`,
+`known_hosts`, `install.log`. Every other script (`vmreset.sh`, `vmwatch.sh`,
+...) reads the user, key and repo from there: pass the same `VM_DIR`.
+
+## What gets installed
+
+CachyOS with the ISO's own headless installer (`cachyos-installer`,
+`"headless_mode": true`): KDE Plasma, plasma-login-manager, btrfs with the
+default subvolumes, Limine, `linux-cachyos` + `linux-cachyos-lts`, fish.
+Then `share/vminstall-post.sh` in the new system: hostname `steamify-vm`,
+sshd with the chosen key, passwordless sudo, the test autologin into Plasma
+(`/etc/plasmalogin.conf.d/00-test-autologin.conf`), `en_US.UTF-8`, the host's
+timezone, tmux + shellcheck, Limine `default_entry: 2` (the installer's
+config points at the folder, so the first boot would wait in the menu).
+
+## Login (by hand)
+
+- User: your host username (`id -un`), or `VM_USER=...`.
+- Password: **`steamify`** (user and root), or `VM_PASSWORD=...`.
+- SSH: `~/.ssh/steamify-vm_ed25519`. Made once, on the first install (the
+  script asks: that new key, or one of your own `~/.ssh/*.pub`), then always
+  used. An existing key is never overwritten. The VM's host key is kept in
+  `$VM_DIR/known_hosts`, never in `~/.ssh/known_hosts`.
+
+## How it works
+
+1. The ISO's kernel and initramfs are copied out (`udisksctl loop-setup`, no
+   root) and booted directly (`VM_KERNEL`/`VM_INITRD`/`VM_APPEND` in
+   `run.sh`) with `systemd.run=` (+ `systemd.wants=kernel-command-line.service`,
+   or the unit is only generated) running `curl http://10.0.2.2:<port>/vminstall-live.sh | bash` as root.
+2. `scripts/vminstall-server.py` serves the live script, `settings.json`,
+   `vminstall.env` and the post script on 127.0.0.1; the guest reaches the
+   host at 10.0.2.2 (QEMU user networking, any host network;
+   `VM_HOST_IP` for a bridged setup). The live system PUTs its log
+   (`install-www/install.log`, every 20 s) and the status back.
+3. The live desktop shows a Konsole following the install log; the serial
+   console is logged to `$VM_DIR/serial.log`, and root logs in there
+   without a password over `$VM_DIR/serial.log.sock` (for debugging).
+4. After `== ok` the VM powers off, `clean` is taken, it boots once for the
+   checks, powers off, `ssh-ready` is taken.
+
+Takes 15-30 minutes (mirrors, packages). Run it with `run_in_background`
+and wait with an until-loop on the log, e.g.
+`until grep -qaE '^== (ok|failed)' $VM_DIR/install-www/install.log; do sleep 20; done`.
+
+## Gotchas
+
+- Refuses an existing `disk.qcow2` without `--force` (asks YES), and a
+  running VM (port 2222).
+- Never edit `vminstall.sh` while it runs: bash reads it as it goes.
+- Don't match your own wait loop with `pgrep -f`/`pkill -f` on a pattern that
+  is part of that loop's command line.
+- Mirror 404s during the install are normal for an older ISO (pacman moves
+  on); `fatal library error, lookup self` in the chroot is harmless.
+- QMP screenshots don't work (virgl, "no surface"): watch the window, the
+  serial log, or the install log.
+
+## The Steamify CachyOS ISO (later)
+
+`--iso <steamify iso>` installs it the same way if it's archiso-based with
+`cachyos-installer`. The headless installer doesn't run Calamares, so the
+ISO's Steamify step (`steamify-install`) doesn't run by itself: run it in the
+live script after the install (`/usr/local/bin/steamify-install /mnt
+$VM_USER <options>`) when testing the ISO, and check
+`/var/log/steamify-install.log` in the installed system.