Merge pull request #15 from theupriser/fix/cec-steam-settings

fix: Steam's HDMI-CEC settings reach cecd on a first run
2026-10-03 17:41:58 +02:00 · 2026-09-25 12:19:54 +02:00 · 2026-09-25 11:13:53 +02:00 · 2026-09-25 10:09:27 +02:00 · 2026-09-25 10:08:06 +02:00 · 2026-09-25 10:04:18 +02:00
15 changed files with 1007 additions and 381 deletions
@@ -5,8 +5,6 @@
 # release are moved to it, so both of these always get the newest version:
 #   curl -fsSL https://github.com/theupriser/steamify-cachyos/releases/latest/download/steamify.sh | bash
 #   curl -fsSL https://github.com/theupriser/steamify-cachyos/releases/download/latest/steamify.sh | bash
-# The bundle is also published as setup-gamescope-boot.sh, its name before
-# 0.9.0, so older install commands keep working.
 # Pull requests only build and check it, and warn when VERSION is already released.
 name: Single-file build

@@ -30,8 +28,6 @@ jobs:
      - name: Build
        run: |
          .github/tools/bundle.sh dist/steamify.sh
-          # Old name (before 0.9.0), for older install commands and links.
-          cp dist/steamify.sh dist/setup-gamescope-boot.sh

      - name: Check
        run: |
@@ -77,7 +73,7 @@ jobs:

          ## Changes in v$VERSION
          $changes"
-          gh release create "v$VERSION" dist/steamify.sh dist/setup-gamescope-boot.sh assets/steam-gaming-settings.svg \
+          gh release create "v$VERSION" dist/steamify.sh assets/steam-gaming-settings.svg \
              --target "$GITHUB_SHA" --title "Steamify CachyOS v$VERSION" --notes "$notes" --latest

          # "latest" follows the newest version tag, for the older install URL
@@ -90,4 +86,4 @@ jobs:
          else
            gh release create latest --title "Steamify CachyOS - latest (v$VERSION)" --notes "$latest_notes" --latest=false
          fi
-          gh release upload latest dist/steamify.sh dist/setup-gamescope-boot.sh assets/steam-gaming-settings.svg --clobber
+          gh release upload latest dist/steamify.sh assets/steam-gaming-settings.svg --clobber
@@ -17,7 +17,7 @@ gamescope and the Plasma desktop. Primary target: the Valve Steam Machine
  logic here.
 - `lib/*.sh` - one file per responsibility, each defining functions only
  (no top-level side effects besides constants). See the table in
-  `README.md`.
+  `TECHNICAL.md`.
 - **Components.** Every menu item `<id>` (listed in `COMPONENTS` and `LABEL`
  in `lib/menu.sh`) provides `<id>_status` (return 0 if on, detected from
  the system, no state file needed), `<id>_enable` and `<id>_disable`, all
