commit the script

README.md

@@ -0,0 +1,150 @@
+# CachyOS Gamescope Boot Wizard
+
+A setup script that makes a CachyOS desktop install (running KDE Plasma +
+`plasma-login-manager`) always boot into a **Steam Deck-style gamescope
+session** — the same "always boots into Big Picture, switch to desktop and
+back on demand" experience SteamOS gives you on a real Deck or the Valve
+Steam Machine.
+
+It exists because, as of the CachyOS March 2026 release (which switched the
+default login manager from SDDM to `plasma-login-manager`), the stock
+`gamescope-session-cachyos` tooling has a few gaps that stop this from
+working out of the box. This script patches around them.
+
+## What's actually broken (and what this fixes)
+
+CachyOS's `gamescope-session-cachyos` package ships `steamos-session-select`,
+which is meant to work exactly like it does on real SteamOS. On a
+`plasma-login-manager` system, three things get in the way:
+
+1. **No `User=` written to the autologin config.**
+   `steam-set-session` (the script `steamos-session-select` calls under the
+   hood) only ever writes a `Session=` key to the autologin config file. On
+   SDDM this is fine, because SDDM's `User=` is set once by the installer and
+   never touched again. `plasma-login-manager` needs *both* `Session=` and
+   `User=` present to autologin at all — without `User=`, it just falls back
+   to showing the greeter every boot.
+
+2. **Missing `/etc/plasmalogin.conf.d` directory.**
+   If that directory doesn't exist, `steam-set-session` fails outright when
+   it tries to write to it. In practice this shows up as Steam's **"Switch to
+   Desktop"** hanging forever on a "Switching to Desktop" message with no way
+   back except a hard reset.
+
+3. **The base `/etc/plasmalogin.conf` wins over conf.d, and CachyOS ships it
+   hardcoded to `Session=plasma`.**
+   Every CachyOS tool that changes sessions (`steamos-session-select`, Steam's
+   power menu, and the `cachyos-gamescope-autologin.service` that's supposed
+   to reset you back to gamescope after a desktop session) only ever writes
+   to `/etc/plasmalogin.conf.d/zz-steamos-autologin.conf`. But the *base*
+   `/etc/plasmalogin.conf` file takes priority over that fragment, and it
+   ships with `Session=plasma` baked in — so none of those session switches
+   ever actually stick, no matter what the fragment says.
+
+This script fixes all three: it ensures the conf.d directory exists, sets the
+base config's `Session=`, `User=`, and `Relogin=true` correctly, and installs
+a small `systemd` path-watcher that keeps the base config in sync with
+whatever CachyOS's own tools write to the conf.d fragment — so switching
+sessions from inside Steam or the desktop actually works, in both
+directions, and resets to gamescope on the next boot by default (matching
+real Deck/SteamOS behavior).
+
+## Requirements
+
+- CachyOS (or an Arch-based system) with `pacman`
+- KDE Plasma installed
+- `plasma-login-manager` as the active display manager
+  *(the script will warn and ask for confirmation if it detects SDDM or
+  something else instead — most of these workarounds are specific to
+  `plasma-login-manager`)*
+- A regular user account with `sudo` access
+
+## Usage
+
+```bash
+git clone <this-repo-url>
+cd <this-repo>
+chmod +x setup-gamescope-boot.sh
+./setup-gamescope-boot.sh
+```
+
+Run it as your normal user, **not** as root — it calls `sudo` internally for
+the specific commands that need it.
+
+The script will:
+
+1. Ask which user account should autologin into gamescope (defaults to
+   whoever's running the script).
+2. Check for and offer to install `gamescope-session-cachyos`, `steam`, and
+   `mangohud` if any are missing.
+3. Create `/etc/plasmalogin.conf.d` if it doesn't exist.
+4. Back up and rewrite `/etc/plasmalogin.conf`'s `[Autologin]` section.
+5. Remove any stray manual override files from earlier troubleshooting
+   attempts (only files matching `zzz-steamos-autologin*.conf` — it never
+   touches `zz-steamos-autologin.conf`, which CachyOS's own tools own).
+6. Install a sync script (`/usr/local/bin/sync-steamos-session.sh`) and a
+   `systemd` path unit that keeps the base config aligned with session
+   switches made through Steam or `steamos-session-select`.
+7. Ask whether to reboot immediately to test it.
+
+It's **safe to re-run** — every step checks current state first, and any
+file it modifies gets backed up once with a `.bak-gamescope-wizard` suffix
+before the first change.
+
+## After running it
+
+Boot straight into gamescope: it should happen automatically. From inside
+gamescope, Steam's **Power → Switch to Desktop** should now work. From the
+desktop, logging out should drop you back into gamescope automatically
+(thanks to CachyOS's own `cachyos-gamescope-autologin.service`, which this
+script doesn't replace — it just makes sure the setting it writes actually
+takes effect).
+
+You can also switch sessions manually at any time:
+
+```bash
+steamos-session-select gamescope   # switch to gamescope right now
+steamos-session-select plasma      # switch to desktop right now
+steamos-session-select persistent  # remember whichever session you used last, across reboots
+steamos-session-select oneshot     # always start in gamescope regardless of what you used last (the default Deck-like behavior)
+```
+
+## Restoring the originals
+
+Every file the script modifies is backed up next to itself:
+
+```bash
+sudo cp /etc/plasmalogin.conf.bak-gamescope-wizard /etc/plasmalogin.conf
+```
+
+To fully remove the sync watcher this script adds:
+
+```bash
+sudo systemctl disable --now sync-steamos-session.path
+sudo rm /etc/systemd/system/sync-steamos-session.path
+sudo rm /etc/systemd/system/sync-steamos-session.service
+sudo rm /usr/local/bin/sync-steamos-session.sh
+sudo systemctl daemon-reload
+```
+
+## Caveats
+
+- This works around current CachyOS/`plasma-login-manager` behavior as of
+  September 2026. If CachyOS fixes `steam-set-session` upstream to write
+  `User=` and to target whichever base config the login manager actually
+  reads, this script becomes unnecessary — check for updates before running
+  it on a freshly reinstalled system.
+- Tested on a Valve Steam Machine (desktop AMD APU + discrete GPU) running
+  CachyOS Desktop edition. Should apply to any CachyOS desktop install using
+  `plasma-login-manager`, but hasn't been tested on Steam Deck/Legion Go
+  hardware, which typically ship with SDDM instead.
+- If you find CachyOS has patched the underlying issue, please open an issue
+  or PR here so the script can detect that and skip the workaround.
+
+## 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`
+
+## License
+
+MIT — do whatever you want with it.