docs: AGENTS.md: never work on main or a release branch, hardware-specific fixes, git identity

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

.github/workflows/bundle.yml

@@ -40,12 +40,39 @@ jobs:
       - name: Check
         run: |
           bash -n dist/steamify.sh
-          # SC2034/SC2154: variables used across the inlined modules.
-          shellcheck -S warning -e SC2034,SC2154 dist/steamify.sh
-          shellcheck -S warning dist/steamify-app.sh
           python3 -m py_compile ui/steamify-ui
 
+      # shellcheck through an action that brings its own binary: GitHub's runner has it installed,
+      # Gitea's act_runner image doesn't. One file per run, as before (the exceptions are the bundle's).
+      - name: shellcheck the bundle
+        uses: ludeeus/action-shellcheck@2.0.0
+        env:
+          # SC2034/SC2154: variables used across the inlined modules.
+          SHELLCHECK_OPTS: -e SC2034 -e SC2154
+        with:
+          severity: warning
+          scandir: dist
+          ignore_names: steamify-app.sh
+      - name: shellcheck the app launcher
+        uses: ludeeus/action-shellcheck@2.0.0
+        with:
+          severity: warning
+          scandir: dist
+          ignore_names: steamify.sh
+
+      # The build as an artifact on GitHub and on the mirror (Gitea); releases stay GitHub's.
+      # Gitea's artifact server doesn't speak upload-artifact@v4's protocol, and GitHub fails a workflow
+      # that merely mentions the deprecated @v3: Gitea gets christopherhx's fork of v4 for Gitea.
       - uses: actions/upload-artifact@v4
+        if: github.server_url == 'https://github.com'
+        with:
+          name: steamify
+          path: |
+            dist/steamify.sh
+            dist/steamify-app.tar.gz
+            dist/steamify-app.sh
+      - uses: christopherhx/gitea-upload-artifact@v4
+        if: github.server_url != 'https://github.com'
         with:
           name: steamify
           path: |
@@ -55,6 +82,7 @@ jobs:
 
       - name: Version
         id: version
+        if: github.server_url == 'https://github.com'
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
@@ -69,6 +97,7 @@ jobs:
 
       - name: Publish the v${{ steps.version.outputs.version }} release
         if: >-
+          github.server_url == 'https://github.com' &&
           github.event_name != 'pull_request' && github.ref == 'refs/heads/main' &&
           steps.version.outputs.released == 'false'
         env:
@@ -104,3 +133,85 @@ jobs:
             gh release create latest --title "Steamify CachyOS - latest (v$VERSION)" --notes "$latest_notes" --latest=false
           fi
           gh release upload latest dist/steamify.sh dist/steamify-app.sh dist/steamify-app.tar.gz assets/steam-gaming-settings.svg --clobber
