feat: Release testing, cleaner resets and screenshots; skill updates

- vmwatch.sh --release: run the newest GitHub release in the VM.
- vmreset.sh: skip the broken krfoss mirror, install shellcheck.
- vmshot.sh --clean: close Steam, CachyOS Hello and Konsole first.
- Skill: items 1-7, menu loop and restart question, current inputs, finish on a fresh snapshot, release testing, Steamify shortcut, zsh pitfall.

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

@@ -12,7 +12,11 @@ which components are on and toggles them to match the user's choice. Menu order:
 2. SteamOS theme (installs `cachyos-vapor` and applies the Vapor global theme with its desktop and window layout; needs a running Plasma session)
 3. Steam Deck/Machine icons (`STEAM_GAMEPADUI_ARGS -steamos3`)
 4. Single user mode (SDDM, no lock screen/user switching/log out; enabling it enables 1, disabling 1 disables it)
-5. Steam Machine support (only on DMI Valve/Fremont: leds-valve-dkms-git built for every kernel via `/etc/dkms/leds-valve-dkms.conf`, `ensure-kernel-headers.service`, udev rule, steamos-manager)
+5. Steamify shortcut (desktop icon + launcher entry that `curl | bash` the newest release; its gear icon is a release asset)
+6. Steam Machine support (only on DMI Valve/Fremont: leds-valve-dkms-git built for every kernel via `/etc/dkms/leds-valve-dkms.conf`, `ensure-kernel-headers.service`, udev rule, steamos-manager, powerdevilrc)
+7. Update BIOS (only on Fremont, an opt-in action, never pre-ticked; tickable only when Valve has a newer BIOS)
+
+Without `--fremont` the menu has only 1-5.
 
 Undo journals live in `~/.local/state/cachyos-gamescope-boot/` in the guest.
 
@@ -29,12 +33,23 @@ snapshot commands below run in that directory. `scripts/vmreset.sh` takes
 
 ```bash
 scripts/vmreset.sh --fremont        # restore ssh-ready, boot, mount repo, autologin, wait for Plasma
+                                    # (also skips the broken krfoss mirror, installs shellcheck)
 scripts/cmp.sh save                 # baseline of the KDE configs
-scripts/vmwatch.sh '1\n3\n\ny\nn\n' "Theme only"   # wizard in a visible Konsole in the VM
+scripts/vmwatch.sh '1\n3\n\ny\n' "Theme only"   # wizard in a visible Konsole in the VM
+scripts/vmwatch.sh --release '\ny\nm\nq\n' "Full run"   # the newest GitHub release instead of /mnt
 scripts/vmstate.sh                  # component state
-scripts/vmshot.sh /path/shot.png    # screenshot, then view it
+scripts/vmshot.sh --clean /path/shot.png    # screenshot (--clean: close Steam/Hello/Konsole first)
 ```
 
+**Always finish on a fresh `ssh-ready` snapshot**, ideally with `--release`
+once published. Re-applying or toggling on an already set-up VM hides
+first-install bugs: the DKMS override silently failed on a fresh system
+(`/etc/dkms` doesn't exist before `dkms` is installed), which no re-apply
+showed because `dkms` was there already.
+
+Long runs (full install: packages, yay, DKMS) take 10+ minutes: run them
+with `run_in_background` and wait with an until-loop, not chained sleeps.
+
 Prefer `vmwatch.sh` over `vmrun.sh` when the user is watching the QEMU
 window: `vmrun.sh` runs invisibly over SSH, so they see nothing happen.
 
@@ -134,21 +149,26 @@ guest). Manually, in the guest:
 
 ```bash
 export XDG_RUNTIME_DIR=/run/user/1000 WAYLAND_DISPLAY=wayland-0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
-printf '\ny\nn\n' | /mnt/steamify.sh
+printf '\ny\nm\nq\n' | /mnt/steamify.sh
 ```
 
 Menu input: a number toggles a component, an empty line continues, `a`
