docs: TODO-nvidia.md: state and open work of the NVIDIA fix, for the next session

.no-release-yet

@@ -1,3 +1,4 @@
 This branch is not ready to be released: do not merge it into the release branch.
 When the feature is complete and tested, ask the user whether it may be released;
 on a yes, delete this file, then open the pull request into the release branch.
+Open work and how to pick it up: TODO-nvidia.md.

TODO-nvidia.md

@@ -0,0 +1,61 @@
+# TODO: NVIDIA fix for gaming mode (branch `feature/nvidia-gaming-fix`)
+
+Delete this file together with `.no-release-yet` when the feature is released.
+Written 2026-10-01 so a new session can pick this up.
+
+## Problem
+A PC with an NVIDIA RTX 5080 (Blackwell, open kernel modules) shows a corrupted
+image when gaming mode (gamescope) starts. Cause not confirmed. Steamify had no
+NVIDIA handling at all. Likely: `nvidia-drm.modeset=1` / `nvidia-drm.fbdev=1`
+missing, or a gamescope/driver mismatch.
+
+## What is built (all on this branch, pushed)
+- `lib/nvidia.sh`: part of the SteamOS conversion (`gaming_enable` / `gaming_disable`).
+  With an NVIDIA GPU + driver it adds `nvidia-drm.modeset=1 nvidia-drm.fbdev=1` to the
+  kernel command line (Limine, systemd-boot, GRUB; backup first) and, only when every
+  installed kernel has `nvidia_drm`, `/etc/mkinitcpio.conf.d/90-steamify-nvidia.conf`.
+  Rebuilds initramfs + boot entries, verifies the config and the generated entries
+  have the parameters (error otherwise). Undone on disable. Description: `TECHNICAL.md`.
+- `FEATURE_VERSION[gaming]=2.9.7` so installs that already have the conversion re-apply it.
+- Test hooks `NVIDIA_DRM_DIR`, `NVIDIA_MODULES_DIR`, `NVIDIA_LIMINE_CONF`,
+  `NVIDIA_SDBOOT_DIR`, `NVIDIA_GRUB_CFG`: only set by tests; defaults are the real paths.
+
+## Tested
+- `bash tests/nvidia-test.sh`: 22 checks against a fake RTX 5080 beside an iGPU, a stub
+  `modinfo`, temp boot loader files. All pass.
+- Real VMs (QEMU/KVM, Limine, systemd-boot, GRUB): enable, reboot, kernel command line
+  has the parameters; disable, reboot, original command line. All pass. Found and fixed:
+  Limine pasted an appended `+=` line as text into the cmdline; a kernel without the
+  NVIDIA modules made limine-mkinitcpio skip its boot entry.
+
+## Still to do
+1. [ ] **On the NVIDIA PC** (only place the real fix can be judged), from this checkout:
+   `bash tests/nvidia-hardware-test.sh check` (before), `... apply` (asks sudo), reboot,
+   `... check` (after: `nvidia_drm modeset/fbdev = Y`), boot gaming mode, then
+   `... visual` (was the picture clean?). Everything goes to `~/steamify-nvidia-report.txt`:
+   paste it into the session.
+2. [ ] If the parameters apply but the picture is still corrupted: look at the report's
+   gamescope/NVIDIA log lines and the versions (`nvidia-open`, `nvidia-utils`, `gamescope`,
+   `gamescope-session-cachyos`); the cause is then probably a gamescope/driver mismatch
+   for Blackwell, not this fix.
+3. [ ] Not covered by any test: the early-load drop-in on a machine that has the modules
+   (the VMs have none), and a boot loader other than the three.
+4. [ ] Changelog: fill in the commit hashes of this feature's lines (next commit, per AGENTS.md).
+5. [ ] When complete and tested: ask the user whether it may be released. On a yes delete
+   `.no-release-yet` and this file, open the PR into `release/2.9.7` (local branch only so
+   far, one commit `chore: Version 2.9.7`; push it then) and merge it. The user merges
+   `release/2.9.7` into `main`.
+
+## Working rules for this repo (see AGENTS.md and ../steamify-cachyos-dev/AGENTS.md)
+- Never work on `main` or a `release/*` branch; no `Co-Authored-By` / "Generated with
+  Claude" lines in commits or PRs. No git identity on the dev laptop: use
+  `git -c user.name="Rick Peters" -c user.email="rickpeters@upriser.nl" commit`.
+- Don't push `release/2.9.7` before the PR (a push can start a dev ISO build).
+
+## If the VM tests need repeating (dev laptop, Ubuntu)
+- `scripts/vminstall.sh` (steamify-cachyos-dev) with `VM_BOOTLOADER=limine|systemd-boot|grub`,
+  `CI=1`, a short `VM_DIR` (`~/vms/...`: socket paths over 108 bytes fail) and `VM_SSH_KEY`.
+- This session's shell lacked the `kvm` group: run QEMU steps as `sg kvm -c "..."`.
+- `/tmp/vminstall-iso.lock` belongs to another user and there is no `bsdtar`: use a copy of
+  `vminstall.sh` with another lock path and a `bsdtar` shim (Python `pycdlib` in a venv).
+- Delete everything afterwards (`~/vms` incl. `pkg-cache`, the 3 GB ISO, keys).