steamify-cachyos-live-iso/AGENTS.md

AGENTS.md

Guidance for AI coding agents working on this repository (the Steam Machine live ISO: CachyOS + the Steamify installer step). See README.md and TODO.md for what's built and what's left; this file is operational knowledge — how to test/build/debug it without rediscovering the same things every session. TODO.md should stay a plain task list; lessons and gotchas belong here instead.

Full build/test workflow (VM scripts, snapshots, cache setup) lives in the steam-machine-iso and cachyos-vm-testing skills in steamify-cachyos-dev — load those first. This file is the overflow: things worth knowing that don't fit a skill's step-by-step flow.

Calamares modules

• Verify a module is actually installed (ls /usr/lib/calamares/modules) before writing QML/config for it. A .conf file existing is not proof — CachyOS's own cachyos-calamares-next build explicitly skips packagechooserq (-DSKIP_MODULES=...).
• Read a module's actual logged global-storage writes (Calamares debug log, -D6), not its UI label text, to know what a mode/method really does.
• packagechooser's multi-select only works with Shift/Ctrl-click (a plain click replaces the selection) and its UI has no visible checkboxes — not usable as the Steamify page. Use packagechooserq (custom QML, qtplugin/legacy) or netinstall (checkbox tree) instead.
• packagechooserq is built out of tree against the installed Calamares CMake config (/usr/lib/cmake/Calamares) with -DWITH_QML=ON -DQT_VERSION_SUFFIX=-qt6 -Dqtname=Qt6 -DWITH_QT6=ON; find_package(KF6CoreAddons) must come before find_package(Calamares) or the build fails with "KF6::CoreAddons target not found". Its Config class (and prettyStatus()'s raw Install option: <ids> text) is shared with the plain packagechooser module — override prettyStatus() in PackageChooserQmlViewStep.cpp itself (not Config.cpp) to change only this module's Summary display without affecting packagechooser@desktop etc. elsewhere in the installer.
• Both packagechooserq (QML swap) and netinstall (config swap) are testable live in a booted ISO VM with no rebuild: edit /etc/calamares/modules/*.conf + settings.conf (steamify-cachyos-dev/share/sq.sh / sn.sh), relaunch pkexec-wrapper calamares -D6 in a separate Konsole tab (it blocks the tab it runs in; typing into that same tab just echoes inertly into its blocked stdin). A C++ module change needs an actual rebuild (out-of-tree, in the build VM) and redeploying the .so — no shortcut.

ISO permissions

steamify-prepare.sh fetches steamify.sh with curl -o, which doesn't carry the executable bit, and archiso/profiledef.sh's file_permissions map is the only other place permissions get fixed up on the ISO — any path not listed there stays at whatever curl/cp gave it. calamares-online.sh execs steamify.sh directly (not via bash) to regenerate Items.qml/ items.json at boot; without +x that failed silently (its stderr is redirected to /dev/null), so the page kept working off build-time fallbacks with no visible error. When something the ISO downloads or copies at build time needs to run directly (not bash script.sh), add it to file_permissions — don't assume the source already had the right mode.

Driving a live/installer session via QMP

• Don't screenshot-poll for VM readiness. Pass VM_SERIAL=<file> to run.sh/vmisoboot.sh (logs console=ttyS0 to a plain text file) and grep that instead — near-zero tokens vs. repeated screenshot + image analysis. Only screenshot at real decision points (to show the user, or to check a layout), not as a polling mechanism.
• The live session's keyboard layout keeps drifting to Dutch (e.g. after Calamares' Welcome page's keyboard preview, or after opening System Settings), which silently breaks qmptype.py's US-layout character map (/ → -, &/> fail outright) with no error for the common substitutions. Check with a no-symbols probe (echo test123) after any language/keyboard step. Typing setxkbmap us via QMP does fix it.
• qmptype.py has no key mapping 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 (symptom: the prompt shows a bare > continuation). Send Ctrl+C before retyping. Avoid redirection/&& in typed commands entirely — write the commands to a file on the shared vmtools/share mount and run bash /media/foo.sh instead, since a file's contents aren't typed character-by-character and have no such limits.
• Send QMP keystrokes one command at a time with a beat (~1-2s) in between. Firing several qmptype.py calls back-to-back can interleave with the guest's own prompt redraw and garble the input (seen as commands merging or a stray leading character).
• Calamares page Next/Back buttons move vertically as page content grows/shrinks: re-screenshot and re-locate the button after every page change, don't reuse a fixed y-coordinate.
• A second pkexec-wrapper calamares -D6 while an earlier failed instance's window is still open just prints "Calamares is already running.": close that window first (Cancel/Afbreken, then confirm the "really cancel?" dialog).

Build VM SSH flakiness

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 further quick retries seem to extend the penalty rather than reset it. Don't retry-loop through it — that makes it worse. Either back off for a good while (minutes, not seconds) with zero attempts in between, or just restart the VM, which clears its in-memory penalty state immediately and is usually faster than waiting it out.

Large scp transfers (e.g. the ~3.2GB built ISO) over this same flaky link can report "Connection closed" while actually still having copied fully — check the destination file's size/timestamp before assuming a real failure, and retry the copy (it's idempotent) rather than the whole build.