@@ -0,0 +1,48 @@
+# HDMI-CEC: does my PC have it?
+
+The **HDMI-CEC** item in Steamify lets you use Steam with your TV's remote,
+and turns the TV on and off with the PC. It only works when the PC has a
+CEC device (`/dev/cec*`). Many PCs don't: on desktop PCs CEC is rare.
+How it works: [TECHNICAL.md](TECHNICAL.md#hdmi-cec); problems:
+[TROUBLESHOOTING.md](TROUBLESHOOTING.md#the-tv-remote-does-nothing-hdmi-cec).
+
+## Graphics cards
+
+- **NVIDIA:** no. The driver doesn't expose CEC on the HDMI port, on Linux
+  or Windows.
+- **AMD and Intel:** the CEC line of the HDMI port is normally not
+  connected on desktop cards. The Linux drivers (`amdgpu`, `i915`) only
+  support CEC over a **DisplayPort** connection: some DisplayPort-to-HDMI
+  adapters and built-in converter chips pass CEC along ("DP-AUX CEC"). That
+  depends on the adapter or chip, not on the graphics card, so it's worth
+  trying a different adapter.
+
+## Devices with CEC built in
+
+- the **Valve Steam Machine** (Steamify ticks HDMI-CEC by default there);
+- some **Intel NUC** mini PCs, which have a CEC chip on the board;
+- the **Raspberry Pi**.
+
+## Any PC: a USB CEC adapter
+
+A USB CEC adapter, such as the **Pulse-Eight USB-CEC adapter** (or a
+RainShadow Tech one), sits between the PC and the TV on the HDMI cable and
+works on Linux. This is the way to get CEC on a custom build, e.g. with an
+NVIDIA card. Steamify installs what these adapters need
+(`inputattach-cec-units`), so plug it in and turn on HDMI-CEC.
+
+## Check your PC
+
+After turning on HDMI-CEC in Steamify, the menu lists the CEC devices it
+found. Or run:
+
+```bash
+ls /dev/cec*
+```
+
+No device (and no USB adapter): no CEC on this PC. Also turn on CEC on the
+TV itself: it has a brand name there (Sony: BRAVIA Sync, Samsung: Anynet+,
+LG: SimpLink, Philips: EasyLink, Panasonic: VIERA Link).
+
+This overview is based on how the Linux drivers work; hardware differs,
+so the only sure test is `ls /dev/cec*` on your own PC.
@@ -5,6 +5,76 @@ 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.

+## 1.1.2 - 2026-09-25
+
+- **fix: Steam's HDMI-CEC settings reach cecd on a first run**
+  - HDMI-CEC runs before Steam Machine support, which installs
+    steamos-manager; so steamos-manager's `configure-cecd` unit couldn't be
+    enabled and cecd ran without Steam's settings. Steam Machine support now
+    links them once steamos-manager is there.
+
+## 1.1.1 - 2026-09-25
+
+- **perf: Pinned kernel before the LED driver**
+  - With the kernel pin ticked, Steam Machine support installs kernel
+    7.1.6-1 first, so DKMS builds the LED driver once, for that kernel,
+    instead of for the current kernel first and then again. The LED driver
+    then loads after the restart, which it now says instead of warning.
+- **fix: steamos-manager starts after cecd**
+  - It checks only at its start whether cecd runs; if it was first, Steam's
+    HDMI-CEC settings were missing until it restarted. A drop-in
+    (`/etc/systemd/user/steamos-manager.service.d/`) orders it after cecd.
+
+## 1.1.0 - 2026-09-25
+
+- **feat: HDMI-CEC** (experimental, on every PC; ticked by default only on a
+  Steam Machine)
+  - Valve's `cecd`, `cec-audio-control` and `inputattach-cec-units` from its
+    SteamOS repository (SHA-256 checked): use Steam with the TV remote, and
+    the TV turns on and off with the PC. On a Steam Machine, steamos-manager
+    configures it from Steam's settings.
+  - Works with any `/dev/cec*` (GPU or USB adapter); the menu lists them.
+  - `CEC.md`: which PCs have CEC (NVIDIA doesn't, AMD/Intel only over some
+    DisplayPort adapters), and USB adapters for your own build.
+  - Restarts steamos-manager, which only offers Steam its HDMI-CEC settings
+    when cecd was there at its start.
+  - The README no longer says Steam Machine support alone gives HDMI-CEC:
+    `cecd` wasn't installed, so it didn't.
+
+## 1.0.0 - 2026-09-25
+
+- **feat: Pin the kernel to 7.1.6-1 on a Steam Machine**
+  - New sub-option under Steam Machine support, ticked along with it (opt
+    out): newer CachyOS kernels make the Steam Machine reboot instead of
+    shutting down. Installs `linux-cachyos` and `-headers` 7.1.6-1 and adds
+    them to `IgnorePkg`; unticking removes the pin and updates the system.
+  - The packages are kept in `/var/cache/steamify/kernel` and reinstalled
+    from there without downloading; else from pacman's cache, the CachyOS
+    archive, the CachyOS mirror, or `PINNED_KERNEL_URL`.
+  - First download source: the `kernel-7.1.6-1` release of this repo, a
+    one-off release that always has these files.
+  - Every file is checked against its SHA-256 (in the script) and its
+    CachyOS signature before it's installed; a bad file is deleted.
+  - Installed kernel headers are no longer updated by the wizard, so the
+    pinned kernel keeps matching headers.
+  - The BIOS item moves down one (9 on a Steam Machine).
+- **docs: Shorter README, with a Steam Machine section**
+  - How it works moved to `TECHNICAL.md`, problems to `TROUBLESHOOTING.md`;
+    the README links to them and to the files it mentions.
+- **feat: No more KDE wallet password prompts in single user mode**
+  - Uses Valve's empty, password-less wallet, like SteamOS; apps such as
+    Brave no longer ask for the wallet password after autologin.
+  - Your own wallet is moved to `kdewallet.kwl.bak-steamify` and comes back,
+    unchanged, when single user mode is off; the single user wallet is kept
+    and reused next time.
+  - Moved from the SteamOS theme, where it only helped without any wallet.
+- **fix: No second sudo password prompt while installing yay**
+  - `makepkg -si` installs with `sudo -k`, which forgets the cached password;
+    yay is now built with makepkg and installed with `sudo pacman -U`.
+- **docs: LICENSE.md** with the MIT license the README already named.
+- **chore: No more `setup-gamescope-boot.sh` release asset**
+  - Only `steamify.sh` is published; the old name from before 0.9.0 is gone.
+
 ## 0.10.0 - 2026-09-24

 - `0f503dd` **feat: Boot into gamescope or the desktop**
@@ -0,0 +1,24 @@
+# MIT License
+
+Copyright (c) 2026 Rick Peters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The kernel packages in the `kernel-7.1.6-1` release are unmodified CachyOS
+packages under their own license (GPL-2.0); see that release for the source.
@@ -5,34 +5,54 @@ into Steam's Big Picture (gamescope), and you can switch to the KDE Plasma
 desktop and back whenever you like - just like on a Steam Deck or Valve's
 Steam Machine.

+- **One command**, then a simple checklist: pick what you want.
+- **Everything is undoable**: untick something and it's put back the way it was.
+- **Made for the Steam Machine**, and works on any CachyOS KDE desktop PC.
+
 ## What you get

-The wizard is a menu: pick what you want, and it turns each part on or off.
-Everything you turn off is put back the way it was.
+1. **SteamOS conversion** - boots straight into gaming mode. **Switch to
+   Desktop** in Steam works, and so does going back (the **Return to Gaming
+   Mode** icon on the desktop). Steam's on-screen keyboard (Steam + X) works
+   on the desktop too.
+   - **Boot into: gamescope / desktop** - where the PC starts. Gaming mode is
+     the default.
+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)).
+3. **Steam Deck/Machine icons** - Steam Deck button icons in gaming mode.
+4. **Single user mode** - like SteamOS: never a login or lock screen, and no
+   KDE wallet password prompts (e.g. from Brave). Typing a password with a
+   controller is no fun
+   ([details](TECHNICAL.md#single-user-mode-sddm-no-locking)).
+5. **Steamify shortcut** - an icon on the desktop and in the launcher that
+   opens the newest Steamify, so you don't need the install command again.
+6. **HDMI-CEC** (experimental; off by default, on by default on a Steam
+   Machine) - use Steam with your TV's
+   remote, and the TV turns on and off with the PC. Needs a PC with CEC (like
+   the Steam Machine) or a USB CEC adapter; most graphics cards, NVIDIA
+   included, don't have it. See [CEC.md](CEC.md) for which PCs do, and how to
+   add it to your own build ([details](TECHNICAL.md#hdmi-cec)).

-1. **SteamOS conversion** - boots straight into gaming mode, **Switch to
-   Desktop** in Steam works and so does going back (the **Return to Gaming
-   Mode** icon on the desktop), you're back in gaming mode after a restart,
-   and Steam's on-screen keyboard (Steam + X) also works on the desktop.
-2. **Boot into: [gamescope] / desktop** - a sub-option of 1, shown under it
-   while it's ticked: where the PC starts. Gamescope (gaming mode) is the
-   default; choose desktop to start in KDE Plasma instead, with Return to
-   Gaming Mode one double-click away.
-3. **SteamOS theme** - the Vapor look for the desktop (CachyOS's
-   `cachyos-vapor` package).
-4. **Steam Deck/Machine icons** - Steam Deck button icons in gaming mode.
-5. **Single user mode** - like SteamOS: never a login or lock screen, no
-   user switching or logging out. Typing a password with a controller is no
-   fun. (Needs 1.)
-6. **Steamify shortcut** - a "Steamify CachyOS" icon on the desktop and in
-   the app launcher (the Steam logo with a gear) that opens the newest version
-   of Steamify in Konsole, so you don't need the install command again.
-7. **Steam Machine support** - only shown on a Valve Steam Machine: the
-   driver for the front LED bar, and the hardware settings in Steam (fan,
-   TV control over HDMI-CEC).
-8. **Update BIOS** - only on a Steam Machine, opt-in and at your own risk:
-   installs the newest Steam Machine BIOS from Valve (see
-   [BIOS updates](#bios-updates-steam-machine)).
+## Steam Machine
+
+What Steamify can do on a Valve Steam Machine:
+
+- **HDMI-CEC** - ticked by default here, as on SteamOS: use Steam with your
+  TV's remote, and the TV turns on and off with the 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.
+  - **Pin the kernel to 7.1.6-1** - on by default: with newer CachyOS kernels
+    the Steam Machine reboots instead of shutting down. Untick it once CachyOS
+    fixes that. The kernel comes from its own
+    [release](https://github.com/theupriser/steamify-cachyos/releases/tag/kernel-7.1.6-1),
+    checked against CachyOS's signature
+    ([details](TECHNICAL.md#kernel-pin-steam-machine)).
+- **Update BIOS** - installs Valve's newest Steam Machine BIOS. Never ticked
+  by default, at your own risk, and only after two warnings
+  ([details](TECHNICAL.md#bios-updates-steam-machine)).

 ## Requirements

@@ -47,360 +67,60 @@ Open **Konsole** on your Plasma desktop and run:
 curl -fsSL https://github.com/theupriser/steamify-cachyos/releases/latest/download/steamify.sh | bash
 ```

-(Before 0.9.0 the script was called `setup-gamescope-boot.sh`; that name
-still works in the download URL.) That downloads and runs the latest
-single-file version, and works in any
-shell, including fish (CachyOS's default). Prefer to keep a copy, or to look
-at the script first? Clone the repository instead:
+Prefer to look at the script first? Clone the repository and run
+[`./steamify.sh`](steamify.sh) (keep the whole folder: it needs
+[`lib/`](lib/)).

-```bash
-git clone https://github.com/theupriser/steamify-cachyos.git
-cd steamify-cachyos
-./steamify.sh
-```
-
-Run it as yourself, not as root. You'll see a checklist:
+You'll see a checklist:

 ```
   [x] SteamOS conversion: boot into gaming mode, Steam on the desktop  (now: off)
+         └ Boot into: [gamescope]  desktop
 > [x] Install SteamOS theme: Vapor look (cachyos-vapor)  (now: off)
   [x] Install Steam Deck/Machine icons: Deck button icons in gaming mode  (now: off)
   [x] Single user mode: no password, lock screen or log out (SDDM)  (now: off)
+   [x] Steamify shortcut: desktop icon to run this again  (now: off)

-  Kernels (> = running; controller = Steam controller driver, LEDs = LED bar driver built)
-    6.18.52-1-cachyos-lts   linux-cachyos-lts  headers yes  controller yes
-  > 7.2.7-1-cachyos         linux-cachyos      headers yes  controller yes
-
-  Up/Down move   Space select   Enter run   a run + re-apply what's on   q quit
+  Up/Down move   Space select   Left/Right choose   Enter run
+  a run + re-apply what's on   q quit
 ```

-Move with the **arrow keys**, tick or untick with **Space** (on the **Boot
-into** row, **Left/Right** choose gamescope or desktop), and press
-**Enter** to run. "now:" shows what's on at the moment. Below the list, every
-installed kernel is shown with its headers and Steam controller driver; on a
-Steam Machine also whether the LED bar driver is built for it, and whether
-it's loaded right now, so a kernel update is easy to check. The wizard then
-shows what it will change, asks your password once, and at the end offers
-to restart (needed for changes to how the PC starts).
+Tick with **Space**, run with **Enter**. It shows what it will change, asks
+your password once, and offers to restart at the end. Below the list you see
+every installed kernel, so after an update it's easy to check that
+everything is in place.

-After each run the menu comes back with the new state, so you can change more
-in one go; quit with **q**. When something needs a restart, you choose
-between going back to the menu and restarting now. Quitting then asks
-"Restart now? [Y/n]": **n** takes you back to the menu (and the next **q**
-asks again); Ctrl+C quits without restarting.
-
-Run it again whenever you like - to change your choices, to turn things off
-again, or after a CachyOS update (press `a` in the menu to re-apply
-everything that's on).
-
-If you cloned the repository, keep the whole folder: the script needs the
-files in `lib/` next to it.
+Run it again whenever you like: to change your choices, or after a CachyOS
+update (press `a` to re-apply what's on).

 ## Using it

 - **To the desktop:** in gaming mode, open the Steam menu and choose
  **Power > Switch to Desktop**.
 - **Back to gaming mode:** double-click **Return to Gaming Mode** on the
-  desktop (or log out, if you're not using single user mode).
- After a restart you start in gaming mode, or on the desktop if you chose
-  **Boot into: desktop** in the menu. Switching back and forth works the same
-  either way.
+  desktop.
+- **Remove it all:** run the wizard and untick everything. You get the
+  normal CachyOS login screen back; Steam stays installed.

-Prefer to start where you left off last time? Run one of these in Konsole
-(with **Boot into: gamescope**):
+Prefer to start where you left off last time?

 ```bash
 steamos-session-select persistent  # start where you left off last time
 steamos-session-select oneshot     # always start in gaming mode (default)
 ```

-## If something goes wrong
+## Something wrong?

-**Gaming mode shows a black screen or keeps restarting.** Press
-**Ctrl+Alt+F3**, log in with your username and password, and run:
+Stuck on a black screen in gaming mode: press **Ctrl+Alt+F3**, log in, and run

 ```bash
 sudo /usr/lib/steamos/steam-set-session plasma.desktop && sudo systemctl restart display-manager
 ```

-That takes you back to the desktop.
-
-**The LED bar on the Steam Machine stays dark.** Restart the PC once more; a
-freshly installed driver often needs a reboot. Still dark? See
-[Front LED bar](#front-led-bar-steam-machine) under technical details.
-
-**Undo something:** run the wizard again and untick it.
-
---
-
-## Technical details
-
-### How turning things on and off works
-
-At startup every component checks whether it is on (`*_status` in `lib/`).
-You choose; the wizard then turns off what you unticked (in reverse order)
-and turns on what you ticked. To be able to undo:
-
- **System files** are backed up once, next to the original, with a
-  `.bak-gamescope-wizard` suffix, and restored when you turn the component
-  off.
- **KDE settings** in your home directory are recorded with their previous
-  value the first time the wizard changes them, in an undo journal under
-  `~/.local/state/cachyos-gamescope-boot/`. Turning the component off writes
-  the old values back (or removes keys that didn't exist before). Setups
-  made by older versions of the script, without a journal, fall back to
-  KDE's defaults.
- **Packages** installed for the conversion (Steam, gamescope-session, ...)
-  are kept when you turn it off; Steam Machine support removes its own.
-
-### Single user mode: SDDM, no locking
-
-Turning it on switches to **SDDM** and turns off everything that asks for a
-password or another user, per user: `action/lock_screen`, `switch_user` and
-`start_new_session` restrictions in `kdeglobals`, no automatic locking
-(`kscreenlockerrc`), Meta+L and Ctrl+Alt+Del unbound, and the launcher shows
-only Sleep / Restart / Shut Down (kickoff `primaryActions=3`), which hides
-the Session dropdown with Log Out. (Restricting `action/logout` would also
-hide Restart and Shut Down.) Turning it off restores all of that and moves
-the conversion back to plasma-login-manager.
-
-**SDDM** is what SteamOS uses, and CachyOS's `steam-set-session` supports it
-directly: it writes `/etc/sddm.conf.d/zz-steamos-autologin.conf`, which SDDM
-honours. The script installs and enables `sddm` (active from the next boot),
-writes `User=`, `Session=` and `Relogin=true` to
-`/etc/sddm.conf.d/10-gamescope-autologin.conf`, and removes any
-`[Autologin]` from `/etc/sddm.conf` (read last, so it would override both).
-No sync bridge or sudoers rule is needed; the shortcut just runs
-`steamos-session-select gamescope`, which logs out, and `Relogin=true` logs
-straight back in to gamescope.
-
-Without single user mode, the conversion uses **plasma-login-manager**
-(CachyOS's default since March 2026), which needs the workarounds below.
-
-### Why this is needed (plasma-login-manager)
-
-CachyOS's `gamescope-session-cachyos` package ships `steamos-session-select`,
-which is meant to work exactly like it does on real SteamOS. Since the March
-2026 release, CachyOS uses `plasma-login-manager` instead of SDDM, and three
-things get in the way:
-
-1. **No `User=` written to the autologin config.**
-   `steam-set-session` (called by `steamos-session-select`) only writes a
-   `Session=` key. `plasma-login-manager` needs both `Session=` and `User=`
-   to autologin at all; without `User=` it shows the greeter every boot.
-
-2. **Missing `/etc/plasmalogin.conf.d` directory.**
-   Without it, `steam-set-session` fails, and Steam's "Switch to Desktop"
-   hangs forever. *(Fixed upstream in `gamescope-session-cachyos` 1.1.6; the
-   script still creates the directory for older versions.)*
-
-3. **The base `/etc/plasmalogin.conf` wins over conf.d, and CachyOS ships it
-   with `Session=plasma`.**
-   Every tool that changes sessions (`steamos-session-select`, Steam's power
-   menu, and `cachyos-gamescope-autologin.service`, which resets you to
-   gamescope after a desktop session) only writes
-   `/etc/plasmalogin.conf.d/zz-steamos-autologin.conf`. The base file takes
-   priority, so none of those switches stick.
-
-The script sets `Session=`, `User=` and `Relogin=true` in the base config,
-and installs a small systemd path watcher that copies whatever CachyOS's
-tools write to the conf.d fragment into the base config.
-
-### What each component changes
-
-**SteamOS conversion** (`lib/login-manager.sh`, `lib/steam-desktop.sh`,
-`lib/desktop-shortcut.sh`):
-
- installs missing packages: `gamescope-session-cachyos`, `steam`,
-  `mangohud`, `xterm`, `ttf-liberation`, `wqy-zenhei`, `plasma-keyboard`;
- *SDDM (single user mode):* installs/enables SDDM and writes its autologin
-  config;
- *plasma-login-manager:* creates `/etc/plasmalogin.conf.d`, backs up and
-  rewrites the `[Autologin]` section of `/etc/plasmalogin.conf`, removes
-  stray `zzz-steamos-autologin*.conf` files from manual troubleshooting
-  (never `zz-steamos-autologin.conf`, which CachyOS's tools own), and
-  installs `/usr/local/bin/sync-steamos-session.sh` plus
-  `sync-steamos-session.path`/`.service`;
- `KWIN_IM_SHOW_ALWAYS=1` for the virtual keyboard and a
-  `steam-desktop-autostart` systemd user service that starts Steam silently
-  in Plasma only;
- the **Return to Gaming Mode** shortcut; on plasma-login-manager with a
-  narrow sudoers rule (`/etc/sudoers.d/gamescope-session-switch`) so it can
-  restart the login manager without a password prompt.
-
-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.
-
-**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.
-
-### SteamOS desktop look
-
-Installs CachyOS's `cachyos-vapor` package (the SteamOS Vapor theme the
-CachyOS handheld edition uses) from the CachyOS repository and switches your
-desktop to its Vapor global theme, including its desktop and window layout
-(like ticking "Desktop and window layout" in System Settings): Vapor colors
-and Plasma style, the SteamOS panel and launcher icon, and the Steam Deck
-wallpaper. Run it from the Plasma desktop: applying the layout needs a
-running Plasma session.
-
-It also adds the SteamOS desktop extras that `cachyos-vapor` doesn't ship,
-taken from the newest `steamdeck-kde-presets` on Valve's SteamOS mirror
-(checksum verified) and installed to `/usr/local`:
-
- **Add to Steam** in the right-click menu of apps, AppImages and `.exe`
-  files, and in the launcher: adds them to Steam as non-Steam games;
- **Nested Desktop**: add it to Steam from the launcher, then start it in
-  gaming mode for a Plasma desktop inside gaming mode;
- the SteamOS **Return to Gaming Mode** icon (Steam logo with a return arrow);
- a window rule that keeps the **Steam keyboard** above other windows;
- an empty, password-less **KWallet**, only if you don't have a wallet yet,
-  so nothing asks for a wallet password after autologin.
-
-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).
-
-### Front LED bar (Steam Machine)
-
-The **Steam Machine support** component, only shown on Fremont hardware
-(DMI `Valve`/`Fremont`, or `OEM`/`F7F` on early units):
-
- installs an AUR helper (`yay`) if neither `yay` nor `paru` is present;
- installs the kernel headers for every installed kernel;
- installs `leds-valve-dkms-git` from the AUR - Valve's own driver from the
-  SteamOS kernel - builds it for every installed kernel (so the LTS kernel
-  works too), and loads it at every boot (`/etc/modules-load.d/leds-valve.conf`);
- adds a udev rule (`/etc/udev/rules.d/70-valve-leds-user.rules`) that gives
-  your user the LED files, so Steam, which runs as you, can drive the bar;
- console-like power button: it puts the machine to sleep, and it never
-  suspends by itself on mains power (the launcher's Shut Down still shuts down);
- installs and enables `steamos-manager`, the service Steam in gaming mode
-  uses for hardware settings (fan, HDMI-CEC, performance); it recognises the
-  Steam Machine from its DMI data.
-
-Turning it off removes all of that again (the AUR helper is kept).
-
-The LEDs appear as `/sys/class/leds/valve-leds*`. The driver's Makefile
-builds against the running kernel (`uname -r`) instead of the kernel DKMS
-builds for, so the wizard adds a DKMS override
-(`/etc/dkms/leds-valve-dkms.conf`) that passes DKMS's target kernel in. With
-it, DKMS rebuilds the driver whenever a kernel or its headers are installed
-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.
-
-Troubleshooting:
-
-```bash
-dkms status
-ls -l /sys/class/leds/valve-leds*/
-sudo dmesg | grep -i valve
-cat /var/lib/dkms/leds-valve-dkms/0.1/build/make.log
-journalctl --user -b | grep -i led
-```
-
-### BIOS updates (Steam Machine)
-
-The **Update BIOS** item is only shown on a Steam Machine and is never ticked
-by default. It shows the BIOS version you have now and the newest one Valve
-ships (the `.cab` file in its `fremont-hw-support` package, looked up on
-Valve's SteamOS mirror):
-
-```
- [ ] Update BIOS: now F7F0107, newest F7F0108 (own risk)  (opt-in, runs once)
-```
-
-It can only be ticked when Valve has a newer BIOS than yours; when you're up
-to date, when the newest version can't be looked up (offline), or when an
-update is already waiting for a restart, it's greyed out.
-
-When you run it, the wizard:
-
-1. downloads Valve's package and checks its **SHA-256** against Valve's
-   repository, so it's exactly Valve's file;
-2. asks **fwupd** whether the firmware is for this very machine (fwupd compares
-   the firmware's hardware IDs with the device) and stops if it isn't;
-3. shows a large red **warning** with the current and the new version, and asks
-   whether you understand the risks (default: no);
-4. shows the warning **again** and only continues when you type `UPDATE`;
-5. hands the firmware to fwupd, which writes it during the **next restart**:
-   choose "restart now" or restart later yourself.
-
-**At your own risk:** a failed or interrupted BIOS update can leave the machine
-unable to start. Keep it on mains power, and never turn off the power, unplug
-it or press the power button while it updates, including during the restart;
-the screen can stay black for several minutes.
-
-To walk through it without flashing anything, run the wizard with
-`WIZARD_BIOS_DRY_RUN=1`: it downloads and checks the package and shows both
-warnings, skips fwupd's device check, and only prints the install command.
-
-### Manual session control
-
-```bash
-steamos-session-select gamescope   # switch to gamescope right now
-steamos-session-select plasma      # switch to desktop right now
-steamos-session-select persistent  # remember the last-used session across reboots
-steamos-session-select oneshot     # always start in gamescope (default, like a Deck)
-```
-
-With `Relogin=true`, a gamescope session that fails to start is restarted
-immediately, which can turn into a loop - hence the Ctrl+Alt+F3 escape above.
-
-### Removing everything
-
-Run the wizard and untick everything. Afterwards the PC boots to the normal
-CachyOS login screen again; packages installed for the conversion (Steam,
-gamescope-session, ...) stay installed.
-
-### Project layout
-
-| File | Responsibility |
-|---|---|
-| `steamify.sh` | Entry point: checks, menu, apply, summary, restart |
-| `lib/menu.sh` | The menu: detect, toggle, plan and apply changes |
-| `lib/state.sh` | Undo journal for KDE settings (`kset`/`krevert`) |
-| `lib/common.sh` | Output helpers, prompts, backups, plasmashell handling |
-| `lib/packages.sh` | Required packages, AUR helper (yay/paru) |
-| `lib/boot-session.sh` | Boot into gamescope or the desktop (`steamify-boot-desktop.service`) |
-| `lib/login-manager.sh` | SteamOS conversion: SDDM or plasmalogin autologin, sync bridge |
-| `lib/steam-desktop.sh` | Steam in the Plasma session; Steam Deck/Machine icons |
-| `lib/desktop-shortcut.sh` | Return to Gaming Mode shortcut and its sudoers rule |
-| `lib/vapor-theme.sh` | SteamOS theme: installs and switches to `cachyos-vapor` |
-| `lib/steamos-extras.sh` | SteamOS desktop extras from Valve's package (Add to Steam, Nested Desktop, icon, keyboard rule, KWallet) |
-| `lib/single-user.sh` | Single user mode: no lock screen, user switching or log out |
-| `lib/wizard-shortcut.sh` | Steamify shortcut: desktop icon and launcher entry that run the newest release |
-| `lib/bios.sh` | Update BIOS (Steam Machine, opt-in): current/newest version, double confirmation, fwupd |
-| `lib/steam-machine.sh` | Steam Machine support: LED driver, LED access, steamos-manager |
-| `.github/tools/bundle.sh` | Builds the single-file version (`dist/steamify.sh`) |
-| `.github/workflows/bundle.yml` | Builds and checks it on every push; publishes it on `main` |
-
-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
-shellcheck, and publishes it as a release per version (tag `v<VERSION>`,
-never overwritten; the newest is marked latest, and the `latest` tag follows
-it). It inlines
-`lib/*.sh` and wraps the entry point in `main()`, so bash has read the whole
-file before anything runs; when stdin is a pipe (`curl | bash`) it reattaches
-the terminal for the menu (set `WIZARD_KEEP_STDIN=1` to keep piped input).
-
-Notes for contributors and AI coding agents are in [`AGENTS.md`](AGENTS.md).
-
-### Caveats
-
- This works around CachyOS/`plasma-login-manager` behavior as of September
-  2026. If CachyOS fixes `steam-set-session` upstream, parts of this script
-  become unnecessary - please open an issue or PR if you notice that.
- Tested on a Valve Steam Machine running CachyOS Desktop edition. It should
-  work on any CachyOS desktop install using `plasma-login-manager`, but
-  hasn't been tested on Steam Deck/Legion Go hardware.
-
-### Related upstream reports
-
- [CachyOS/gamescope-session#9](https://github.com/CachyOS/gamescope-session/issues/9) - "Switch to Desktop" hang due to missing `/etc/plasmalogin.conf.d`
+More in [TROUBLESHOOTING.md](TROUBLESHOOTING.md). How it all works:
+[TECHNICAL.md](TECHNICAL.md). Changes per version: [CHANGELOG.md](CHANGELOG.md).
+Contributing (or an AI agent)? Read [AGENTS.md](AGENTS.md).

 ## License

-MIT - do whatever you want with it.
+MIT - do whatever you want with it. See [LICENSE.md](LICENSE.md).
@@ -0,0 +1,319 @@
+# Technical details
+
+How Steamify CachyOS works under the hood. For using it, see
+[README.md](README.md); for problems, [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
+## How turning things on and off works
+
+At startup every component checks whether it is on (`*_status` in `lib/`).
+You choose; the wizard then turns off what you unticked (in reverse order)
+and turns on what you ticked. To be able to undo:
+
+- **System files** are backed up once, next to the original, with a
+  `.bak-gamescope-wizard` suffix, and restored when you turn the component
+  off.
+- **KDE settings** in your home directory are recorded with their previous
+  value the first time the wizard changes them, in an undo journal under
+  `~/.local/state/cachyos-gamescope-boot/`. Turning the component off writes
+  the old values back (or removes keys that didn't exist before). Setups
+  made by older versions of the script, without a journal, fall back to
+  KDE's defaults.
+- **Packages** installed for the conversion (Steam, gamescope-session, ...)
+  are kept when you turn it off; Steam Machine support removes its own.
+
+## Single user mode: SDDM, no locking
+
+Turning it on switches to **SDDM** and turns off everything that asks for a
+password or another user, per user: `action/lock_screen`, `switch_user` and
+`start_new_session` restrictions in `kdeglobals`, no automatic locking
+(`kscreenlockerrc`), Meta+L and Ctrl+Alt+Del unbound, and the launcher shows
+only Sleep / Restart / Shut Down (kickoff `primaryActions=3`), which hides
+the Session dropdown with Log Out. (Restricting `action/logout` would also
+hide Restart and Shut Down.) Turning it off restores all of that and moves
+the conversion back to plasma-login-manager.
+
+**KDE wallet.** KDE normally unlocks your wallet with the password you log in
+with; with autologin nobody types it, so apps that keep passwords in it (Brave,
+for example) ask for the wallet password. Single user mode does what SteamOS
+does: it uses Valve's empty wallet without a password (from
+`steamdeck-kde-presets`, checksum verified). Your own wallet in
+`~/.local/share/kwalletd/` is moved to `kdewallet.kwl.bak-steamify` (and
+`.salt`). Turning single user mode off puts it back, unchanged; the single
+user wallet, with anything saved in it meanwhile, is kept as
+`kdewallet.kwl.steamify-single-user` and used again the next time it's on.
+Passwords aren't shared between the two wallets.
+
+**SDDM** is what SteamOS uses, and CachyOS's `steam-set-session` supports it
+directly: it writes `/etc/sddm.conf.d/zz-steamos-autologin.conf`, which SDDM
+honours. The script installs and enables `sddm` (active from the next boot),
+writes `User=`, `Session=` and `Relogin=true` to
+`/etc/sddm.conf.d/10-gamescope-autologin.conf`, and removes any
+`[Autologin]` from `/etc/sddm.conf` (read last, so it would override both).
+No sync bridge or sudoers rule is needed; the shortcut just runs
+`steamos-session-select gamescope`, which logs out, and `Relogin=true` logs
+straight back in to gamescope.
+
+Without single user mode, the conversion uses **plasma-login-manager**
+(CachyOS's default since March 2026), which needs the workarounds below.
+
+## Why this is needed (plasma-login-manager)
+
+CachyOS's `gamescope-session-cachyos` package ships `steamos-session-select`,
+which is meant to work exactly like it does on real SteamOS. Since the March
+2026 release, CachyOS uses `plasma-login-manager` instead of SDDM, and three
+things get in the way:
+
+1. **No `User=` written to the autologin config.**
+   `steam-set-session` (called by `steamos-session-select`) only writes a
+   `Session=` key. `plasma-login-manager` needs both `Session=` and `User=`
+   to autologin at all; without `User=` it shows the greeter every boot.
+
+2. **Missing `/etc/plasmalogin.conf.d` directory.**
+   Without it, `steam-set-session` fails, and Steam's "Switch to Desktop"
+   hangs forever. *(Fixed upstream in `gamescope-session-cachyos` 1.1.6; the
+   script still creates the directory for older versions.)*
+
+3. **The base `/etc/plasmalogin.conf` wins over conf.d, and CachyOS ships it
+   with `Session=plasma`.**
+   Every tool that changes sessions (`steamos-session-select`, Steam's power
+   menu, and `cachyos-gamescope-autologin.service`, which resets you to
+   gamescope after a desktop session) only writes
+   `/etc/plasmalogin.conf.d/zz-steamos-autologin.conf`. The base file takes
+   priority, so none of those switches stick.
+
+The script sets `Session=`, `User=` and `Relogin=true` in the base config,
+and installs a small systemd path watcher that copies whatever CachyOS's
+tools write to the conf.d fragment into the base config.
+
+## What each component changes
+
+**SteamOS conversion** (`lib/login-manager.sh`, `lib/steam-desktop.sh`,
+`lib/desktop-shortcut.sh`):
+
+- installs missing packages: `gamescope-session-cachyos`, `steam`,
+  `mangohud`, `xterm`, `ttf-liberation`, `wqy-zenhei`, `plasma-keyboard`;
+- *SDDM (single user mode):* installs/enables SDDM and writes its autologin
+  config;
+- *plasma-login-manager:* creates `/etc/plasmalogin.conf.d`, backs up and
+  rewrites the `[Autologin]` section of `/etc/plasmalogin.conf`, removes
+  stray `zzz-steamos-autologin*.conf` files from manual troubleshooting
+  (never `zz-steamos-autologin.conf`, which CachyOS's tools own), and
+  installs `/usr/local/bin/sync-steamos-session.sh` plus
+  `sync-steamos-session.path`/`.service`;
+- `KWIN_IM_SHOW_ALWAYS=1` for the virtual keyboard and a
+  `steam-desktop-autostart` systemd user service that starts Steam silently
+  in Plasma only;
+- the **Return to Gaming Mode** shortcut; on plasma-login-manager with a
+  narrow sudoers rule (`/etc/sudoers.d/gamescope-session-switch`) so it can
+  restart the login manager without a password prompt.
+
+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.
+
+**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.
+
+## SteamOS desktop look
+
+Installs CachyOS's `cachyos-vapor` package (the SteamOS Vapor theme the
+CachyOS handheld edition uses) from the CachyOS repository and switches your
+desktop to its Vapor global theme, including its desktop and window layout
+(like ticking "Desktop and window layout" in System Settings): Vapor colors
+and Plasma style, the SteamOS panel and launcher icon, and the Steam Deck
+wallpaper. Run it from the Plasma desktop: applying the layout needs a
+running Plasma session.
+
+It also adds the SteamOS desktop extras that `cachyos-vapor` doesn't ship,
+taken from the newest `steamdeck-kde-presets` on Valve's SteamOS mirror
+(checksum verified) and installed to `/usr/local`:
+
+- **Add to Steam** in the right-click menu of apps, AppImages and `.exe`
+  files, and in the launcher: adds them to Steam as non-Steam games;
+- **Nested Desktop**: add it to Steam from the launcher, then start it in
+  gaming mode for a Plasma desktop inside gaming mode;
+- the SteamOS **Return to Gaming Mode** icon (Steam logo with a return arrow);
+- a window rule that keeps the **Steam keyboard** above other windows.
+
+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).
+
+## Front LED bar (Steam Machine)
+
+The **Steam Machine support** component, only shown on Fremont hardware
+(DMI `Valve`/`Fremont`, or `OEM`/`F7F` on early units):
+
+- installs an AUR helper (`yay`) if neither `yay` nor `paru` is present;
+- installs the kernel headers for every installed kernel;
+- installs `leds-valve-dkms-git` from the AUR - Valve's own driver from the
+  SteamOS kernel - builds it for every installed kernel (so the LTS kernel
+  works too), and loads it at every boot (`/etc/modules-load.d/leds-valve.conf`);
+- adds a udev rule (`/etc/udev/rules.d/70-valve-leds-user.rules`) that gives
+  your user the LED files, so Steam, which runs as you, can drive the bar;
+- console-like power button: it puts the machine to sleep, and it never
+  suspends by itself on mains power (the launcher's Shut Down still shuts down);
+- 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.
+
+Turning it off removes all of that again (the AUR helper is kept).
+
+The LEDs appear as `/sys/class/leds/valve-leds*`. The driver's Makefile
+builds against the running kernel (`uname -r`) instead of the kernel DKMS
+builds for, so the wizard adds a DKMS override
+(`/etc/dkms/leds-valve-dkms.conf`) that passes DKMS's target kernel in. With
+it, DKMS rebuilds the driver whenever a kernel or its headers are installed
+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.
+
+## HDMI-CEC
+
+The **HDMI-CEC** item (on every PC; ticked by default only on a Steam
+Machine) installs
+Valve's CEC stack from its SteamOS `holo` repository, the newest `holo-X.Y`
+on `steamdeck-packages.steamos.cloud`, each package checked against the
+SHA-256 in Valve's package index:
+
+- `cecd`, Valve's CEC daemon (a user service started with the desktop and
+  gaming mode): TV remote keys become normal key presses (arrows, Enter,
+  Back), and it turns the TV on and off with the PC;
+- `cec-audio-control`: volume of the TV or receiver;
+- `inputattach-cec-units` (with `linuxconsole` from CachyOS for
+  `inputattach`): attaches USB CEC adapters (Pulse-Eight, RainShadow).
+
+It works with any `/dev/cec*`: a GPU that has CEC on its HDMI port (the
+Steam Machine; the CachyOS kernel has DisplayPort CEC built in) or a USB
+adapter ([CEC.md](CEC.md) lists which PCs have one). The menu lists the CEC
+devices found. Also turn on CEC on the TV
+(Sony: BRAVIA Sync, Samsung: Anynet+, LG: SimpLink). On a Steam Machine
+`steamos-manager` writes cecd's settings from Steam's (wake the TV, put it to
+sleep), in `~/.config/cecd/config.d/`, and Steam shows its HDMI-CEC
+settings; the wizard restarts steamos-manager so that happens right away.
+
+It's experimental: on SteamOS itself CEC can wake the Steam Machine right
+after it goes to sleep (Samsung TVs,
+[SteamOS#2626](https://github.com/ValveSoftware/SteamOS/issues/2626)) and
+upset CEC for the TV's other devices
+([SteamOS#2817](https://github.com/ValveSoftware/SteamOS/issues/2817)).
+Turning it off removes the packages again (`linuxconsole` only if the
+wizard installed it).
+
+## Kernel pin (Steam Machine)
+
+With CachyOS kernels newer than 7.1.6 a Steam Machine reboots instead of
+shutting down. The **Pin the kernel** sub-option (ticked along with Steam
+Machine support) installs `linux-cachyos` and `linux-cachyos-headers`
+7.1.6-1 and adds them to `IgnorePkg` in `/etc/pacman.conf`, so updates skip
+them. DKMS builds the LED driver for it; restart to boot it.
+
+The packages (and their signatures, which pacman checks) are kept in
+`/var/cache/steamify/kernel`, so re-applying needs no download. Missing
+files are taken from pacman's cache, else downloaded from this repo's
+`kernel-7.1.6-1` release, then `archive.cachyos.org`, then
+`mirror.cachyos.org` (which only has the current kernel). Every file must
+match the SHA-256 in the script and have a valid CachyOS signature; a bad
+one is deleted, so the next run downloads it again. Set `PINNED_KERNEL_URL`
+to a directory URL with the files to try another source first, or drop them
+into the kernel directory yourself.
+
+Unticking it removes the pin and runs `sudo pacman -Syu`, which brings the
+kernel back to CachyOS's current version; the files stay for next time.
+
+## BIOS updates (Steam Machine)
+
+The **Update BIOS** item is only shown on a Steam Machine and is never ticked
+by default. It shows the BIOS version you have now and the newest one Valve
+ships (the `.cab` file in its `fremont-hw-support` package, looked up on
+Valve's SteamOS mirror):
+
+```
+ [ ] Update BIOS: now F7F0107, newest F7F0108 (own risk)  (opt-in, runs once)
+```
+
+It can only be ticked when Valve has a newer BIOS than yours; when you're up
+to date, when the newest version can't be looked up (offline), or when an
+update is already waiting for a restart, it's greyed out.
+
+When you run it, the wizard:
+
+1. downloads Valve's package and checks its **SHA-256** against Valve's
+   repository, so it's exactly Valve's file;
+2. asks **fwupd** whether the firmware is for this very machine (fwupd compares
+   the firmware's hardware IDs with the device) and stops if it isn't;
+3. shows a large red **warning** with the current and the new version, and asks
+   whether you understand the risks (default: no);
+4. shows the warning **again** and only continues when you type `UPDATE`;
+5. hands the firmware to fwupd, which writes it during the **next restart**:
+   choose "restart now" or restart later yourself.
+
+**At your own risk:** a failed or interrupted BIOS update can leave the machine
+unable to start. Keep it on mains power, and never turn off the power, unplug
+it or press the power button while it updates, including during the restart;
+the screen can stay black for several minutes.
+
+To walk through it without flashing anything, run the wizard with
+`WIZARD_BIOS_DRY_RUN=1`: it downloads and checks the package and shows both
+warnings, skips fwupd's device check, and only prints the install command.
+
+## Manual session control
+
+```bash
+steamos-session-select gamescope   # switch to gamescope right now
+steamos-session-select plasma      # switch to desktop right now
+steamos-session-select persistent  # remember the last-used session across reboots
+steamos-session-select oneshot     # always start in gamescope (default, like a Deck)
+```
+
+With `Relogin=true`, a gamescope session that fails to start is restarted
+immediately, which can turn into a loop - see
+[TROUBLESHOOTING.md](TROUBLESHOOTING.md) for the way out.
+
+## Project layout
+
+| File | Responsibility |
+|---|---|
+| `steamify.sh` | Entry point: checks, menu, apply, summary, restart |
+| `lib/menu.sh` | The menu: detect, toggle, plan and apply changes |
+| `lib/state.sh` | Undo journal for KDE settings (`kset`/`krevert`) |
+| `lib/common.sh` | Output helpers, prompts, backups, plasmashell handling |
+| `lib/packages.sh` | Required packages, AUR helper (yay/paru) |
+| `lib/boot-session.sh` | Boot into gamescope or the desktop (`steamify-boot-desktop.service`) |
+| `lib/login-manager.sh` | SteamOS conversion: SDDM or plasmalogin autologin, sync bridge |
+| `lib/steam-desktop.sh` | Steam in the Plasma session; Steam Deck/Machine icons |
+| `lib/desktop-shortcut.sh` | Return to Gaming Mode shortcut and its sudoers rule |
+| `lib/vapor-theme.sh` | SteamOS theme: installs and switches to `cachyos-vapor` |
+| `lib/steamos-extras.sh` | SteamOS desktop extras from Valve's package (Add to Steam, Nested Desktop, icon, keyboard rule, KWallet) |
+| `lib/single-user.sh` | Single user mode: no lock screen, user switching or log out |
+| `lib/wizard-shortcut.sh` | Steamify shortcut: desktop icon and launcher entry that run the newest release |
+| `lib/bios.sh` | Update BIOS (Steam Machine, opt-in): current/newest version, double confirmation, fwupd |
+| `lib/cec.sh` | HDMI-CEC: Valve's `cecd` and friends from its `holo` repository |
+| `lib/steam-machine.sh` | Steam Machine support: LED driver, LED access, steamos-manager; kernel pin |
+| `.github/tools/bundle.sh` | Builds the single-file version (`dist/steamify.sh`) |
+| `.github/workflows/bundle.yml` | Builds and checks it on every push; publishes it on `main` |
+
+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
+shellcheck, and publishes it as a release per version (tag `v<VERSION>`,
+never overwritten; the newest is marked latest, and the `latest` tag follows
+it). It inlines
+`lib/*.sh` and wraps the entry point in `main()`, so bash has read the whole
+file before anything runs; when stdin is a pipe (`curl | bash`) it reattaches
+the terminal for the menu (set `WIZARD_KEEP_STDIN=1` to keep piped input).
+
+Notes for contributors and AI coding agents are in [`AGENTS.md`](AGENTS.md).
+
+## Caveats
+
+- This works around CachyOS/`plasma-login-manager` behavior as of September
+  2026. If CachyOS fixes `steam-set-session` upstream, parts of this script
+  become unnecessary - please open an issue or PR if you notice that.
+- Tested on a Valve Steam Machine running CachyOS Desktop edition. It should
+  work on any CachyOS desktop install using `plasma-login-manager`, but
+  hasn't been tested on Steam Deck/Legion Go hardware.
+
+## Related upstream reports
+
+- [CachyOS/gamescope-session#9](https://github.com/CachyOS/gamescope-session/issues/9) - "Switch to Desktop" hang due to missing `/etc/plasmalogin.conf.d`
@@ -0,0 +1,75 @@
+# Troubleshooting
+
+See [TECHNICAL.md](TECHNICAL.md) for how each part works.
+
+## Gaming mode shows a black screen or keeps restarting
+
+Press **Ctrl+Alt+F3**, log in with your username and password, and run:
+
+```bash
+sudo /usr/lib/steamos/steam-set-session plasma.desktop && sudo systemctl restart display-manager
+```
+
+That takes you back to the desktop. Gamescope sessions that fail to start are
+restarted right away (`Relogin=true`), which is why it can loop.
+
+## Something is set up wrong
+
+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.
+
+## The LED bar on the Steam Machine stays dark
+
+Restart once more; a freshly installed driver often needs a reboot. The menu
+shows per kernel whether the LED driver is built, and whether it's loaded.
+Still dark:
+
+```bash
+dkms status
+ls -l /sys/class/leds/valve-leds*/
+sudo dmesg | grep -i valve
+cat /var/lib/dkms/leds-valve-dkms/0.1/build/make.log
+journalctl --user -b | grep -i led
+```
+
+## The TV remote does nothing (HDMI-CEC)
+
+- Turn on CEC in the TV's settings (Sony: BRAVIA Sync, Samsung: Anynet+, LG:
+  SimpLink) and, if it has one, allow the PC to control it.
+- Check that the PC has a CEC device, and that `cecd` runs:
+
+```bash
+ls /dev/cec*
+systemctl --user status cecd
+journalctl --user -u cecd -b
+cec-ctl -d /dev/cec0 -S        # the devices on the TV's CEC bus (v4l-utils)
+```
+
+No `/dev/cec*`: your PC has no CEC; a USB CEC adapter (e.g. Pulse-Eight)
+works. See [CEC.md](CEC.md). The Steam Machine wakes up again right after going
+to sleep, or other devices lose CEC? That happens on SteamOS too; turn
+HDMI-CEC off in the wizard.
+
+## The Steam Machine still reboots when I shut it down
+
+Check that the pinned kernel is installed and running:
+
+```bash
+uname -r                                   # should be 7.1.6-1-cachyos
+pacman -Q linux-cachyos linux-cachyos-headers
+grep '^IgnorePkg' /etc/pacman.conf         # should list both packages
+```
+
+Not running it yet? Restart. Not installed? Run the wizard and make sure
+**Pin the kernel** under Steam Machine support is ticked. If you have more
+kernels installed (e.g. the LTS kernel), pick `linux-cachyos` in the boot menu.
+
+## The kernel pin can't download or verify the kernel
+
+The wizard tries this repo's `kernel-7.1.6-1` release, then the CachyOS
+archive and mirror. A file that fails its checksum or CachyOS signature is
+deleted, so running the wizard again downloads it once more. Offline? Put
+the four files from the
+[kernel-7.1.6-1 release](https://github.com/theupriser/steamify-cachyos/releases/tag/kernel-7.1.6-1)
+in `/var/cache/steamify/kernel` and run it again.
+
@@ -0,0 +1,114 @@
+#!/bin/bash
+# "HDMI-CEC" menu item, on any PC: Valve's CEC daemon (cecd), TV/receiver
+# volume control (cec-audio-control) and the units that attach USB CEC
+# adapters (Pulse-Eight, RainShadow) with inputattach. They're only in
+# Valve's SteamOS (holo) repository, not in CachyOS or the AUR. Works with
+# any /dev/cec*: a GPU with CEC (e.g. the Steam Machine) or a USB adapter.
+# On a Steam Machine, steamos-manager configures cecd from Steam's settings.
+# Sourced by steamify.sh; not meant to be run on its own.
+
+CEC_PKGS=(cecd cec-audio-control inputattach-cec-units)
+# steamos-manager checks once, at its start, whether cecd runs; order it
+# after cecd so it never misses it at login.
+CEC_ORDER_DROPIN=/etc/systemd/user/steamos-manager.service.d/10-steamify-after-cecd.conf
+
+cec_link_steamos_manager() {
+    # On a Steam Machine: steamos-manager writes cecd's config from Steam's
+    # CEC settings (its configure-cecd unit, run before cecd), and only
+    # offers Steam those settings when cecd was there at its start. Also
+    # called by Steam Machine support, which installs steamos-manager after
+    # this item ran.
+    pacman -Q steamos-manager >/dev/null 2>&1 || return 0
+    systemctl --user daemon-reload
+    systemctl --user enable steamos-manager-configure-cecd.service 2>/dev/null
+    systemctl --user start steamos-manager-configure-cecd.service 2>/dev/null
+    systemctl --user restart cecd.service 2>/dev/null
+    systemctl --user restart steamos-manager.service 2>/dev/null
+    return 0
+}
+
+cec_status() { pacman -Q "${CEC_PKGS[@]}" >/dev/null 2>&1; }
+
+fetch_holo_pkg() {
+    # fetch_holo_pkg <dir> <package>: download the newest <package> from
+    # Valve's newest holo repository into <dir> and print its path. The
+    # SHA-256 comes from Valve's package index and is verified.
+    local dir="$1" name="$2" repo desc file_name sha256
+    repo="$(curl -fsL "$VALVE_MIRROR/" | grep -oE 'holo-[0-9]+\.[0-9]+/' | tr -d / | sort -V | tail -n 1)"
+    if [[ ! -f "$dir/holo.db" ]]; then
+        [[ -n "$repo" ]] && curl -fsL "$VALVE_MIRROR/$repo/os/x86_64/$repo.db" -o "$dir/holo.db" ||
+            { err "Couldn't read Valve's SteamOS package index ($VALVE_MIRROR)."; return 1; }
+    fi
+    desc="$(tar -tf "$dir/holo.db" 2>/dev/null | grep -E "^$name-[0-9][^/]*/desc$" | head -n 1)"
+    [[ -n "$desc" ]] || { err "No $name in Valve's $repo repository."; return 1; }
+    file_name="$(tar -xOf "$dir/holo.db" "$desc" | awk '/^%FILENAME%$/ { getline; print }')"
+    sha256="$(tar -xOf "$dir/holo.db" "$desc" | awk '/^%SHA256SUM%$/ { getline; print }')"
+    info "Downloading $file_name ($repo)..." >&2
+    curl -fsL "$VALVE_MIRROR/$repo/os/x86_64/$file_name" -o "$dir/$file_name" ||
+        { err "Downloading $file_name failed."; return 1; }
+    echo "$sha256  $dir/$file_name" | sha256sum -c --quiet - >&2 ||
+        { err "Checksum mismatch for $file_name; not using it."; return 1; }
+    echo "$dir/$file_name"
+}
+
+cec_enable() {
+    local tmp p f files=()
+    # inputattach, needed by inputattach-cec-units.
+    if ! pacman -Q linuxconsole >/dev/null 2>&1; then
+        sudo pacman -S --needed --noconfirm linuxconsole || { err "Installing linuxconsole failed."; return 1; }
+        state_set cec installed_linuxconsole 1
+    fi
+    tmp="$(mktemp -d)"
+    for p in "${CEC_PKGS[@]}"; do
+        f="$(fetch_holo_pkg "$tmp" "$p")" || { rm -rf "$tmp"; return 1; }
+        files+=("$f")
+    done
+    info "Installing Valve's CEC daemon..."
+    if ! sudo pacman -U --needed --noconfirm "${files[@]}"; then
+        rm -rf "$tmp"
+        err "Installing ${CEC_PKGS[*]} failed."
+        return 1
+    fi
+    rm -rf "$tmp"
+    # Its udev rule gives the user /dev/cec*; cecd starts with the graphical
+    # session, after steamos-manager wrote its config from Steam's settings.
+    sudo udevadm control --reload
+    sudo udevadm trigger --subsystem-match=cec --action=add
+    sudo mkdir -p "$(dirname "$CEC_ORDER_DROPIN")"
+    printf '%s\n' "# Written by Steamify: steamos-manager only sees cecd if it runs at its start." \
+        '[Unit]' 'After=cecd.service' | sudo tee "$CEC_ORDER_DROPIN" >/dev/null
+    systemctl --user daemon-reload
+    cec_link_steamos_manager
+    if compgen -G "/dev/cec*" >/dev/null; then
+        systemctl --user restart cecd.service 2>/dev/null
+        ok "HDMI-CEC on ($(cd /dev && echo cec*)). Turn on CEC on your TV too (e.g. Sony: BRAVIA Sync, Samsung: Anynet+, LG: SimpLink)."
+    else
+        warn "No CEC device (/dev/cec*) found: your GPU may not support CEC. A USB CEC adapter"
+        warn "(e.g. Pulse-Eight) works too. Check again after a restart with: ls /dev/cec*"
+    fi
+}
+
+cec_disable() {
+    info "Removing HDMI-CEC..."
+    systemctl --user disable --now cecd.service cec-audio-control.socket cec-audio-control.service 2>/dev/null
+    systemctl --user disable steamos-manager-configure-cecd.service 2>/dev/null
+    sudo pacman -Rns --noconfirm "${CEC_PKGS[@]}" 2>/dev/null
+    sudo rm -f "$CEC_ORDER_DROPIN"
+    sudo rmdir "$(dirname "$CEC_ORDER_DROPIN")" 2>/dev/null
+    systemctl --user daemon-reload
+    if [[ -n "$(state_get cec installed_linuxconsole)" ]]; then
+        sudo pacman -Rns --noconfirm linuxconsole 2>/dev/null
+        state_clear cec
+    fi
+    sudo udevadm control --reload
+    systemctl --user is-active -q steamos-manager.service 2>/dev/null &&
+        systemctl --user restart steamos-manager.service
+    ok "HDMI-CEC removed."
+}
+
+cec_overview() {
+    # For the menu's kernel overview.
+    local dev="none"
+    compgen -G "/dev/cec*" >/dev/null && dev="$(cd /dev && echo cec*)"
+    echo "CEC devices: $dev  cecd: $(systemctl --user is-active cecd 2>/dev/null)"
+}
@@ -5,13 +5,17 @@

 # Menu order. Components are turned on in this order and off in reverse;
 # gaming must come first (single user builds on it).
-COMPONENTS=(gaming boot theme glyphs single launcher machine bios)
+COMPONENTS=(gaming boot theme glyphs single launcher cec machine kpin bios)
 # One-off actions rather than on/off components: never preselected, never
 # re-applied, not listed as on or off.
 ACTIONS=(bios)
+# Sub-options, shown indented under their parent and only while it's ticked.
+declare -A PARENT=([boot]=gaming [kpin]=machine)
 # Never preselected on a first run: booting into the desktop is a choice,
-# gamescope is the default.
-NO_PRESELECT=(boot)
+# gamescope is the default; HDMI-CEC is opt-in (it can wake the machine or
+# upset other devices on the TV, even on SteamOS), except on a Steam Machine,
+# which has CEC like on SteamOS.
+NO_PRESELECT=(boot cec)

 declare -A LABEL=(
    [gaming]="SteamOS conversion: boot into gaming mode, Steam on the desktop"
@@ -20,14 +24,16 @@ declare -A LABEL=(
    [glyphs]="Install Steam Deck/Machine icons: Deck button icons in gaming mode"
    [single]="Single user mode: no password, lock screen or log out (SDDM)"
    [launcher]="Steamify shortcut: desktop icon to run this again"
+    [cec]="HDMI-CEC: use Steam with the TV remote, TV on/off with the PC (experimental)"
    [machine]="Steam Machine support: LED bar driver, hardware settings in Steam"
+    [kpin]="Pin the kernel to $PINNED_KERNEL_VER (fixes rebooting after shutdown)"
    [bios]="Update BIOS"
 )
 declare -A CURRENT WANTED

 component_available() {
    case "$1" in
-        machine) machine_available ;;
+        machine|kpin) machine_available ;;
        bios) bios_available ;;
    esac
 }
@@ -41,10 +47,10 @@ boot_mode() {
 }

 menu_visible() {
-    # Shown in the menu. "Boot into" is a sub-option of the conversion: only
-    # while the conversion is ticked.
+    # Shown in the menu. A sub-option ("Boot into", the kernel pin) only
+    # while its parent is ticked.
    component_available "$1" || return 1
-    [[ "$1" != boot || "${WANTED[gaming]:-0}" == 1 ]]
+    [[ -z "${PARENT[$1]:-}" || "${WANTED[${PARENT[$1]}]:-0}" == 1 ]]
 }

 component_selectable() {
@@ -69,6 +75,7 @@ detect_components() {
            component_available "$c" && ! is_action "$c" &&
                [[ " ${NO_PRESELECT[*]} " != *" $c "* ]] && WANTED[$c]=1
        done
+        machine_available && WANTED[cec]=1
    fi
 }

@@ -81,6 +88,9 @@ toggle_component() {
    if [[ "$c" == gaming && "${WANTED[gaming]}" == 0 ]]; then WANTED[single]=0; WANTED[boot]=0; fi
    # Where to boot to is part of the conversion, too.
    if [[ "$c" == boot && "${WANTED[boot]}" == 1 ]]; then WANTED[gaming]=1; fi
+    # The kernel pin is opt-out: ticked along with Steam Machine support.
+    if [[ "$c" == machine ]]; then WANTED[kpin]=${WANTED[machine]}; fi
+    if [[ "$c" == kpin && "${WANTED[kpin]}" == 1 ]]; then WANTED[machine]=1; fi
 }

 show_menu() {
@@ -103,6 +113,8 @@ show_menu() {
            [[ "${CURRENT[gaming]}" == 1 ]] || now="-"
            want="gaming"; [[ "${WANTED[boot]}" == 1 ]] && want="desk"
            printf "  %-3s %-6s %-6s   └ %s\n" "$i" "$now" "$want" "$(boot_choice "${WANTED[boot]}")"
+        elif [[ -n "${PARENT[$c]:-}" ]]; then
+            printf "  %-3s %b %-6s   └ %s\n" "$i" "$now" "$want" "${LABEL[$c]}"
        elif component_selectable "$c"; then
            printf "  %-3s %b %-6s %s\n" "$i" "$now" "$want" "${LABEL[$c]}"
        else
@@ -149,6 +161,8 @@ draw_menu_tui() {
            local mode=gamescope; [[ "${CURRENT[boot]}" == 1 ]] && mode=desktop
            state="  (${c_bold}←/→${c_reset} choose)"
            [[ "${CURRENT[gaming]}" == 1 ]] && state="  (now: $mode; ${c_bold}←/→${c_reset} choose)"
+        elif [[ -n "${PARENT[$c]:-}" ]]; then
+            line="    └ $line"
        fi
        if ! component_selectable "$c"; then
            # Greyed out: nothing to do (e.g. BIOS already up to date).
@@ -41,8 +41,13 @@ bootstrap_yay() {
        return 1
    fi

+    # Build only, then install it ourselves: makepkg -i runs `sudo -k pacman`,
+    # which forgets the cached sudo password and asks for it again.
    info "Building and installing yay (this runs makepkg as your user, not root)..."
-    if (cd "$tmp_dir/yay-bin" && makepkg -si --noconfirm); then
+    local -a pkgs
+    if (cd "$tmp_dir/yay-bin" && makepkg --noconfirm) &&
+        mapfile -t pkgs < <(cd "$tmp_dir/yay-bin" && makepkg --packagelist | grep -v -- '-debug-') &&
+        sudo pacman -U --noconfirm "${pkgs[@]}"; then
        ok "yay installed."
        rm -rf "$tmp_dir"
        return 0
@@ -9,6 +9,78 @@ single_status() {
    [[ "$(kreadconfig6 --file kdeglobals --group "KDE Action Restrictions" --key action/lock_screen)" == false ]]
 }

+WALLET_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/kwalletd"
+# The user's own wallet while single user mode is on, and ours after.
+WALLET_BACKUP=".bak-steamify"
+WALLET_OURS=".steamify-single-user"
+
+stop_kwallet() {
+    # The wallet daemon keeps the file open and would write it back.
+    local d
+    for d in kwalletd6 ksecretd; do
+        pkill -u "$USER" -x "$d" 2>/dev/null && sleep 1
+    done
+    return 0
+}
+
+single_wallet_enable() {
+    # Like SteamOS: an empty, password-less wallet (Valve's own file), so
+    # nothing asks for a wallet password (e.g. Brave at start): with
+    # autologin nobody typed the login password that unlocks the usual one.
+    # The user's wallet is moved aside and comes back when this is off. The
+    # wallet from an earlier time in single user mode is reused, with
+    # whatever was saved in it then.
+    local tmp f
+    if [[ -f "$WALLET_DIR/kdewallet.kwl$WALLET_OURS" ]]; then
+        stop_kwallet
+        for f in kdewallet.kwl kdewallet.salt; do
+            [[ -f "$WALLET_DIR/$f" && ! -e "$WALLET_DIR/$f$WALLET_BACKUP" ]] &&
+                mv "$WALLET_DIR/$f" "$WALLET_DIR/$f$WALLET_BACKUP"
+            [[ -f "$WALLET_DIR/$f$WALLET_OURS" ]] && mv -f "$WALLET_DIR/$f$WALLET_OURS" "$WALLET_DIR/$f"
+        done
+        kset single kwalletrc Wallet "First Use" false
+        ok "Single user mode's wallet (no password) is back; your own is kept as kdewallet.kwl$WALLET_BACKUP."
+        return 0
+    fi
+    tmp="$(mktemp -d)"
+    if ! fetch_valve_presets "$tmp"; then
+        rm -rf "$tmp"
+        warn "Couldn't get Valve's empty wallet; apps may still ask for the wallet password."
+        return 0
+    fi
+    if [[ -f "$WALLET_DIR/kdewallet.kwl" ]] &&
+        cmp -s "$WALLET_DIR/kdewallet.kwl" "$tmp/usr/share/kwalletd/kdewallet.kwl"; then
+        rm -rf "$tmp"
+        return 0
+    fi
+    stop_kwallet
+    mkdir -p "$WALLET_DIR"
+    for f in kdewallet.kwl kdewallet.salt; do
+        # Never overwrite an earlier backup: that one is the user's.
+        [[ -f "$WALLET_DIR/$f" && ! -e "$WALLET_DIR/$f$WALLET_BACKUP" ]] &&
+            mv "$WALLET_DIR/$f" "$WALLET_DIR/$f$WALLET_BACKUP"
+        install -m 600 "$tmp/usr/share/kwalletd/$f" "$WALLET_DIR/$f"
+    done
+    rm -rf "$tmp"
+    kset single kwalletrc Wallet "First Use" false
+    [[ -f "$WALLET_DIR/kdewallet.kwl$WALLET_BACKUP" ]] &&
+        info "Your wallet is kept as $WALLET_DIR/kdewallet.kwl$WALLET_BACKUP and comes back when single user mode is off."
+    ok "Empty wallet without a password: apps no longer ask for the wallet password."
+}
+
+single_wallet_disable() {
+    # The user's wallet back; ours (maybe with passwords saved since) is
+    # kept next to it.
+    [[ -f "$WALLET_DIR/kdewallet.kwl$WALLET_BACKUP" ]] || return 0
+    stop_kwallet
+    local f
+    for f in kdewallet.kwl kdewallet.salt; do
+        [[ -f "$WALLET_DIR/$f" ]] && mv -f "$WALLET_DIR/$f" "$WALLET_DIR/$f$WALLET_OURS"
+        [[ -f "$WALLET_DIR/$f$WALLET_BACKUP" ]] && mv "$WALLET_DIR/$f$WALLET_BACKUP" "$WALLET_DIR/$f"
+    done
+    ok "Your own wallet is back (the empty one is kept as kdewallet.kwl$WALLET_OURS)."
+}
+
 single_launcher() {
    # Launcher: only Sleep / Restart / Shut Down, no Session dropdown (where
    # Log Out lives). Restricting action/logout instead would also hide
@@ -42,6 +114,7 @@ single_enable() {
    single_launcher

    restart_plasmashell_if_stopped
+    single_wallet_enable
    ok "Single user: no lock screen, user switching or log out."
 }

@@ -70,5 +143,6 @@ single_disable() {
        done
    fi
    restart_plasmashell_if_stopped
+    single_wallet_disable
    ok "KDE's normal lock screen and user switching are back."
 }
@@ -14,16 +14,175 @@ detect_valve_fremont() {
        [[ "$vendor" == "OEM" && "$product" == "F7F" ]]
 }

+# Kernel pinned on a Steam Machine: with newer linux-cachyos releases it
+# reboots instead of shutting down. The packages are kept in
+# PINNED_KERNEL_DIR, so re-applying (or reinstalling after an update slipped
+# through) needs no download.
+PINNED_KERNEL_VER="7.1.6-1"
+PINNED_KERNEL_KVER="7.1.6-1-cachyos"
+PINNED_KERNEL_PKGS=(linux-cachyos linux-cachyos-headers)
+PINNED_KERNEL_DIR="${PINNED_KERNEL_DIR:-/var/cache/steamify/kernel}"
+# SHA-256 of each package, so a file from any source is the one reviewed
+# here; its CachyOS signature is checked as well.
+declare -A PINNED_KERNEL_SHA256=(
+    [linux-cachyos]=417fcd07102192b86e78e92ed7171d5a49378e9f57faea3fa2c7c541e9f68d08
+    [linux-cachyos-headers]=d069866a11d9092746e1d5133cefd8924f027da2c9bf5af38d30b3aed6ded9bf
+)
+# Tried in order, after the kernel dir and pacman's cache. Our own release
+# always has these files; the archive keeps every release; the mirror only
+# the current one. PINNED_KERNEL_URL puts another source (a directory
+# holding the files) in front.
+PINNED_KERNEL_SOURCES=(
+    ${PINNED_KERNEL_URL:+"$PINNED_KERNEL_URL"}
+    "https://github.com/theupriser/steamify-cachyos/releases/download/kernel-$PINNED_KERNEL_VER"
+    "https://archive.cachyos.org/archive/cachyos"
+    "https://mirror.cachyos.org/repo/x86_64/cachyos"
+)
+
+pinned_kernel_installed() {
+    local p
+    for p in "${PINNED_KERNEL_PKGS[@]}"; do
+        [[ "$(pacman -Q "$p" 2>/dev/null)" == "$p $PINNED_KERNEL_VER" ]] || return 1
+    done
+}
+
+fetch_pinned_kernel_file() {
+    # $1 = file name. Local kernel dir first, then pacman's cache, then the
+    # download sources. Downloads go to a .part file so a broken one is never
+    # mistaken for a finished one.
+    local f="$1" dest="$PINNED_KERNEL_DIR/$1" src
+    [[ -s "$dest" ]] && return 0
+    if [[ -s "/var/cache/pacman/pkg/$f" ]]; then
+        sudo cp "/var/cache/pacman/pkg/$f" "$dest" && return 0
+    fi
+    for src in "${PINNED_KERNEL_SOURCES[@]}"; do
+        if sudo curl -fL --retry 2 --connect-timeout 15 -o "$dest.part" "$src/$f" 2>/dev/null; then
+            sudo mv "$dest.part" "$dest"
+            return 0
+        fi
+        warn "Couldn't get $f from $src, trying the next source..."
+    done
+    sudo rm -f "$dest.part"
+    return 1
+}
+
+verify_pinned_kernel_pkg() {
+    # $1 = package name, $2 = file. Both checks must pass: the SHA-256 from
+    # this script, and the CachyOS signature (pacman on its own installs a
+    # local file without a .sig: LocalFileSigLevel = Optional).
+    local sum
+    sum="$(sha256sum "$2" | cut -d' ' -f1)"
+    if [[ "$sum" != "${PINNED_KERNEL_SHA256[$1]}" ]]; then
+        err "$(basename "$2") doesn't match its expected checksum."
+        return 1
+    fi
+    if ! sudo pacman-key --verify "$2.sig" "$2" >/dev/null 2>&1; then
+        err "$(basename "$2") doesn't have a valid CachyOS signature."
+        return 1
+    fi
+}
+
+pin_kernel_in_pacman_conf() {
+    # Adds our packages to IgnorePkg in [options], keeping what's there.
+    local p
+    for p in "${PINNED_KERNEL_PKGS[@]}"; do
+        grep -Eq "^IgnorePkg\s*=.*(\s|=)$p(\s|$)" /etc/pacman.conf && continue
+        if grep -Eq '^IgnorePkg\s*=' /etc/pacman.conf; then
+            sudo sed -i -E "0,/^IgnorePkg\s*=/s/^(IgnorePkg\s*=.*)$/\1 $p/" /etc/pacman.conf
+        else
+            sudo sed -i -E "0,/^\[options\]/s//[options]\nIgnorePkg = $p/" /etc/pacman.conf
+        fi
+    done
+}
+
+unpin_kernel_in_pacman_conf() {
+    local p
+    for p in "${PINNED_KERNEL_PKGS[@]}"; do
+        sudo sed -i -E "/^IgnorePkg\s*=/s/\s$p(\s|$)/\1/" /etc/pacman.conf
+    done
+    # Drop the line if nothing is left on it.
+    sudo sed -i -E '/^IgnorePkg\s*=\s*$/d' /etc/pacman.conf
+}
+
+install_pinned_kernel() {
+    sudo mkdir -p "$PINNED_KERNEL_DIR"
+    pin_kernel_in_pacman_conf
+    if pinned_kernel_installed; then
+        ok "Kernel $PINNED_KERNEL_VER already installed and pinned."
+        return 0
+    fi
+
+    local p f files=()
+    info "Getting kernel $PINNED_KERNEL_VER (kept in $PINNED_KERNEL_DIR)..."
+    for p in "${PINNED_KERNEL_PKGS[@]}"; do
+        f="$p-$PINNED_KERNEL_VER-x86_64.pkg.tar.zst"
+        fetch_pinned_kernel_file "$f" && fetch_pinned_kernel_file "$f.sig" ||
+            { err "Couldn't download $f from any source."; return 1; }
+        if ! verify_pinned_kernel_pkg "$p" "$PINNED_KERNEL_DIR/$f"; then
+            # Removed, so the next run fetches it again.
+            sudo rm -f "$PINNED_KERNEL_DIR/$f" "$PINNED_KERNEL_DIR/$f.sig"
+            err "Removed it; run the wizard again to download it once more."
+            return 1
+        fi
+        files+=("$PINNED_KERNEL_DIR/$f")
+    done
+
+    # pacman checks each package against the .sig next to it.
+    info "Installing kernel $PINNED_KERNEL_VER..."
+    if ! sudo pacman -U --noconfirm "${files[@]}"; then
+        err "Installing kernel $PINNED_KERNEL_VER failed."
+        return 1
+    fi
+    [[ "$(uname -r)" != "$PINNED_KERNEL_KVER" ]] && RESTART_FOR_LOGIN=true
+    ok "Kernel $PINNED_KERNEL_VER installed and pinned (restart to use it)."
+}
+
+remove_kernel_pin() {
+    # Back to CachyOS's current kernel. The packages stay in
+    # PINNED_KERNEL_DIR, so turning support on again doesn't download.
+    unpin_kernel_in_pacman_conf
+    pinned_kernel_installed || return 0
+    info "Updating the kernel back to CachyOS's current version..."
+    sudo pacman -Syu --noconfirm ||
+        { warn "Updating the kernel failed; run: sudo pacman -Syu"; return 0; }
+    RESTART_FOR_LOGIN=true
+}
+
+# "Pin the kernel" menu item, a sub-option of Steam Machine support.
+kpin_status() {
+    pinned_kernel_installed && grep -Eq '^IgnorePkg\s*=.*\slinux-cachyos(\s|$)' /etc/pacman.conf
+}
+
+kpin_enable() {
+    install_pinned_kernel || return 1
+    # The DKMS pacman hook built leds-valve for the new headers; make sure.
+    if pacman -Qi leds-valve-dkms-git >/dev/null 2>&1 &&
+        ! dkms status -k "$PINNED_KERNEL_KVER" leds-valve-dkms 2>/dev/null | grep -q installed; then
+        sudo dkms install leds-valve-dkms/0.1 -k "$PINNED_KERNEL_KVER" ||
+            warn "Building the LED driver for $PINNED_KERNEL_KVER failed."
+    fi
+}
+
+kpin_disable() { remove_kernel_pin; }
+
 install_kernel_headers() {
    # DKMS can only build leds-valve against kernels whose headers are
    # installed. CachyOS ships several kernels (linux-cachyos, -lts, -bore,
    # ...); install the matching -headers package for every one present.
    local -a kernels headers=()
-    mapfile -t kernels < <(pacman -Qqo /usr/lib/modules/*/pkgbase 2>/dev/null | sort -u)
    local k
+    mapfile -t kernels < <(pacman -Qqo /usr/lib/modules/*/pkgbase 2>/dev/null | sort -u)
+    # Installed headers are left alone: -S would update them past a pinned
+    # kernel (linux-cachyos-headers on a Steam Machine).
+    local have=0
    for k in "${kernels[@]}"; do
+        pacman -Q "${k}-headers" >/dev/null 2>&1 && { have=$((have + 1)); continue; }
        pacman -Si "${k}-headers" >/dev/null 2>&1 && headers+=("${k}-headers")
    done
+    if [[ ${#headers[@]} -eq 0 && $have -gt 0 ]]; then
+        ok "Kernel headers already installed."
+        return 0
+    fi
    if [[ ${#headers[@]} -eq 0 ]]; then
        warn "Couldn't work out which kernel headers package you need."
        warn "Install the -headers package for your kernel (e.g. linux-cachyos-headers) yourself."
@@ -92,6 +251,13 @@ install_valve_led_driver() {
    # Load now, and on every boot.
    echo leds-valve | sudo tee /etc/modules-load.d/leds-valve.conf >/dev/null

+    # The running kernel was just replaced (the kernel pin): its modules are
+    # gone, so the driver can only load after the restart.
+    if [[ ! -d "/usr/lib/modules/$(uname -r)/kernel" ]]; then
+        ok "The LED driver loads after the restart (into the new kernel)."
+        return 0
+    fi
+
    info "Loading the leds-valve kernel module..."
    if sudo modprobe leds-valve; then
        ok "Module loaded."
@@ -185,6 +351,7 @@ kernel_overview() {
        fi
        echo -e "  ${running}${line}"
    done
+    cec_status && { echo; echo -e "    $(cec_overview)"; }
    if [[ "$leds" == true ]]; then
        local loaded="$miss" nodes
        lsmod | grep -q '^leds_valve' && loaded="$mark"
@@ -201,6 +368,11 @@ machine_status() {
 }

 machine_enable() {
+    # The pinned kernel first when it's wanted too, so DKMS builds the LED
+    # driver for it once, instead of for the current kernel and then again.
+    if [[ "${WANTED[kpin]:-0}" == 1 ]]; then
+        install_pinned_kernel || { err "Couldn't set up kernel $PINNED_KERNEL_VER."; return 1; }
+    fi
    ensure_aur_helper || { warn "Couldn't set up an AUR helper automatically. Install yay or paru, then run the wizard again."; return 1; }
    install_valve_led_driver || { warn "LED driver setup ran into a problem - see errors above."; return 1; }
    install_headers_boot_check
@@ -223,6 +395,8 @@ EOF
    sudo systemctl enable --now inputplumber.service
    sudo systemctl enable --now steamos-manager.service
    systemctl --user enable steamos-manager.service 2>/dev/null
+    # HDMI-CEC ran before this and couldn't link cecd to steamos-manager yet.
+    cec_status && cec_link_steamos_manager

    # Console-like power handling, as SteamOS's powerdevilrc (mains-power
    # part; there is no battery): the power button sleeps instead of showing
@@ -3,7 +3,7 @@
 # newest Valve steamdeck-kde-presets package: "Add to Steam" (file
 # right-click menu and launcher), Nested Desktop (Plasma as a game inside
 # gaming mode), the "Return to Gaming Mode" icon, the Steam Keyboard window
-# rule and an empty KWallet. Part of the SteamOS theme component
+# rule. Part of the SteamOS theme component
 # (lib/vapor-theme.sh). System files go to /usr/local (nothing
 # package-owned); per-user settings go through the undo journal.
 # Sourced by steamify.sh; not meant to be run on its own.
@@ -75,15 +75,6 @@ extras_enable() {
    sudo cp -r "$src/share/applications/steam/holo-nested-desktop" "$NESTED_DIR"
    sudo sed -i "s|/usr/share/applications/steam/holo-nested-desktop|$NESTED_DIR|" "$NESTED_DIR/holo-nested-desktop.desktop"

-    # An empty, password-less wallet (Valve's), so nothing asks for a wallet
-    # password: with autologin nobody typed one to unlock it. Only when the
-    # user has no wallet yet; an existing one is never touched.
-    local wallet="${XDG_DATA_HOME:-$HOME/.local/share}/kwalletd"
-    if [[ ! -f "$wallet/kdewallet.kwl" ]]; then
-        mkdir -p "$wallet"
-        install -m 600 "$src/share/kwalletd/kdewallet.kwl" "$src/share/kwalletd/kdewallet.salt" "$wallet/"
-        kset theme kwalletrc Wallet "First Use" false
-    fi
    rm -rf "$tmp_dir"

    sudo gtk-update-icon-cache -q -f -t /usr/local/share/icons/hicolor 2>/dev/null || true
@@ -122,7 +113,6 @@ extras_disable() {
    for pkg in kdialog zstd curl; do
        [[ -n "$(state_get theme "installed_$pkg")" ]] && sudo pacman -R --noconfirm "$pkg" >/dev/null 2>&1
    done
-    # The keyboard rule and kwalletrc are reverted by the theme's journal.
-    # The wallet itself stays: secrets may have been saved in it since.
+    # The keyboard rule is reverted by the theme's journal.
    return 0
 }
@@ -10,16 +10,16 @@
 # them on or off to match what the user picks; turning one off restores
 # what was there before (system files from .bak-gamescope-wizard backups,
 # KDE settings from the undo journal in lib/state.sh). Components live in
-# lib/, see README.md. Safe to re-run.
+# lib/, see TECHNICAL.md. Safe to re-run.

 set -uo pipefail

 # Release version, see CHANGELOG.md.
-VERSION=0.10.0
+VERSION=1.1.2

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

-for lib in common state packages login-manager single-user steam-desktop steam-machine boot-session vapor-theme steamos-extras bios desktop-shortcut wizard-shortcut menu; do
+for lib in common state packages login-manager single-user steam-desktop steam-machine cec boot-session vapor-theme steamos-extras bios desktop-shortcut wizard-shortcut menu; do
    # shellcheck source=/dev/null
    source "$SCRIPT_DIR/lib/$lib.sh"
 done
@@ -139,7 +139,7 @@ while true; do

    apply_changes
    # Login manager changes only take effect after a restart.
-    [[ " ${TO_DISABLE[*]} ${TO_ENABLE[*]} " =~ \ (gaming|single|boot)\  ]] &&
+    [[ " ${TO_DISABLE[*]} ${TO_ENABLE[*]} " =~ \ (gaming|single|boot|kpin)\  ]] &&
        RESTART_FOR_LOGIN=true

    echo
@@ -149,6 +149,9 @@ while true; do
        component_available "$c" && ! is_action "$c" || continue
        if [[ "$c" == boot ]]; then
            [[ "${CURRENT[gaming]}" == 1 ]] && echo "       └ boots into: $(boot_mode "${CURRENT[boot]}")"
+        elif [[ -n "${PARENT[$c]:-}" ]]; then
+            [[ "${CURRENT[${PARENT[$c]}]}" == 1 ]] || continue
+            if [[ "${CURRENT[$c]}" == 1 ]]; then echo -e "       └ ${c_green}on ${c_reset} ${LABEL[$c]}"; else echo "       └ off  ${LABEL[$c]}"; fi
        elif [[ "${CURRENT[$c]}" == 1 ]]; then echo -e "  ${c_green}on ${c_reset} ${LABEL[$c]}"; else echo "  off  ${LABEL[$c]}"; fi
    done
    if [[ ${#FAILED[@]} -gt 0 ]]; then
Author	SHA1	Message	Date
theupriser	9aef0a986a	Merge pull request #15 from theupriser/fix/cec-steam-settings fix: Steam's HDMI-CEC settings reach cecd on a first run	2026-09-25 12:19:54 +02:00
theupriser	f7aa2412df	fix: Steam's HDMI-CEC settings reach cecd on a first run HDMI-CEC runs before Steam Machine support, which installs steamos-manager, so its configure-cecd unit couldn't be enabled. Link them from Steam Machine support too.	2026-09-25 11:13:53 +02:00
theupriser	87162efaa2	Merge pull request #14 from theupriser/perf/pin-kernel-first Perf/pin kernel first	2026-09-25 10:09:27 +02:00
theupriser	c79a3bbda5	fix: No LED warnings when the kernel pin just replaced the running kernel	2026-09-25 10:08:06 +02:00
theupriser	ba11f58d9e	perf: Pinned kernel before the LED driver; steamos-manager after cecd With the kernel pin ticked, install 7.1.6-1 before the LED driver, so DKMS builds it once. steamos-manager checks for cecd only at its start: order it after cecd.	2026-09-25 10:04:18 +02:00
theupriser	45ff036f09	Merge pull request #13 from theupriser/feat/hdmi-cec Feat/hdmi cec	2026-09-25 09:53:29 +02:00
theupriser	de02f267f4	docs: README's Steam Machine part lists its features, HDMI-CEC included	2026-09-25 09:50:55 +02:00
theupriser	0f123004d0	docs: CEC.md, which PCs have HDMI-CEC and how to add it	2026-09-25 09:47:22 +02:00
theupriser	3048b35dd8	feat: HDMI-CEC ticked by default on a Steam Machine	2026-09-25 09:18:28 +02:00
theupriser	f7837f82b9	fix: Restart steamos-manager after HDMI-CEC changes It only offers Steam its HDMI-CEC settings when cecd was there at its start.	2026-09-25 09:17:05 +02:00
theupriser	3eb41eef5a	feat: HDMI-CEC with Valve's cecd, on any PC Opt-in menu item: cecd, cec-audio-control and inputattach-cec-units from Valve's holo repository (SHA-256 checked). Works with any /dev/cec*.	2026-09-25 09:11:44 +02:00
theupriser	41422e5bb4	chore: Version 1.0.0	2026-09-25 08:44:49 +02:00
theupriser	6c2e203563	fix: No second sudo password prompt while installing yay makepkg -si installs with sudo -k, which forgets the cached password. Build with makepkg, install with sudo pacman -U.	2026-09-25 08:35:54 +02:00
theupriser	1522e5632d	feat: No more KDE wallet password prompts in single user mode Valve's empty, password-less wallet, like SteamOS. The user's wallet is moved aside and restored when single user mode is off; the single user wallet is kept and reused next time.	2026-09-25 08:27:50 +02:00
theupriser	1d994ae359	docs: Add LICENSE.md (MIT)	2026-09-25 08:22:11 +02:00
theupriser	700f3e514b	docs: README links to the files it mentions; drop setup-gamescope-boot.sh The release no longer publishes the bundle under its pre-0.9.0 name.	2026-09-25 08:18:40 +02:00
theupriser	d78652c862	docs: Shorter README, with a Steam Machine section How it works moved to TECHNICAL.md, problems to TROUBLESHOOTING.md.	2026-09-25 08:17:07 +02:00
theupriser	727e6a2302	feat: Kernel files from our own release, checked before install The kernel-7.1.6-1 release is the first download source. Every file must match the SHA-256 in the script and have a valid CachyOS signature.	2026-09-25 08:08:28 +02:00
theupriser	c4bd1ca39c	feat: Pin the kernel to 7.1.6-1 on a Steam Machine Sub-option of Steam Machine support, ticked along with it: newer CachyOS kernels make the Steam Machine reboot instead of shutting down. Packages are kept in /var/cache/steamify/kernel and reinstalled from there; else pacman's cache, the CachyOS archive or mirror, or PINNED_KERNEL_URL.	2026-09-25 07:58:02 +02:00
theupriser	a449a9e467	Enhance kernel installation and header management Updated kernel installation process to include header symlink setup and improved logging messages.	2026-09-24 22:01:54 +02:00
theupriser	388b1286c9	Implement kernel installation and locking function Adds a function to install and pin a specific CachyOS kernel with verification and locking.	2026-09-24 21:39:15 +02:00