-re-applies what is on, `q` quits. Then `y` answers "Go ahead?" and `n` the
+re-applies what is on, `q` quits; then `y` answers "Go ahead?". The wizard
-restart question.
+**loops**: after a run it asks for Enter (back to the menu), or `[m]`/`[r]`
+(menu / restart now) when a restart is needed. On `q` with a restart pending
+it asks "Restart now? [Y/n]" (default **yes**): `n` goes back to the menu and
+the next `q` asks again. Input that runs out quits without restarting, so end
+scripted input right after the last `q` (or with `n`), never with an empty
+line at the restart question.
 
 | Input | Meaning |
 |---|---|
-| `'\ny\nn\n'` | first run, accept all |
+| `'\ny\nm\nq\n'` | first run, accept all (not the BIOS item), back to the menu, quit |
-| `'2\n\ny\nn\n'` | toggle the theme |
+| `'2\n\ny\n'` | toggle the theme |
-| `'a\ny\nn\n'` | re-apply what is on |
+| `'a\ny\nm\nq\n'` | re-apply what is on (includes the conversion, so a restart is pending) |
 | `'q\n'` | just show the menu |
-| `'1\n3\n\ny\nn\n'` | from all-off: theme only (Steam Machine too with `--fremont`; add `5\n` to drop it) |
+| `'1\n3\n5\n\ny\n'` | from all-off: theme only (with `--fremont` also add `6\n` to drop Steam Machine support) |
-| `'1\n\ny\nn\n'` | from a state where 1 is off: turn the conversion on |
+| `'1\n\ny\n'` | from a state where 1 is off: turn the conversion on |
 
 **Know the starting ticks before choosing input.** When *everything* is off
 (fresh snapshot, or after turning the last component off), the menu treats it
@@ -200,6 +220,16 @@ After changing the theme, `cmp.sh` should show only spectacle's
 `~/.config/kdedefaults` (e.g. `ColorScheme=BreezeDark`, `widgetStyle=Breeze`):
 KDE drops or writes those on its own.
 
+## Testing the newest release
+
+`scripts/vmwatch.sh --release '<input>'` downloads
+`releases/latest/download/steamify.sh` in the guest and runs it with the piped
+input (`WIZARD_KEEP_STDIN=1`; the bundle otherwise reattaches the terminal).
+Release assets only exist from the version that added them: before v0.9.0 was
+published, `steamify.sh` and the shortcut's `steam-gaming-settings.svg` gave
+404 and the shortcut fell back to Steam's icon. Check a release with
+`curl -sIL -o /dev/null -w '%{http_code}' .../releases/latest/download/<asset>`.
+
 ## Reboot checks
 
 - Single user mode on: SDDM autologin without greeter: `pgrep sddm-greeter` empty, `plasmashell` running.
@@ -210,7 +240,9 @@ KDE drops or writes those on its own.
 Reset to `ssh-ready`, start with `--fremont`, mount the repo, enable test
 autologin, then (all passed last run; `scripts/vmstate.sh` after every step):
 
-1. Fresh run turning everything on (`'\ny\nn\n'`), set session to plasma, reboot.
+1. Fresh run turning everything on (`'\ny\nm\nq\n'`), set session to plasma, reboot:
+   SDDM logs straight in, Vapor desktop, three desktop icons (Return to Gaming
+   Mode, Steam, Steamify CachyOS with the gear icon), LEDs loaded (17 nodes).
 2. Rerun: all shown on, "Everything is already the way you want it".
 3. `a` re-apply: no duplicate journal entries.
 4. Theme on: Steam Deck wallpaper, full-width 46px panel, `distributor-logo-steamdeck` launcher icon, `dark-lnf=com.valve.vapor.desktop` (Brightness & Color's Dark Mode toggle is on, hint "Switch to Breeze"); with single user on, kickoff keeps `primaryActions=3`. Theme off: CachyOS wallpaper, floating 30px panel, CachyOS launcher icon, BreezeDark colors (not light), `cachyos-vapor` removed, `cmp.sh` clean.
@@ -232,14 +264,26 @@ differs from Valve's newest. Fake an older one with
 the environment through). fwupd correctly refuses the firmware in the VM
 ("not for this machine's hardware"), so walk the whole flow with
 `WIZARD_BIOS_DRY_RUN=1` (skips only that check, never flashes). Scripted:
