steamify-cachyos-live-iso/TODO.md

To do (Steam Machine edition)

Open

1. Steamify installer page (2026-09-28, working end to end). packagechooserq (custom QML) doesn't exist in CachyOS's own cachyos-calamares-next build (-DSKIP_MODULES=...packagechooserq...), so it's built out of tree against the installed Calamares headers (see the build VM notes in the steam-machine-iso skill) and its .so + module.desc are baked straight into archiso/airootfs/usr/lib/calamares/ modules/packagechooserq/ (no conflict: the package never ships that path). netinstall (checkbox tree) stays as a manually-swappable fallback (steamify-cachyos-dev/share/sn.sh + nisteamify.conf) for when the module can't load, but isn't wired into calamares-online.sh automatically yet — see the version-mismatch item below.

   • Fixed this session: selected-row contrast (border-only highlight, was a translucent teal fill making white text unreadable), page background (was falling through to Calamares' white default), a sub-option └ marker, more right padding so the row border clears the scrollbar, Summary step showing readable labels (packagechooserq's prettyStatus() overridden, only for this module instance, to render an HTML bullet list from a new items.json that calamares-online.sh writes next to Items.qml), and a pre-existing bug: steamify.sh on the ISO was never executable (curl -o in steamify-prepare.sh doesn't set +x, and profiledef.sh's file_permissions never listed it), so calamares-online.sh's direct exec of it ("$sbin" --defaults --list) silently failed and items.json (no static fallback) was never written — fixed by adding the path to file_permissions.
   • Still open:
     • Bake the packagechooserq build into the ISO build pipeline itself (a build-calamares-modules.sh step: install cachyos-calamares-next, build out of tree, install into airootfs) instead of committing a prebuilt .so, so it always matches whatever Calamares version is current at build time.
     • Version-mismatch fallback: after calamares-online.sh's pacman -Sy cachyos-calamares-next, check the installed version against what the module was built for; on a mismatch, switch settings.conf to the netinstall page instead (generate its groups conf from --defaults --list there too) rather than risk an "Initialization Failed" module.
     • "Boot into gaming mode" as an opt-out sub-toggle under SteamOS conversion (agreed with the user) isn't implemented on either page yet — both still use the old Gaming/Desktop radio-row.
     • A Python job (e.g. steamifychoice, before packages@online) to normalize either page's choice (packagechooserq's packagechooser_steamifypage GS key, or netinstall's packageOperations markers) into one steamifyChoice GS key, so shellprocess_steamify.conf doesn't need to know which page ran.
   • Lessons learned:
     • Verify a Calamares module is actually installed (ls /usr/lib/calamares/modules) before writing QML/config for it; packagechooser's multi-select needs Shift/Ctrl-click (plain click replaces the selection) — not usable as-is, packagechooserq or netinstall only.
     • Both pages are testable live in the booted ISO VM with no rebuild: hot-swap /etc/calamares/modules/*.conf + settings.conf (share/sq.sh / share/sn.sh), relaunch pkexec-wrapper calamares -D6 in a separate Konsole tab (it blocks the tab it runs in). A C++ module change needs a real rebuild (out-of-tree, in the build VM) + redeploy of the .so, no shortcut.
     • The live session's keyboard layout keeps drifting to Dutch (e.g. after Calamares' Welcome page, or after opening System Settings), breaking //(/)/&/> in qmptype.py's US-layout map with no error for the common ones (/ → -) — setxkbmap us typed via QMP does fix it (unlike the earlier Wayland claim), but check with a no-symbols probe after any language/keyboard step regardless.
     • qmptype.py has no key for & or > at all: a typed command using either raises "no key for" and can leave an unterminated quote in the shell's input buffer; send Ctrl+C before retyping. Avoid redirection/&& in typed commands — write it to a file and run bash /media/foo.sh instead, since a file's contents aren't typed character-by-character.
     • Send QMP keystrokes one command at a time with a beat in between; firing several qmptype.py calls back-to-back can interleave with the guest's own prompt redraw and garble the input.
     • Don't screenshot-poll for VM readiness: pass VM_SERIAL=<file> to run.sh/vmisoboot.sh and grep the plain-text serial log instead (near-zero tokens vs. repeated screenshot+image-analysis).
     • The build VM's guest sshd applies OpenSSH's PerSourcePenalties: repeated quick reconnect attempts within its window make ssh/scp fail instantly with "Connection closed" (verbose: "Not allowed at this time"), and each further attempt seems to extend the penalty rather than reset it. Don't retry-loop through it; back off for a while, or just restart the VM (clears its in-memory penalty state immediately) instead of waiting it out.

2. Check the live name (the build tree has it right: build/x86_64/airootfs/etc/os-release) after the next build: Hello's subtitle should say "Steamify CachyOS, based on CachyOS rolling" (steamify-customize.sh, run by mkarchiso after the packages; the airootfs copy of os-release is overwritten by a package).

3. Steamify PR for feat/defaults-options (2.7.0, c4ec755: --options, --boot; also steamify.sh --boot on its own and the HDMI-CEC volume fix): pushed and regression-tested in the VM (--fremont), no PR yet; the user merges (never commit to main). 2.6.0 is released. Until 2.7.0 is, build the ISO with steamify-prepare.sh ~/projects/steamify-cachyos (the branch).

4. Build in the test VM instead of on the Steam Machine (steam-machine-iso skill), and install the result unattended with scripts/vminstall.sh --iso (vm-install skill; the Calamares Steamify step then needs steamify-install run from the live script).

5. Test on the real Steam Machine from a USB stick (gamescope, LEDs, CEC, power-off) before calling the ISO usable.

Done

• Steamify 2.6.0 released (--defaults, install-time mode).
• Live session (VM, --fremont): Vapor look and layout (Steam Deck wallpaper) at the live login; the power-off module is built for both ISO kernels and loaded at boot, in the VM it returns "No such device" (no AMDI0030 GPIO controller), as designed. Whether it keeps the real Steam Machine off is part of the hardware test.
• Regression test 2.6.0 on an existing desktop install (test VM from ssh-ready, --fremont): full first run, re-apply, notifications/CEC/theme off and on again. No errors; user units enabled and running, theme applied and restored live, no first-login autostart with a session.
• ISO name: steamify-cachyos-<date>-x86_64.iso (iso_name in archiso/profiledef.sh); the volume label stays COS_<yyyymm>.
• VM install from the ISO (2026-09-27, f42859a): a VM install from the ISO (Hello's Install, no manual fixes) ran Steamify's step: every component OK, exit: 0, SDDM autologin into gamescope. First desktop login (session switched to plasma in the VM) passed too: Vapor layout, the app opened with everything on. The first-login script runs the newest release, so it only works once 2.6.0 is released (in the test it was pointed at the bundle). The VM's text console doesn't show (virgl): read the installed disk with qemu-nbd -r + mount -o ro,rescue=nologreplay,subvol=@ (logs in @log).

Later

• Branding: the live session's os-release says "Steamify, based on CachyOS" (Hello's subtitle); Hello's window title and the boot menu still say CachyOS. Check with the CachyOS team.
• Release: a CI job that builds the ISO (privileged container, flags from the steam-machine-iso skill) and hosts it (>2 GB, not a GitHub release asset).
• Drop the Boost 1.91 workaround in steamify-prepare.sh once cachyos-calamares-next is rebuilt against the repos' Boost.

Build and test details: the steam-machine-iso skill in steamify-cachyos-dev.