+
+      # The mirror (Gitea) publishes its own release per version too, the same way: never overwrites one,
+      # notes from the changelog. gh can't talk to Gitea: its API for the check, a Gitea release action to
+      # publish. The token is the run's own (repository write); a secret RELEASE_TOKEN overrides it.
+      - name: Version (mirror)
+        id: mirror_version
+        if: github.server_url != 'https://github.com'
+        env:
+          TOKEN: ${{ secrets.RELEASE_TOKEN || github.token }}
+        run: |
+          version="$(grep -oP '^VERSION=\K.*' steamify.sh)"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          if curl -fsS -o /dev/null -H "Authorization: token $TOKEN" \
+              "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/tags/v$version"; then
+            echo "released=true" >> "$GITHUB_OUTPUT"
+            echo "::warning::v$version is already released on this server and won't be overwritten."
+          else
+            echo "released=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Release notes (mirror)
+        if: >-
+          github.server_url != 'https://github.com' &&
+          github.event_name != 'pull_request' && github.ref == 'refs/heads/main' &&
+          steps.mirror_version.outputs.released == 'false'
+        env:
+          VERSION: ${{ steps.mirror_version.outputs.version }}
+        run: |
+          changes="$(awk -v v="$VERSION" '
+              $0 ~ "^## " { if (found) exit; if (index($0, "## " v " ") == 1) { found = 1; next } }
+              found' CHANGELOG.md)"
+          cat > dist/release-notes.md <<NOTES
+          Single-file build of v$VERSION ($(git describe --always), $(git log -1 --format=%cs)).
+          Run this version with:
+
+              curl -fsSL ${{ github.server_url }}/${{ github.repository }}/releases/download/v$VERSION/steamify.sh | bash
+
+          ## Changes in v$VERSION
+          $changes
+          NOTES
+
+      - name: Publish the v${{ steps.mirror_version.outputs.version }} release (mirror)
+        if: >-
+          github.server_url != 'https://github.com' &&
+          github.event_name != 'pull_request' && github.ref == 'refs/heads/main' &&
+          steps.mirror_version.outputs.released == 'false'
+        uses: akkuman/gitea-release-action@v1.3.7
+        with:
+          token: ${{ secrets.RELEASE_TOKEN || github.token }}
+          tag_name: v${{ steps.mirror_version.outputs.version }}
+          target_commitish: ${{ github.sha }}
+          name: Steamify CachyOS v${{ steps.mirror_version.outputs.version }}
+          body_path: dist/release-notes.md
+          files: |
+            dist/steamify.sh
+            dist/steamify-app.sh
+            dist/steamify-app.tar.gz
+            assets/steam-gaming-settings.svg
+
+      # A new version starts the Steamify ISO's release of the ISO repo: its iso-1-github-tag.yml (always run from
+      # master) names the ISO after the newest Steamify release, tags it, and the Gitea mirror builds and attaches the ISO.
+      # The branch here decides the kind of build (the workflow's input `kind`):
+      #   main (publishes the release)            -> release: a real ISO (tag v<steamify>-<date>)
+      #   release/** (a version not yet released) -> dev: a pre-release (tag v<steamify>-dev.<date>)
+      # Needs a fine-grained token for that repo (Actions: read and write) as the secret ISO_DISPATCH_TOKEN;
+      # without it, this is skipped.
+      - name: Start the Steamify ISO's release
+        if: >-
+          github.server_url == 'https://github.com' &&
+          github.event_name != 'pull_request' &&
+          (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')) &&
+          steps.version.outputs.released == 'false'
+        env:
+          GH_TOKEN: ${{ secrets.ISO_DISPATCH_TOKEN }}
+        run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "::notice::No ISO_DISPATCH_TOKEN: the Steamify ISO isn't released with this version."; exit 0
+          fi
+          # A release branch builds the ISO with its own code (and VERSION): steamify_ref. main builds the release it just published.
+          if [ "$GITHUB_REF" = refs/heads/main ]; then kind=release; sref=""; else kind=dev; sref="$GITHUB_REF_NAME"; fi
+          gh workflow run iso-1-github-tag.yml -R theupriser/steamify-cachyos-live-iso --ref master -f kind="$kind" -f steamify_ref="$sref"
+          echo "Started the Steamify ISO's release (theupriser/steamify-cachyos-live-iso, master, kind $kind, Steamify ${sref:-the newest release})"

.github/workflows/git-upriser-sync.yml

@@ -0,0 +1,26 @@
+name: Sync git.upriser.nl mirror
+
+# Trigger the Gitea pull-mirror immediately instead of waiting for its interval,
+# so Gitea builds/tests right after any branch or tag lands on GitHub (the mirror has no sync interval of its own).
+on:
+  push:
+    branches: ['**']
+    tags: ['*']
+  workflow_dispatch:
+
+jobs:
+  sync:
+    # Gitea also reads .github/workflows on the mirror; only run on GitHub
+    if: github.server_url == 'https://github.com'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger mirror-sync
+        env:
+          GITEA_URL: ${{ secrets.GIT_UPRISER_URL }}
+          GIT_UPRISER_TOKEN: ${{ secrets.GIT_UPRISER_TOKEN }}
+          # Gitea "owner/repo"; defaults to the same path as on GitHub
+          GITEA_REPO: ${{ vars.GITEA_REPO || github.repository }}
+        run: |
+          curl --fail-with-body -sS --retry 5 --retry-delay 10 --retry-all-errors -X POST \
+            -H "Authorization: token ${GIT_UPRISER_TOKEN}" \
+            "${GITEA_URL%/}/api/v1/repos/${GITEA_REPO}/mirror-sync"

.no-release-yet

@@ -0,0 +1,3 @@
+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.

AGENTS.md

@@ -48,6 +48,13 @@ gamescope and the Plasma desktop. Primary target: the Valve Steam Machine
   `<id>_available` is checked via `component_available` (e.g. `machine`
   only on Fremont). Turn-on order is `COMPONENTS` order, turn-off reverse;
   `gaming` must stay first. Dependencies live in `toggle_component`.
+- **Hardware-specific fixes** that belong to a component but aren't a menu
+  row (e.g. `lib/nvidia.sh`: NVIDIA's kernel parameters and early modules
+  for gaming mode, called from `gaming_enable`/`gaming_disable`) detect the
+  hardware themselves, change only what's missing, and undo it on disable.
+  Add them to the source loop in `steamify.sh` and the table in
+  `TECHNICAL.md`. They can't be tested without the hardware: say so in the
+  changelog and keep the branch behind `.no-release-yet` until it was.
 - **Feature versions.** Set `FEATURE_VERSION[<id>]` (`lib/menu.sh`) to the new
   `VERSION` whenever what `<id>_enable` sets up changes (a new component gets
   one too): installs recorded with an older version
@@ -68,6 +75,13 @@ gamescope and the Plasma desktop. Primary target: the Valve Steam Machine
   the entry point's `for lib in ...; do` source loop and wraps everything
   after that loop in `main()`. Keep that loop on one line, keep all logic in
   functions, and don't rely on `SCRIPT_DIR` for anything but sourcing.
+  The workflow is one file for GitHub and a Gitea mirror (`github.server_url`): build and check run on both
+  (shellcheck through `ludeeus/action-shellcheck`, which brings its own binary; the artifact with
+  `upload-artifact@v4` on GitHub and `christopherhx/gitea-upload-artifact@v4` elsewhere: never mention
+  `upload-artifact@v3`, GitHub fails a workflow for a deprecated version even in a skipped step); the
+  release is `gh` on GitHub and `akkuman/gitea-release-action` on Gitea. A new release on GitHub also starts the
+  Steamify ISO's release (`gh workflow run iso-1-github-tag.yml` in steamify-cachyos-live-iso, secret
+  `ISO_DISPATCH_TOKEN`; skipped without it): the ISO repo's GitHub tag names it, the Gitea mirror builds it.
   CI (`.github/workflows/bundle.yml`) publishes the bundle as release
   `v$VERSION` on pushes to `main`; an existing version is never overwritten,
   so bump `VERSION` for every release.