-`printf '6\n\ny\ny\nUPDATE\n\nq\n' | WIZARD_BIOS_DRY_RUN=1 /mnt/steamify.sh`.
+`printf '7\n\ny\ny\nUPDATE\nm\nq\nn\n' | WIZARD_BIOS_DRY_RUN=1 /mnt/steamify.sh`
+(BIOS is item 7 with `--fremont`; the final `n` answers the restart question).
 
-The wizard loops back to the menu after every run (Enter, or `m`/`r` when a
+A successful dry run counts as staged, so `[m]`/`[r]` and the restart question
-restart is needed) until `q`; scripted input that runs out ends it like `q`.
+on `q` show up too; in dry-run mode "restart" only prints.
+
+## Steamify shortcut
+
+Test a double-click with `systemd-run --user kioclient exec
+~/Desktop/cachyos-gamescope-boot-wizard.desktop`. If Plasma opens the file in
+Kate instead, it saw the file before it was executable. After the wizard the
+window counts down 10 seconds and closes; after an error (e.g. 404) it waits
+for Enter.
 
 ## Visual checks
 
-`scripts/vmshot.sh <out.png>` does the below. Starting `spectacle` straight
+`scripts/vmshot.sh [--clean] <out.png>` does the below. After a reboot, Steam's
+sign-in window and CachyOS Hello cover the desktop: `--clean` shuts Steam down
+(closing only `steamwebhelper` leaves a black window) and closes Hello and the
+wizard's Konsole. Steam comes back at the next login. Starting `spectacle` straight
 from SSH core-dumps; it has to run as a user unit (`systemd-run --user --wait`).
 
 ```bash
@@ -258,17 +302,22 @@ them with `systemd-run --user <app>`.
 ## Pitfalls
 
 - Broken mirror: `mirror5.krfoss.org` served a bad `.sig` ("Maximum file size
-  exceeded"), failing the conversion's package install. Comment it out:
+  exceeded"), failing the conversion's package install. `vmreset.sh` comments
-  `sudo sed -i '/krfoss/s/^Server/#Server/' /etc/pacman.d/*mirrorlist*`.
+  it out; by hand: `sudo sed -i '/krfoss/s/^Server/#Server/' /etc/pacman.d/*mirrorlist*`.
+- The snapshot has no shellcheck; `vmreset.sh` installs it. Check the bundle
+  like CI: `.github/tools/bundle.sh` on the host, then in the guest
+  `cd /mnt && shellcheck -S warning -e SC2034,SC2154 dist/steamify.sh`.
+- The host shell is zsh: `$var` holding several file names isn't split
+  (`sed -i ... $files` gets one "name"); use `xargs`.
 - Windows open in the snapshot (System Settings, CachyOS Hello) show stale
   data (e.g. a theme list from before `cachyos-vapor`) and cover screenshots;
   `vmreset.sh` closes them.
 
 - The guest's `/tmp` is cleared on reboot; keep baselines elsewhere.
 - The fake Fremont DMI makes leds-valve load 17 LED nodes, but there is no real hardware.
-- shellcheck: `sudo pacman -S shellcheck`, then in `/mnt`:
+- Per-file shellcheck (`shellcheck -S warning -x steamify.sh lib/*.sh` in
-  `shellcheck -S warning -x steamify.sh lib/*.sh`
+  `/mnt`) shows SC2154/SC2034 cross-file false positives; the bundle check
-  (SC2154/SC2034 cross-file warnings are false positives).
+  above is the one CI runs.
 - This repo's `.gitignore` is an allowlist: it ignores everything and
   un-ignores only the tracked scripts/docs. Add any new tracked file to it
   explicitly, or git will silently ignore it.

CHANGELOG.md

@@ -34,8 +34,16 @@ Watchable test runs and the lessons from testing cachyos-gamescope-boot 0.7.0
   - README and skill point to `github.com/theupriser/steamify-cachyos`; the
     local clone's default path (`REPO`) and the guest's state directory keep
     their old names.
-- **chore: The wizard's script is now steamify.sh**
+- `8c48858` **chore: The wizard's script is now steamify.sh**
   - `vmrun.sh`, `vmwatch.sh`, the skill and the README run `/mnt/steamify.sh`.
+- **feat: Release testing, cleaner resets and screenshots; skill updates**
+  - `vmwatch.sh --release` runs the newest GitHub release in the VM.
+  - `vmreset.sh` skips the broken krfoss mirror and installs shellcheck.
+  - `vmshot.sh --clean` closes Steam, CachyOS Hello and Konsole first.
+  - Skill: menu items 1-7 and the new menu loop/restart question, current
+    scripted inputs, always finishing on a fresh snapshot (the DKMS bug only
+    showed there), testing releases and their assets, the Steamify shortcut,
+    and the zsh word-splitting pitfall.
 
 ## 0.1.1 - 2026-09-23
 

README.md

@@ -108,9 +108,12 @@ read-write as 9p tag `repo`; in the guest:
 ## Helper scripts
 
 - `scripts/vmreset.sh [--fremont]`: restore `ssh-ready`, boot, mount the repo, autologin into Plasma
+  (and skip the broken krfoss mirror, install shellcheck)
 - `scripts/vmrun.sh '<menu input>'`: run the wizard in the guest's Plasma session with scripted input
-- `scripts/vmwatch.sh '<menu input>' [label]`: same, but in a visible Konsole window in the VM
+- `scripts/vmwatch.sh [--release] '<menu input>' [label]`: same, but in a visible Konsole window
-- `scripts/vmshot.sh <out.png>`: screenshot the guest's desktop
+  in the VM; `--release` runs the newest GitHub release instead of the mounted repo
+- `scripts/vmshot.sh [--clean] <out.png>`: screenshot the guest's desktop (`--clean` closes
+  Steam, CachyOS Hello and Konsole first)
 - `scripts/vmstate.sh`: print the state of every wizard component
 - `scripts/cmp.sh [save]`: save / diff the guest's KDE configs against a baseline
 

scripts/vmreset.sh

@@ -1,7 +1,8 @@
 #!/bin/bash
 # Reset the test VM to a snapshot and bring it up logged in to Plasma:
 # power off, restore the snapshot (disk + vars.fd), start it, mount the repo
-# on /mnt, set up the test autologin and wait for plasmashell.
+# on /mnt, set up the test autologin and wait for plasmashell; also skips
+# the broken krfoss mirror and installs shellcheck.
 #   scripts/vmreset.sh [run.sh flags...]      e.g. scripts/vmreset.sh --fremont
 # Env: VM_USER / VM_PORT / VM_HOST, SNAPSHOT (ssh-ready),
 #      VM_DIR (where disk.qcow2 lives: this repo if it has one, else ~/vms/cachyos-test),
@@ -41,5 +42,10 @@ for _ in $(seq 40); do pgrep -u "$USER" -x plasmashell >/dev/null && break; slee
 sleep 10
 # Windows the snapshot opens at login would cover the screenshots.
 pkill -u "$USER" systemsettings; pkill -u "$USER" cachyos-hello
+# mirror5.krfoss.org served a broken .sig ("Maximum file size exceeded"),
+# which fails the conversion's package install; skip it.
+for f in /etc/pacman.d/*mirrorlist*; do sudo sed -i '/krfoss/s/^Server/#Server/' "$f"; done
+# shellcheck, for checking the bundle like CI does (not in the snapshot).
+sudo pacman -S --needed --noconfirm shellcheck >/dev/null 2>&1 || echo "Couldn't install shellcheck." >&2
 pgrep -u "$USER" -x plasmashell >/dev/null && echo "Logged in to Plasma." || { echo "Plasma did not start." >&2; exit 1; }
 REMOTE

scripts/vmshot.sh

@@ -1,15 +1,26 @@
 #!/bin/bash
 # Screenshot the guest's Plasma session to a file on the host.
-#   scripts/vmshot.sh <out.png>
+#   scripts/vmshot.sh [--clean] <out.png>
+#   --clean  first close what starts with the session and covers the desktop
+#            (Steam, CachyOS Hello) and the wizard's Konsole.
 # spectacle started straight from SSH crashes; run it as a user unit so it
 # gets the session's environment.
 # Env: VM_USER (theupriser), VM_PORT (2222), VM_HOST (localhost), GUEST_UID (1000).
 set -euo pipefail
 . "$(dirname "$0")/common.sh"
-out="${1:?usage: $0 <out.png>}"
+clean=""
-{ printf 'uid=%q\n' "${GUEST_UID:-1000}"; cat << 'REMOTE'
+[[ "${1:-}" == --clean ]] && { clean=1; shift; }
+out="${1:?usage: $0 [--clean] <out.png>}"
+{ printf 'uid=%q clean=%q\n' "${GUEST_UID:-1000}" "$clean"; cat << 'REMOTE'
 export XDG_RUNTIME_DIR=/run/user/$uid DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$uid/bus
 rm -f /tmp/vmshot.png
+if [ -n "$clean" ]; then
+    # Steam as a whole: closing only its web helper leaves a black window.
+    # It comes back at the next login (steam-desktop-autostart).
+    steam -shutdown >/dev/null 2>&1 & sleep 5; pkill -u "$USER" -x steam; pkill -u "$USER" -x steamwebhelper
+    pkill -u "$USER" cachyos-hello; pkill -u "$USER" -x konsole
+    sleep 2
+fi
 sleep 2
 systemd-run --user --wait -q spectacle -b -n -f -o /tmp/vmshot.png
 REMOTE

scripts/vmwatch.sh

@@ -2,24 +2,37 @@
 # Like vmrun.sh, but run the wizard in a visible Konsole window inside the
 # guest's Plasma session, so someone at the QEMU window can follow along.
 # Waits for the wizard to finish, then prints its log. The window stays open.
-#   scripts/vmwatch.sh '<menu input>' ["label shown in the window"]
+#   scripts/vmwatch.sh [--release] '<menu input>' ["label shown in the window"]
+#   --release  run the newest release from GitHub instead of the mounted repo
+#              (downloaded; WIZARD_KEEP_STDIN=1 keeps the piped menu input).
 # Env: VM_USER (theupriser), VM_PORT (2222), VM_HOST (localhost),
 #      GUEST_REPO (/mnt), GUEST_UID (1000), WAIT (seconds, default 1800).
 set -euo pipefail
 . "$(dirname "$0")/common.sh"
-input="${1:?usage: $0 '<menu input>' [label]}"
+release=""
+[[ "${1:-}" == --release ]] && { release=1; shift; }
+input="${1:?usage: $0 [--release] '<menu input>' [label]}"
 label="${2:-Running the wizard}"
 # The guest login shell is fish, so pass values in through the bash script itself.
-{ printf 'input=%q label=%q repo=%q uid=%q wait=%q\n' "$input" "$label" "${GUEST_REPO:-/mnt}" \
+{ printf 'input=%q label=%q repo=%q uid=%q wait=%q release=%q\n' "$input" "$label" "${GUEST_REPO:-/mnt}" \
-    "${GUEST_UID:-1000}" "${WAIT:-1800}"; cat << 'REMOTE'
+    "${GUEST_UID:-1000}" "${WAIT:-1800}" "$release"; cat << 'REMOTE'
 export XDG_RUNTIME_DIR=/run/user/$uid DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$uid/bus
-[ -x "$repo/steamify.sh" ] || { echo "$repo/steamify.sh missing: mount the repo (lost after a reboot)" >&2; exit 1; }
+if [ -n "$release" ]; then
+    wizard=/tmp/steamify-release.sh
+    curl -fsSL https://github.com/theupriser/steamify-cachyos/releases/latest/download/steamify.sh -o "$wizard" ||
+        { echo "Couldn't download the newest release." >&2; exit 1; }
+    run="WIZARD_KEEP_STDIN=1 bash $wizard"
+    label="$label ($(grep -m1 '^VERSION=' "$wizard") from GitHub)"
+else
+    [ -x "$repo/steamify.sh" ] || { echo "$repo/steamify.sh missing: mount the repo (lost after a reboot)" >&2; exit 1; }
+    run="$repo/steamify.sh"
+fi
 rm -f /tmp/wizard.done
 {
     echo '#!/bin/bash'
     printf 'echo %q; echo %q; sleep 3\n' ">>> $label" ">>> menu input: $input"
     # shellcheck disable=SC2016
-    printf 'printf %q | %q 2>&1 | tee /tmp/wizard.log\n' "$input" "$repo/steamify.sh"
+    printf 'printf %q | %s 2>&1 | tee /tmp/wizard.log\n' "$input" "$run"
     echo 'touch /tmp/wizard.done'
 } > /tmp/vmwatch-run.sh
 chmod +x /tmp/vmwatch-run.sh