feat: progress-report skill and scripts/vmprogress.sh (a status line per change); referenced from the other skills and AGENTS.md

.claude/skills/progress-report/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: progress-report
+description: Use whenever a long VM job runs for the user (vminstall.sh, vmbootloadertest.sh, vmsuite.sh, vmtest.sh, an ISO build), locally or on the WSL PC, and the user wants to follow it - how to report progress (a table with a bar per VM and a total, only when something changes), show the log in the user's terminal and the VM's screen on their desktop, and look into a job that seems stuck.
+---
+
+# Progress report for VM jobs
+
+What the user asked for (2026-09-29): see what is going on, without noise.
+
+## The rules
+
+- **Report only on a change**: an install stage, a test step, a job finishing, a FAIL. Never a
+  timed "no change" message. One monitor, not polling from the conversation.
+- **Every report is the same table**, one row per VM/job plus a total row:
+
+  | VM | Step | Checks | Progress |
+  |---|---|---|---|
+  | grub | ✅ done | 40 / 40, 0 failed | `████████████████████` 100% |
+  | systemd-boot | test: kernel update | 27 / 40, 0 failed | `█████████████░░░░░░░` 68% |
+  | limine | install: desktop environment (40%) | 0 / 41 | `░░░░░░░░░░░░░░░░░░░░` 0% |
+  | **Total** | | **67 / 121**, 0 failed | `███████████░░░░░░░░░` 55% |
+
+  Bar: 20 cells, `█` per 5% of checks passed out of the expected count. Step in plain words
+  ("install: base system (9%)", "test: reboot into the other kernel"), ✅ when done, ❌ with the
+  failed check's name when something fails. Under the table at most two lines: what is odd or next.
+- **A FAIL or a job that stops moving is reported at once**, with the cause looked up first (below),
+  not only the numbers.
+
+## The monitor
+
+`scripts/vmprogress.sh [job...]` (jobs: limine systemd-boot grub cli menu hw installer toggles)
+prints one line only when something changes and `ALLDONE` at the end; it reads the latest run in
+`~/vms/bl-<loader>.test.log` / `~/vms/run-<suite>.log` and the install percentage from
+`$VM_DIR/install-www/install.log`. Expected check counts live at its top: update them when a
+suite gains checks. `--once` prints the current state.
+
+On the WSL PC, from the laptop:
+
+```
+Monitor(command: "ssh wsl '~/projects/steamify-cachyos-dev/scripts/vmprogress.sh grub systemd-boot limine'",
+        description: "boot loader tests: only on change", timeout_ms: 1800000)
+```
+
+Re-arm it when it expires while jobs still run. Turn each event into the table above.
+
+## What the user sees on the PC
+
+- **Their terminal**: stream the running job's log into it (the `showlog` unit, `wsl-build-host`
+  skill); switch it when the job changes (install log, then the test log, then `~/vms/test.log`).
+- **The VM's screen**: automated runs are headless. To show one: `scripts/vmview.py ~/vms/<vm>` in
+  a unit with the WSLg env (a window refreshed every 2 s, view only). When the user wants to watch
+  or step in, restart the job with a real window (`--window`, WSLg env) instead.
+- One screenshot for yourself (`scripts/qmpshot.py <qmp.sock> out.png`, copied back and Read) only
+  to diagnose a stuck boot, not as a test.
+
+## A job that seems stuck
+
+1. `--once` and the log's last `#####` step: how long has it been there, compared with the others?
+2. Is the VM up: `pgrep -af '[q]emu'` (its `hostfwd` port), ssh to it with the test's own options
+   (`. scripts/common.sh` with its `VM_DIR`/`VM_PORT`): a known_hosts mismatch or "Permission
+   denied" is a test setup problem, not the guest.
+3. No ssh banner: take one screenshot. Firmware PXE/HTTP boot means no usable boot entry: read the
+   UEFI variables from a copy of `vars.fd` (`virt-fw-vars -i <copy> --print`, package
+   virt-firmware) and compare with a loader that works.