@@ -119,7 +133,20 @@ gamescope and the Plasma desktop. Primary target: the Valve Steam Machine
       `sudo apt install gh`, then `gh auth login`) instead of working around
       it. Only the
       release branch's pull request into `main` is the user's: never commit
-      or merge to `main`, the user merges that one.
+      or merge to `main`, the user merges that one. Never work directly on
+      `main` or a `release/*` branch either: edits, even uncommitted ones,
+      go on a `feature/`/`bugfix/` branch (create it before editing; the
+      release branch only gets the version-bump commit and merged PRs).
+      Don't push a new `release/*` branch before it's needed: a push can
+      start CI builds (a dev ISO).
+      A machine without a git identity: pass the repo's author per command
+      (`git -c user.name=... -c user.email=... commit`, taken from `git
+      log`) instead of changing the git config.
+      A `.no-release-yet` file at the root of a feature/bugfix branch means
+      it must not be merged into the release branch yet (work in progress,
+      untested on hardware). When the feature is complete, ask the user
+      whether it may be released; on a yes, delete the file, then open the
+      pull request and merge it.
       Keep a feature/bugfix branch up to date by merging (or rebasing on)
       its release branch, the release branch by merging `main` when that
       moved.
@@ -252,6 +279,11 @@ gamescope and the Plasma desktop. Primary target: the Valve Steam Machine
   kernel only pairs that with a named lookup ("Port C") when the CEC driver
   registered first, which never happens since amdgpu loads from the
   initramfs. Without it `/dev/cec0` exists but stays at `f.f.f.f`.
+  The source comes from one raw.githubusercontent.com download, which GitHub rate-limits (HTTP 429 after a
+  day of test installs, per address): it's kept in `/var/cache/steamify/cros-ec-cec-<sha256:12>.c` and reused
+  while its checksum matches. The name carries the checksum, so a new pin (commit + SHA-256 in `lib/cec.sh`)
+  downloads its own file once and removes the old one. The repo is an unofficial mirror of Valve's kernel
+  without releases: if it ever disappears, ship the file with Steamify. The test VMs share the host's cache.
 - Power-off fix (`poweroff`, `lib/fremont-poweroff.sh`, a default sub-option
   of `machine`): recent kernels (7.2 and the 6.x/7.0/7.1 updates with the
   backport) keep the firmware's S4/S5 wake bit on GPIO
@@ -296,7 +328,7 @@ gamescope and the Plasma desktop. Primary target: the Valve Steam Machine
   (`state_get vram installed_pkgs`).
 - Install-time mode (`steamify.sh --defaults`, 2.6.0): applies what the menu
   would preselect, no menu or prompts (needs passwordless sudo). The Steam
