docs: NVIDIA-RESEARCH.md and TODO: hook VM results, opt-out toggle plan, older cards

TODO-nvidia.md

@@ -1,6 +1,6 @@
 # TODO: NVIDIA fix for gaming mode (branch `feature/nvidia-gaming-fix`)
 
-Delete this file together with `.no-release-yet` when the feature is released.
+Delete this file, `NVIDIA-RESEARCH.md` and `.no-release-yet` when the feature is released.
 Written 2026-10-01 so a new session can pick this up.
 
 ## Problem
@@ -28,12 +28,43 @@ missing, or a gamescope/driver mismatch.
   Limine pasted an appended `+=` line as text into the cmdline; a kernel without the
   NVIDIA modules made limine-mkinitcpio skip its boot entry.
 
-## In progress (2026-10-01)
-- Kernel changes: the early-load drop-in is now kept right by a pacman hook
-  (`patches/steamify-nvidia-initramfs.{sh,hook}`, installed by `nvidia_enable`). Unit-tested
-  (29 checks). **Not yet VM-tested with a real pacman transaction**: hook order (85- after
-  71-dkms-install, before the mkinitcpio/limine hooks: check the real hook names in
-  /usr/share/libalpm/hooks), a kernel reinstall with and without modules.
+## Kernel changes (done, VM-tested 2026-10-01, Limine)
+The early-load drop-in is kept right by a pacman hook (`patches/steamify-nvidia-initramfs.{sh,hook}`,
+installed by `nvidia_enable`, `/etc/pacman.d/hooks/85-steamify-nvidia-initramfs.hook`). Real pacman
+transactions in a Limine VM: the hook runs between "Updating module dependencies" and "Updating
+linux initcpios" (real hook names there: 60-*-remove, 80-limine-efi-deploy, 90-limine-mkinitcpio-remove-post,
+90-mkinitcpio-install; DKMS would be 71-): the drop-in is present while every kernel has the modules, removed
+when the LTS kernel loses them, back when they return; initramfs nvidia files 1 -> 5 -> 1 -> 5 -> 1
+(1 = baseline, 4 modules added); no ERROR/skipping in any rebuild; cmdline kept the parameters after a reboot;
+disable removes hook, script and drop-in. Found on the way: an empty hook/script was installed when
+`patch_file` failed (now an error). Only tested with fake modules (renamed copies of a small module), on
+Limine; systemd-boot and GRUB use the same hook but were not run with pacman transactions.
+
+## Opt-out toggle (new request, 2026-10-01: not built yet)
+When a compatible NVIDIA card is listed there should be a menu option, on by default (opt-out), named
+"NVIDIA compatibility", as a sub-option of the SteamOS conversion, directly under "Boot into" (`boot`).
+Today the fix runs unconditionally inside `gaming_enable`/`gaming_disable`.
+- [ ] New component `nvidia` in `lib/menu.sh`: `COMPONENTS` right after `boot`, `PARENT[nvidia]=gaming`, `LABEL`,
+      `FEATURE_VERSION[nvidia]`, `component_available` -> `nvidia_available` (= `nvidia_present`); not in
+      `NO_PRESELECT` (ticked by default, `feature_new` ticks it for installs that already have the conversion).
+      `nvidia_status` from the system (hook + parameters present), `nvidia_enable`/`nvidia_disable` = the code now
+      called from `gaming_enable`/`gaming_disable` (remove those calls). Check `toggle_component` dependencies,
+      `feature_record_unticked`, the plan texts ("This will: ...").
+- [ ] The app: `ui/qml/Texts.qml` item texts, `AppState.qml`, the screen rows, `lib/backend.sh` if it lists ids;
+      `--defaults [--options <ids>]` (the Steam Machine ISO's installer pages: it names the ids) and `--skip`.
+- [ ] README rows/screenshot rule (a release that adds a menu row retakes `assets/screenshot-menu.png`), TECHNICAL.md,
+      CHANGELOG, `tests/nvidia-test.sh` (status/enable/disable through the component), VM menu test in
+      steamify-cachyos-dev (`share/vmtest/menu`, TESTPLAN.md row).
+- [ ] What "compatible" means: see the research below. The parameters themselves apply to any card whose driver
+      provides `nvidia_drm` (what `nvidia_present` tests); whether gamescope works on a card is a separate question.
+
+## Older cards and other research
+The user hopes the fix also works for GPUs older than RTX 2000. Full notes with sources: **`NVIDIA-RESEARCH.md`**.
+Short version: open kernel modules need Turing+, Maxwell/Pascal/Volta need the proprietary driver (580 legacy branch);
+`nvidia-drm.modeset/fbdev` exist in both, so the fix applies to any card with `nvidia_drm`, but nothing found says gamescope
+works better or worse there (a GTX 1050 Ti has a known gamescope>3.16.16 start problem on HDMI, not ours). Cannot be promised:
+needs a test on a real older card. Design for the toggle: on by default for any card with `nvidia_drm`, the label says
+what it does, `tests/nvidia-hardware-test.sh` reports GPU and driver so results can be compared.
 
 ## Still to do
 1. [ ] **On the NVIDIA PC** (only place the real fix can be judged), from this checkout:
@@ -45,10 +76,11 @@ missing, or a gamescope/driver mismatch.
    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.
+3. [ ] Not covered by any test: the early-load drop-in with the REAL NVIDIA modules (the VMs only have renamed
+   fake ones), and systemd-boot/GRUB with a pacman transaction (only Limine was run).
 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
+5. [ ] Build the opt-out toggle (section above) before release.
+6. [ ] 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`.