-  Machine ISO ([steammachine-cachyos-live-iso](https://github.com/theupriser/steammachine-cachyos-live-iso))
+  Machine ISO ([steamify-cachyos-live-iso](https://github.com/theupriser/steamify-cachyos-live-iso))
   runs it in the installer for a user who has never logged in: no session
   bus, user systemd or plasmashell. So every `systemctl --user` goes through
   `user_systemctl` (`lib/common.sh`; without a session only unit files change,

CHANGELOG.md

@@ -5,9 +5,56 @@ All notable changes, per version and per commit. Versions follow
 `steamify.sh`. Versions before 0.7.0 were numbered afterwards,
 one per merged pull request.
 
+## 2.9.7 - 2026-10-01
+
+- **feat: the SteamOS conversion fixes a corrupted gaming mode screen with an NVIDIA GPU: nvidia-drm.modeset=1 and fbdev=1 on the kernel command line, NVIDIA modules in the initramfs (lib/nvidia.sh)**
+
+## 2.9.6 - 2026-09-30
+
+- **fix(ci): a dev ISO from a release branch is built with that branch's own Steamify (input steamify_ref of the ISO workflow), not the newest published release: release/2.9.6 kept producing 2.9.5 ISOs**
+- **docs: changelog hashes for 2.9.6**
+- `9a2965d` **fix(ci): the ISO workflow always runs from master; main asks for a release ISO, a release branch for a dev ISO (input `kind` of iso-1-github-tag.yml; feat/steamify is no longer needed)**
+- `c42d545` **fix(ci): a version published from main starts a real ISO release, a release branch a dev ISO (it always started the dev one)**
+- `b3bed43` **chore: Version 2.9.6**
+
+## 2.9.5 - 2026-09-30
+
+- `70ecb56` **ci: trigger a mirror sync**
+- `a7276cf` **ci: sync the git.upriser.nl mirror on every branch and tag**
+- `b3549d4` **ci: sync the mirror on release branch pushes too**
+- `a232a55` **feat(ci): sync the git.upriser.nl mirror on every push to main and every tag (git-upriser-sync.yml calls the mirror-sync API: the Gitea mirror builds at once instead of at its interval; secrets GIT_UPRISER_URL and GIT_UPRISER_TOKEN, retried, skipped on Gitea itself)**
+- `3676c64` **docs: link the renamed steamify-cachyos-live-iso repo (the release dispatches the ISO workflow iso-1-github-tag.yml there)**
+- `971e792` **chore: Version 2.9.5**
+
+## 2.9.4 - 2026-09-29
+
+- `619ef1f` **docs: AGENTS.md and TECHNICAL.md: the CEC driver cache, the one workflow for GitHub and a Gitea mirror, and that a new release starts the Steamify ISO's release**
+- `b624053` **chore: Version 2.9.4**
+
+## 2.9.3 - 2026-09-29
+
+- `7f5d29c` **feat(ci): a new Steamify release starts the Steamify ISO's release (a test build from the ISO repo's feat/steamify; secret ISO_DISPATCH_TOKEN)**
+- `cfe3ce7` **chore: Version 2.9.3**
+
+## 2.9.2 - 2026-09-29
+
+- **feat(ci): a Gitea mirror publishes its own release per version (akkuman/gitea-release-action; never overwrites one, notes from the changelog, links to the mirror)**
+- **fix(ci): the build also runs on a Gitea mirror (act_runner): shellcheck through ludeeus/action-shellcheck, which brings its own binary; the artifact goes up there with christopherhx/gitea-upload-artifact (GitHub refuses a workflow that mentions the deprecated upload-artifact@v3); releases are only published on GitHub**
+- `fe4f3f4` **chore: Version 2.9.2**
+
+## 2.9.1 - 2026-09-29
+
+- `c87e6c7` **docs: changelog for the CEC driver cache**
+- `fc05725` **fix: HDMI-CEC: an older cached CEC driver is removed when a new pin is downloaded**
+- `90bc5e4` **fix: HDMI-CEC: Valve's CEC driver is downloaded once and kept in /var/cache/steamify (GitHub rate-limits repeated downloads with HTTP 429, which left CEC off); turning CEC on again needs no network**
+- `d99ff65` **chore: Version 2.9.1**
+
 ## 2.9.0 - 2026-09-28
 
 - `d30d505` **chore: Version 2.9.0**
+- `66ea63c` **docs: KDE Plasma only: other desktops and display managers "are not supported" (README, was "don't work yet")**
+- `9b86cd1` **docs: KDE Plasma only: other desktops don't work yet (README)**
+- `d73e71d` **docs: README, TECHNICAL and TROUBLESHOOTING for 2.9.0: Steam's System settings, serial number and Wi-Fi backend, --defaults --list, the Steamify ISO**
 - `a72d848` **feat: Steam's OS Version is the SteamOS release Steamify follows (steamos-3.9), its OS Codename steam-machine; About this System keeps "CachyOS Linux" (UseOSReleaseVersion)**
 - `27a4070` **fix: Steam's OS Variant shows Steamify's version (VARIANT_ID=steamify-2.9.0; Steam shows VARIANT_ID, not VARIANT)**
 - `44bfe07` **fix: No VERSION_ID in os-release: About this System said "CachyOS Linux 2.9.0"; the version is in VARIANT ("Steamify 2.9.0")**

README.md

@@ -19,6 +19,10 @@ Steam Machine.
    on the desktop too.
    - **Boot into: gamescope / desktop** - where the PC starts. Gaming mode is
      the default.
+   - Steam's **System** settings show the SteamOS release Steamify follows
+     as OS Version (e.g. `steamos-3.9`), `steam-machine` as OS Codename and
+     Steamify's version as OS Variant. The OS name stays CachyOS
+     ([details](TECHNICAL.md#what-steams-system-settings-show)).
 2. **SteamOS theme** - the Vapor look of SteamOS for the desktop, with
    **Add to Steam** in right-click menus
    ([details](TECHNICAL.md#steamos-desktop-look)).
@@ -62,7 +66,8 @@ What Steamify can do on a Valve Steam Machine:
   ([details](TECHNICAL.md#hdmi-cec)).
 - **Steam Machine support** - the front **LED bar** works, Steam's
   **hardware settings** (fan, performance) work, and the power button puts
-  it to sleep like a console.
+  it to sleep like a console. Steam's System settings show the serial
+  number, and Steam's **Wi-Fi backend** setting works.
   - **Power-off fix** - on by default: shutting down really turns the Steam
     Machine off, also with the newest CachyOS kernel
     ([details](TECHNICAL.md#power-off-fix-steam-machine)).
@@ -73,6 +78,11 @@ What Steamify can do on a Valve Steam Machine:
 ## Requirements
 
 - CachyOS with the KDE Plasma desktop (the default CachyOS Desktop edition)
+
+> **KDE Plasma only.** Steamify works with KDE Plasma and its login managers
+> (plasma-login-manager or SDDM). Other desktops (GNOME, Hyprland, Cosmic,
+> ...) and other display managers are not supported: the switching between gaming mode
+> and the desktop, the theme and the shortcuts are all built for Plasma.
 - Your normal user account, with permission to use `sudo`
 
 ## Installation
@@ -83,6 +93,11 @@ Open **Konsole** on your Plasma desktop and run:
 curl -fsSL https://github.com/theupriser/steamify-cachyos/releases/latest/download/steamify.sh | bash
 ```
 
+Installing CachyOS on a Steam Machine? The
+[Steamify CachyOS ISO](https://github.com/theupriser/steamify-cachyos-live-iso)
+has Steamify built into the installer: pick the options there, and the
+first boot is already set up.
+
 Prefer to look at the script first? Clone the repository and run
 [`./steamify.sh`](steamify.sh) (keep the whole folder: it needs
 [`lib/`](lib/)).

TECHNICAL.md

@@ -111,6 +111,9 @@ Turning it off restores `/etc/plasmalogin.conf` from its backup, removes the
 SDDM autologin, sync bridge, shortcut, sudoers rule and Steam autostart, and
 switches back to plasma-login-manager.
 
+The conversion also sets what Steam's System settings show, see
+[below](#what-steams-system-settings-show).
+
 **Steam Deck/Machine icons:** `STEAM_GAMEPADUI_ARGS="-gamepadui -steamos3"`
 in `~/.config/environment.d/` (and gamescope-session's own environment
 file), which makes Steam show Steam Deck button glyphs in gaming mode.
@@ -139,6 +142,33 @@ taken from the newest `steamdeck-kde-presets` on Valve's SteamOS mirror
 Turning it off restores your previous look and panel layout, and removes `cachyos-vapor` again
 if the wizard installed it (and nothing else, like `cachyos-handheld`, needs it).
 
+## What Steam's System settings show
+
+With the SteamOS conversion on, `/etc/os-release` gets:
+
+| Key | Value | Shown in Steam as |
+|---|---|---|
+| `VERSION_ID` | `steamos-3.9`: the newest SteamOS release in Valve's repo (offline: the previous value) | OS Version |
+| `VERSION_CODENAME` | `steam-machine` | OS Codename |
+| `VARIANT` / `VARIANT_ID` | `Steamify 2.9.0` / `steamify-2.9.0` | OS Variant (`VARIANT_ID`) |
+
+The OS name stays CachyOS everywhere: Steam's OS Name comes from
+`lsb_release -d`, which isn't touched, and `NAME`/`PRETTY_NAME` stay
+CachyOS's. limine-snapper-sync finds the boot entries by that name, so
+changing it would break snapshot boot entries; `/etc/default/limine` gets
+`TARGET_OS_NAME="CachyOS"` as a guard when it has none.
+
+KDE's About this System would show `VERSION_ID` after the name
+("CachyOS Linux steamos-3.9"); `UseOSReleaseVersion=true` in
+`~/.config/kcm-about-distrorc` makes it show `VERSION`, which CachyOS doesn't
+have, so it keeps saying "CachyOS Linux".
+
+CachyOS's own hooks (`cachyos-hooks`) reset os-release on updates of
+`filesystem`; the pacman hook `zz-steamify-os-release` runs after them and
+sets the keys again (`/usr/local/libexec/steamify-os-release`). The values are
+refreshed after every Steamify run that changes something. Turning the
+conversion off removes the hook and runs CachyOS's `cachyos-branding` again.
+
 ## Front LED bar (Steam Machine)
 
 The **Steam Machine support** component, only shown on Fremont hardware
@@ -156,7 +186,14 @@ The **Steam Machine support** component, only shown on Fremont hardware
 - installs and enables `steamos-manager`, the service Steam in gaming mode
   uses for hardware settings (fan, performance, and the HDMI-CEC settings
   when [HDMI-CEC](#hdmi-cec) is on); it recognises the Steam Machine from its
-  DMI data.
+  DMI data;
+- makes the serial number readable for Steam, which shows it in its System
+  settings (`/etc/tmpfiles.d/steamify-serial.conf`: `product_serial` is
+  root-only by default);
+- makes Steam's Wi-Fi backend setting work: steamos-manager switches it in
+  `/etc/NetworkManager/conf.d/99-valve-wifi-backend.conf`, which is created
+  with `wifi.backend=wpa_supplicant` (NetworkManager's default) when no
+  backend is set anywhere yet.
 
 Turning it off removes all of that again (the AUR helper is kept).
 
@@ -169,6 +206,19 @@ or upgraded. A newly added kernel doesn't come with its headers, so
 `ensure-kernel-headers.service` checks at every boot and installs any
 missing `-headers` package, which makes DKMS build the driver for it.
 
+## NVIDIA fix for gaming mode
+
+gamescope drives the display itself through DRM/KMS, which with NVIDIA needs
+kernel modesetting and the framebuffer driver, and the driver loaded early;
+without them gaming mode can show a corrupted image. With an NVIDIA GPU and
+its driver installed (`lib/nvidia.sh`), the SteamOS conversion adds
+`nvidia-drm.modeset=1 nvidia-drm.fbdev=1` to the kernel command line (Limine,
+systemd-boot or GRUB; the file is backed up first) and
+`/etc/mkinitcpio.conf.d/90-steamify-nvidia.conf` (`MODULES+=(nvidia
+nvidia_modeset nvidia_uvm nvidia_drm)`), then rebuilds the initramfs and boot
+entries. Only what's missing is changed; it applies after a reboot. Turning
+the conversion off removes both. Untested on hardware so far.
+
 ## HDMI-CEC
 
 The **HDMI-CEC** item (on every PC; ticked by default only on a Steam
@@ -433,6 +483,7 @@ For an installer (the Steam Machine ISO), without a session or prompts
 ```bash
 steamify.sh --defaults                                  # what the menu would preselect
 steamify.sh --defaults --options gaming,theme,cec,machine --boot desktop
+steamify.sh --defaults --list                           # what --defaults can set up here, as JSON
 ```
 
 `--options` turns on exactly the listed items (the menu's ids: `gaming`,
@@ -472,11 +523,12 @@ immediately, which can turn into a loop - see
 | `lib/steam-game.sh` | Add as non-Steam game: Steamify in the Steam library (`patches/steam-shortcuts.py`) |
 | `lib/update-notifier.sh` | Update notifications: the notifier from `patches/` and its user timer |
 | `lib/first-login.sh` | `--defaults` without a session (the Steam Machine ISO's installer): the one-time first-login step that sets up single user's launcher on Plasma's new layout and opens the app |
+| `lib/nvidia.sh` | NVIDIA fix for gaming mode: kernel parameters and early modules (part of the SteamOS conversion) |
 | `lib/vram-booster.sh` | VRAM booster (`dmemcg-booster`, `plasma-foreground-booster`) |
 | `services/` | The systemd units the scripts install (`service_file`, `@KEY@` placeholders); see its README |
 | `patches/` | Module sources and patches the scripts build or apply (`patch_file`); see its README |
 | `.github/tools/bundle.sh` | Builds the single-file version (`dist/steamify.sh`), with `patches/` and `services/` embedded |
-| `.github/workflows/bundle.yml` | Builds and checks it on every push; publishes it on `main` |
+| `.github/workflows/bundle.yml` | Builds and checks it on every push (GitHub and a Gitea mirror); publishes it on `main`, and starts the Steamify ISO's release |
 
 The single-file version is generated: on every push to `main`, GitHub
 Actions runs `.github/tools/bundle.sh`, checks the result with `bash -n` and

TROUBLESHOOTING.md

@@ -18,6 +18,14 @@ restarted right away (`Relogin=true`), which is why it can loop.
 Run the wizard again and press `a` in the menu to re-apply everything that's
 on (also useful after a CachyOS update). To undo a part, untick it.
 
+## "Target OS name ... not found in /boot/limine.conf"
+
+limine-snapper-sync finds the boot entries by the OS name. Steamify never
+changes that name (it only adds version keys to `/etc/os-release`), and pins
+`TARGET_OS_NAME="CachyOS"` in `/etc/default/limine`. If you see this message,
+check that `PRETTY_NAME` in `/etc/os-release` still says `CachyOS`, or set
+`TARGET_OS_NAME` in `/etc/default/limine` to the name your boot entries use.
+
 ## The LED bar on the Steam Machine stays dark
 
 Restart once more; a freshly installed driver often needs a reboot. The menu

lib/cec.sh

@@ -26,6 +26,10 @@ CEC_DKMS_VER=1
 CEC_DKMS_SRC="/usr/src/$CEC_DKMS_NAME-$CEC_DKMS_VER"
 CEC_DRIVER_URL="https://raw.githubusercontent.com/evlaV/linux-integration/10c8c8800ccd3ae359203b4eefb6479f613b3b8e/drivers/media/cec/platform/cros-ec/cros-ec-cec.c"
 CEC_DRIVER_SHA256=e89fd4e87fceb32d713ffc59b64794779b3c2b3c012b0e2f2e9f0c40b42f4373
+# Downloaded once, then kept: raw.githubusercontent.com rate-limits (HTTP 429) repeated downloads
+# from one address, and turning CEC off and on again needs no network then. Named after its
+# checksum, so a new pin (a new commit and checksum above) downloads its file once by itself.
+CEC_DRIVER_CACHE="/var/cache/steamify/cros-ec-cec-${CEC_DRIVER_SHA256:0:12}.c"
 
 cec_link_steamos_manager() {
     # On a Steam Machine: steamos-manager writes cecd's config from Steam's
@@ -65,12 +69,19 @@ cec_driver_enable() {
     fi
     install_kernel_headers || return 1
     tmp="$(mktemp -d)"
-    info "Downloading Valve's Steam Machine CEC driver..."
-    if ! curl -fsL "$CEC_DRIVER_URL" -o "$tmp/cros-ec-cec.c" ||
-        ! echo "$CEC_DRIVER_SHA256  $tmp/cros-ec-cec.c" | sha256sum -c --quiet -; then
-        rm -rf "$tmp"
-        err "Downloading Valve's CEC driver failed (or its checksum didn't match)."
-        return 1
+    if [[ -f "$CEC_DRIVER_CACHE" ]] && echo "$CEC_DRIVER_SHA256  $CEC_DRIVER_CACHE" | sha256sum -c --quiet - 2>/dev/null; then
+        cp "$CEC_DRIVER_CACHE" "$tmp/cros-ec-cec.c"
+    else
+        info "Downloading Valve's Steam Machine CEC driver..."
+        if ! curl -fsL --retry 2 "$CEC_DRIVER_URL" -o "$tmp/cros-ec-cec.c" ||
+            ! echo "$CEC_DRIVER_SHA256  $tmp/cros-ec-cec.c" | sha256sum -c --quiet -; then
+            rm -rf "$tmp"
+            err "Downloading Valve's CEC driver failed (or its checksum didn't match)."
+            return 1
+        fi
+        # The name carries the checksum: a newer pin gets its own file, the old one goes.
+        sudo find "${CEC_DRIVER_CACHE%/*}" -maxdepth 1 -name 'cros-ec-cec-*.c' ! -name "${CEC_DRIVER_CACHE##*/}" -delete 2>/dev/null
+        sudo install -Dm644 "$tmp/cros-ec-cec.c" "$CEC_DRIVER_CACHE"
     fi
     # So it finds amdgpu's HDMI port (see the patch for why).
     patch_file cros-ec-cec-single-port.patch | patch -s -d "$tmp" -p1 ||

lib/login-manager.sh

@@ -109,6 +109,7 @@ gaming_enable() {
     esac
     create_desktop_shortcut
     steam_enable
+    nvidia_enable || return 1
     os_name_enable || return 1
 }
 
@@ -124,6 +125,7 @@ gaming_disable() {
     steam_disable
     krevert gaming
     os_name_disable
+    nvidia_disable
     ok "The PC boots to the normal login screen again (from the next boot)."
 }
 

lib/menu.sh

@@ -25,7 +25,7 @@ NO_PRESELECT=(boot cec kpin hdmi)
 # FEATURE_BASELINE.
 FEATURE_BASELINE=2.1.0
 declare -A FEATURE_VERSION=(
-    [gaming]=2.9.0 [boot]=2.1.0 [theme]=2.1.0 [glyphs]=2.1.0 [single]=2.1.0
+    [gaming]=2.9.7 [boot]=2.1.0 [theme]=2.1.0 [glyphs]=2.1.0 [single]=2.1.0
     [launcher]=2.1.0 [cec]=2.7.0 [machine]=2.9.0 [poweroff]=2.2.0 [vram]=2.3.0 [notify]=2.5.0 [steamgame]=2.5.1
     [kpin]=2.1.0 [hdmi]=2.1.0
 )

lib/nvidia.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# NVIDIA fix for gaming mode, part of the SteamOS conversion
+# (gaming_enable/gaming_disable). gamescope drives the display itself
+# through DRM/KMS; with NVIDIA that needs kernel modesetting and the
+# framebuffer driver (nvidia-drm.modeset=1 nvidia-drm.fbdev=1) and the
+# driver in the initramfs, or the screen shows a corrupted image.
+# Does nothing without an NVIDIA GPU that has its driver installed.
+# Sourced by steamify.sh; not meant to be run on its own.
+
+NVIDIA_PARAMS="nvidia-drm.modeset=1 nvidia-drm.fbdev=1"
+NVIDIA_INITRAMFS_CONF=/etc/mkinitcpio.conf.d/90-steamify-nvidia.conf
+NVIDIA_MARK="# steamify-nvidia"
+
+nvidia_present() {
+    # An NVIDIA GPU (PCI vendor 0x10de, display class) and its kernel driver.
+    local d
+    for d in /sys/class/drm/card[0-9]*/device; do
+        [[ "$(cat "$d/vendor" 2>/dev/null)" == 0x10de ]] || continue
+        [[ "$(cat "$d/class" 2>/dev/null)" == 0x03* ]] && modinfo nvidia_drm >/dev/null 2>&1 && return 0
+    done
+    return 1
+}
+
+nvidia_boot_file() {
+    # Same boot loaders as the kernel command line elsewhere (lib/hdmi-refresh.sh).
+    hdmi_boot_file
+}
+
+nvidia_param_set() {
+    # 0 when $1 (e.g. nvidia-drm.modeset=1) is on the kernel command line or
+    # already in the boot loader's file (not booted yet).
+    local f; f="$(nvidia_boot_file)"
+    grep -qw -- "$1" /proc/cmdline 2>/dev/null ||
+        { [[ -n "$f" ]] && grep -qw -- "$1" "$f" 2>/dev/null; }
+}
+
+nvidia_params_missing() {
+    local p
+    for p in $NVIDIA_PARAMS; do nvidia_param_set "$p" || return 0; done
+    return 1
+}
+
+nvidia_initramfs_ok() {
+    [[ -f "$NVIDIA_INITRAMFS_CONF" ]] || grep -qE '^MODULES=.*nvidia_drm' /etc/mkinitcpio.conf 2>/dev/null
+}
+
+nvidia_rebuild_boot() {
+    local f; f="$(nvidia_boot_file)"
+    info "Rebuilding the initramfs and boot entries..."
+    case "$f" in
+        /etc/default/limine) sudo limine-mkinitcpio ;;
+        /etc/sdboot-manage.conf) sudo /usr/bin/mkinitcpio -P && sudo sdboot-manage gen ;;
+        /etc/default/grub) sudo /usr/bin/mkinitcpio -P && sudo grub-mkconfig -o /boot/grub/grub.cfg ;;
+        *) sudo /usr/bin/mkinitcpio -P ;;
+    esac
+}
+
+nvidia_enable() {
+    nvidia_present || return 0
+    local f changed=0 p; f="$(nvidia_boot_file)"
+    if nvidia_params_missing; then
+        if [[ -z "$f" ]]; then
+            warn "NVIDIA GPU found, but no supported boot loader: add '$NVIDIA_PARAMS' to the kernel command line yourself."
+        else
+            info "NVIDIA GPU found: adding $NVIDIA_PARAMS to the kernel command line (fixes a corrupted screen in gaming mode)..."
+            backup_file "$f"
+            case "$f" in
+                /etc/default/limine)
+                    printf 'KERNEL_CMDLINE[default]+=" %s" %s\n' "$NVIDIA_PARAMS" "$NVIDIA_MARK" | sudo tee -a "$f" >/dev/null ;;
+                /etc/sdboot-manage.conf)
+                    sudo sed -i -E "s/^(LINUX_OPTIONS=\"[^\"]*)\"/\1 $NVIDIA_PARAMS\"/" "$f" ;;
+                /etc/default/grub)
+                    sudo sed -i -E "s/^(GRUB_CMDLINE_LINUX_DEFAULT=\"[^\"]*)\"/\1 $NVIDIA_PARAMS\"/" "$f" ;;
+            esac
+            changed=1
+        fi
+    fi
+    if ! nvidia_initramfs_ok; then
+        info "Loading the NVIDIA modules early (initramfs)..."
+        printf 'MODULES+=(nvidia nvidia_modeset nvidia_uvm nvidia_drm)\n' |
+            sudo install -Dm644 /dev/stdin "$NVIDIA_INITRAMFS_CONF" && changed=1
+    fi
+    if [[ $changed == 1 ]]; then
+        nvidia_rebuild_boot || { err "Rebuilding the boot entries failed."; return 1; }
+        ok "NVIDIA gaming mode fix applied; it takes effect after a reboot."
+    fi
+    return 0
+}
+
+nvidia_disable() {
+    local f changed=0; f="$(nvidia_boot_file)"
+    if [[ -n "$f" ]] && grep -q "$NVIDIA_PARAMS" "$f" 2>/dev/null; then
+        case "$f" in
+            /etc/default/limine) sudo sed -i "/$NVIDIA_MARK\$/d" "$f" ;;
+            *) sudo sed -i "s/ \?$NVIDIA_PARAMS//" "$f" ;;
+        esac
+        changed=1
+    fi
+    [[ -f "$NVIDIA_INITRAMFS_CONF" ]] && { sudo rm -f "$NVIDIA_INITRAMFS_CONF"; changed=1; }
+    [[ $changed == 1 ]] && nvidia_rebuild_boot
+    return 0
+}

steamify.sh

@@ -15,11 +15,11 @@
 set -uo pipefail
 
 # Release version, see CHANGELOG.md.
-VERSION=2.9.0
+VERSION=2.9.7
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-for lib in common state packages login-manager single-user steam-desktop steam-machine fremont-poweroff vram-booster hdmi-refresh cec boot-session vapor-theme steamos-extras bios desktop-shortcut wizard-shortcut steam-game update-notifier first-login menu backend; do
+for lib in common state packages login-manager single-user steam-desktop steam-machine fremont-poweroff vram-booster hdmi-refresh nvidia cec boot-session vapor-theme steamos-extras bios desktop-shortcut wizard-shortcut steam-game update-notifier first-login menu backend; do
     # shellcheck source=/dev/null
     source "$SCRIPT_DIR/lib/$lib.sh"
 done