Add maintainer notes (Omarchy 4 facts, conventions, test checklist)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

NOTES.md

@@ -0,0 +1,85 @@
+# DeckShift — maintainer notes
+
+Working notes for future development sessions. User-facing docs live in README.md.
+
+## Current state (2026-07-27)
+
+- **v0.1.15 released** — commit `8ba6e72`, tagged, pushed to both remotes
+  (Forgejo `nosignal/deckshift` + GitHub `28allday/deckshift`; the `forgejo`
+  remote pushes to both).
+- v0.1.14 was **skipped**: that label was used by a keybind-change commit
+  (`0844f02`, Super+Shift+S → Super+Shift+G) that was reverted before release.
+- Dev/reference machine: Omarchy 4 desktop (AMD RX 9060 XT), install verified
+  with `./deckshift.sh --verify` — all checks passed, including the two checks
+  added in v0.1.15.
+
+## Omarchy 4 facts that shape this codebase
+
+Discovered during the 2026-07-27 compatibility audit; verify against a live
+system before assuming they still hold.
+
+1. **Hyprland runs on Omarchy's Lua config provider** — `hyprctl systeminfo`
+   reports `configProvider: lua`. Every `~/.config/hypr/*.conf` file
+   (bindings.conf, autostart.conf, windows.conf, ...) is **completely ignored**,
+   even though `hyprland.conf` still contains `source =` lines for them.
+   Proof method: a bind present only in bindings.conf does not appear in
+   `hyprctl binds -j`.
+2. **User override files are Lua**: `~/.config/hypr/bindings.lua`,
+   `autostart.lua`, etc., loaded after Omarchy's defaults. API (defined in
+   `~/.local/share/omarchy/default/hypr/helpers.lua`):
+   - `o.bind("SUPER + SHIFT + S", "Description", "command")`
+   - `hl.unbind("SUPER + SHIFT + S")` — required before rebinding a combo the
+     Omarchy defaults claim; duplicate Hyprland binds BOTH fire.
+   - `o.launch_on_start("command")` — exec-once equivalent (wraps the command
+     with `o.launch()`, i.e. uwsm-app).
+3. **Walker/elephant are gone**: `omarchy-restart-walker` and `elephant` no
+   longer exist (`walker` binary may linger as an orphan). The Quickshell-based
+   omarchy-shell owns the app menu, notifications, and clipboard. The clipboard
+   holder starts fresh with each Hyprland session, so the pre-4 stale-socket
+   clipboard bug (v0.1.5/v0.1.6 fix) cannot recur — that code was removed.
+   `omarchy-restart-shell` exists if a shell bounce is ever needed.
+4. **Still present and safe to depend on**: `omarchy-pkg-add`,
+   `omarchy-hw-nvidia-gsp` / `-without-gsp`, `omarchy-install-gaming-steam`,
+   `uwsm-app`, the `TUI.float` floating-window rule
+   (`default/hypr/apps/system.lua`), `xdg-terminal-exec`.
+
+## Conventions
+
+- **Omarchy-only, not distro-portable** — depend on `omarchy-*` helpers freely;
+  no non-Omarchy fallbacks. (Pre/post-Omarchy-4 *version* branching is fine and
+  used for the bindings/autostart writers.)
+- Lua-first, `.conf` fallback: every Hyprland config write site checks for the
+  `.lua` override file first, falls back to the legacy `.conf`, warns if
+  neither exists. Keep new write sites consistent with this.
+- All config writes are idempotent (grep-before-append). Re-running
+  `./deckshift.sh` on an existing install migrates `.conf` wiring to `.lua`
+  automatically (the stale `.conf` lines are left in place — they're dead
+  files under Omarchy 4).
+- Release flow: bump `DECKSHIFT_VERSION`, README header + changelog entry,
+  commit `vX.Y.Z — summary`, annotated tag, `git push forgejo master &&
+  git push forgejo vX.Y.Z` (covers both remotes).
+
+## Testing checklist for future changes
+
+- `bash -n deckshift.sh bin/deckshift-settings` + `shellcheck -S warning` on
+  both (pre-existing SC2155/SC1090 warnings are known noise).
+- `./deckshift.sh --verify` on the dev box.
+- After touching keybind/autostart wiring: `hyprctl reload` +
+  `hyprctl configerrors` must come back clean, and confirm via
+  `hyprctl binds -j` that the bind is actually live (don't trust file contents
+  — that's exactly how the v0.1.15 bug hid).
+- Full round-trip (enter + return + screen-share + clipboard) when touching
+  anything in switch-to-gaming / gaming-session-switch / portal recovery.
+
+## Open items / ideas
+
+- Real hardware round-trip test of v0.1.15 portal recovery (enter Gaming Mode,
+  return, confirm "Share desktop" works in Chromium) — wiring is verified, the
+  end-to-end path hasn't been re-run since the change.
+- SDDM `Relogin=true` has no backoff: a crash-looping gamescope session
+  respawns several times per second until gamescope-session-plus's 5-strike
+  short-session tracker recovers. Escape hatch from a tty:
+  `sudo /usr/local/bin/gaming-session-switch desktop && sudo systemctl restart sddm`.
+  Worth a proper fix someday.
+- The `--noninteractive` mode sketched for NoSignal OS integration was never
+  committed here; re-implement from scratch if needed.

README.md

@@ -1,15 +1,28 @@
 # DeckShift
 
-**Version 0.1.9** — Steam Deck-style gaming mode for [Omarchy](https://omarchy.com). Press `Super+Shift+S` to enter Gaming Mode (Steam Big Picture in Gamescope), `Super+Shift+R` to return to your desktop.
+**Version 0.1.15** — Steam Deck-style gaming mode for [Omarchy](https://omarchy.com). Press `Super+Shift+S` to enter Gaming Mode (Steam Big Picture in Gamescope), `Super+Shift+R` to return to your desktop.
 
 Lineage: forked from [Super-Shift-S-Omarchy-Deck-Mode](https://git.no-signal.uk/nosignal/Super-Shift-S-Omarchy-Deck-Mode), briefly renamed Omarchy Deck, then renamed DeckShift.
 
-> **Target:** [Omarchy](https://omarchy.com) — Arch + Hyprland + SDDM + Walker. DeckShift depends on Omarchy-specific helpers (`omarchy-pkg-add`, `omarchy-restart-walker`, etc.) and is not intended to be cross-distro.
+> **Target:** [Omarchy](https://omarchy.com) — Arch + Hyprland + SDDM. DeckShift depends on Omarchy-specific helpers (`omarchy-pkg-add`, `omarchy-install-gaming-steam`, etc.) and is not intended to be cross-distro. Omarchy 4 (Quickshell / Lua config) is the primary target; pre-4 installs are still handled via the legacy `.conf` fallbacks.
 
 [![DeckShift demo](https://img.youtube.com/vi/nj4pLh3spCs/maxresdefault.jpg)](https://youtu.be/nj4pLh3spCs)
 
 ## What's New
 
+### v0.1.15 — Omarchy 4 (Quickshell + Lua config) compatibility
+
+Omarchy 4 moved Hyprland onto a Lua config provider (`hyprctl systeminfo` reports `configProvider: lua`) and replaced the Waybar/Walker/Mako desktop stack with the Quickshell-based omarchy-shell. Two things this broke, both fixed:
+
+- **The `Super+Shift+S` keybind never activated on fresh Omarchy 4 installs.** The `*.conf` files under `~/.config/hypr` (including `bindings.conf`, where DeckShift wrote its keybind) are no longer read at all. The installer now writes to `~/.config/hypr/bindings.lua` when it exists — `hl.unbind("SUPER + SHIFT + S")` first (Omarchy's defaults claim that combo, and duplicate Hyprland binds both fire), then `o.bind(...)`. `bindings.conf` remains as a fallback for pre-4 installs.
+- **`deckshift-portal-recovery` silently stopped running after returning from Gaming Mode** — its `exec-once` lived in the now-ignored `autostart.conf`, so the screen-share/portal fix from v0.1.4 was effectively disabled. The installer now wires it via `o.launch_on_start(...)` in `~/.config/hypr/autostart.lua`, with the `autostart.conf` fallback kept for pre-4.
+- `--verify` now checks the Lua files on Omarchy 4 (previously it false-passed against the dead `bindings.conf`) and gained a portal-recovery autostart check.
+- Removed the Walker/elephant integration: `omarchy-restart-walker` and `elephant` no longer exist on Omarchy 4. The elephant `launch_prefix` config step, the Walker refresh after installing the settings launcher, and the clipboard-restart tail of `deckshift-portal-recovery` are all gone. Omarchy 4's shell owns the clipboard and starts fresh with each session, so the stale-clipboard bug those steps fixed can no longer occur. (If you're on pre-4 Omarchy and rely on the clipboard fix, stay on v0.1.13.)
+
+Re-running `./deckshift.sh` on an existing install migrates the keybind and autostart wiring to the Lua files automatically.
+
+*(v0.1.14 was an unreleased keybind change that was reverted; the version number is skipped.)*
+
 ### v0.1.13 — Pacman hook keeps gamescope's cap_sys_nice across upgrades
 
 - Linux file capabilities live as an xattr (`security.capability`) on the inode, so every time pacman replaces `/usr/bin/gamescope` during an upgrade the previously-granted `cap_sys_nice=eip` is silently lost. Performance mode keeps "working" but the compositor thread loses its priority boost — worse frame pacing and input latency, with no error surfaced anywhere.
@@ -94,7 +107,7 @@ Lineage: forked from [Super-Shift-S-Omarchy-Deck-Mode](https://git.no-signal.uk/
 
 ## Settings TUI
 
-After install, launch `DeckShift Settings` from Walker (or run `deckshift-settings` directly) to change Gaming Mode display settings without editing config files:
+After install, launch `DeckShift Settings` from the app menu (`Super+Space`) — or run `deckshift-settings` directly — to change Gaming Mode display settings without editing config files:
 
 | Option | What it sets in `gamescope-session-plus.conf` |
 |---|---|
@@ -142,7 +155,7 @@ chmod +x deckshift.sh
 
 The installer is fully interactive and walks you through each step.
 
-After install, open `DeckShift Settings` from Walker and pick:
+After install, open `DeckShift Settings` from the app menu (`Super+Space`) and pick:
 
 - A monitor
 - A resolution / refresh rate
@@ -157,7 +170,7 @@ Save, then `Super+Shift+S` to launch Gaming Mode.
 | Enter Gaming Mode | `Super + Shift + S` |
 | Return to Desktop | `Super + Shift + R` *(global keybind monitor catches it inside Gamescope)* |
 | Return to Desktop (alternative) | Steam → Power → **Switch to Desktop** |
-| Open settings | Walker → `DeckShift Settings`, or run `deckshift-settings` |
+| Open settings | App menu (`Super+Space`) → `DeckShift Settings`, or run `deckshift-settings` |
 
 ### Command-Line Options
 
@@ -281,14 +294,14 @@ Package installs use Omarchy's `omarchy-pkg-add` (idempotent, double-checks pacm
 | Path | Purpose |
 |---|---|
 | `~/.config/environment.d/gamescope-session-plus.conf` | Gamescope session config (display + GPU keys) — managed via the Settings TUI |
-| `~/.config/hypr/bindings.conf` | Hyprland keybind for `Super+Shift+S` (appended) |
+| `~/.config/hypr/bindings.lua` | Hyprland keybind for `Super+Shift+S` (appended; `bindings.conf` on pre-Omarchy-4) |
 | `~/.cache/deckshift/saved-state` | Pre-Gaming-Mode CPU governor + power profile (created on entry, cleaned up on exit) |
 
 #### Settings TUI
 | Path | Purpose |
 |---|---|
 | `/usr/local/bin/deckshift-settings` | Gum-based TUI for Gaming Mode display + GPU settings |
-| `/usr/share/applications/deckshift-settings.desktop` | Walker launcher (floats via Omarchy's `TUI.float` windowrule) |
+| `/usr/share/applications/deckshift-settings.desktop` | App menu launcher (floats via Omarchy's `TUI.float` windowrule) |
 
 ## How It Works
 
@@ -488,11 +501,11 @@ See [Recovery from a Black Screen](#recovery-from-a-black-screen) for how to get
 - Check PipeWire config exists: `cat /etc/pipewire/pipewire.conf.d/10-gaming-latency.conf`
 - Try lower quantum: edit the config and set `default.clock.min-quantum = 128`
 
-**Screen sharing in Chromium / Firefox is broken after returning from Gaming Mode (only "Share a tab" works) — and/or clipboard is dead**
+**Screen sharing in Chromium / Firefox is broken after returning from Gaming Mode (only "Share a tab" works)**
 
-Both symptoms have the same root cause: `xdg-desktop-portal-hyprland` and Walker's `elephant.service` (the clipboard listener) are still bound to the killed Hyprland instance after the SDDM restart. Tab capture in Chromium works because it bypasses the portal entirely. Clipboard listening, screen capture, and window capture all go through services that need to be reattached to the live compositor.
+Root cause: `xdg-desktop-portal-hyprland` (and the pipewire stack behind it) is still bound to the killed Hyprland instance after the SDDM restart. Tab capture in Chromium works because it bypasses the portal entirely; screen and window capture go through services that need to be reattached to the live compositor. (On pre-4 Omarchy the same stale-socket problem also killed the clipboard via Walker's `elephant.service`; Omarchy 4's shell starts fresh each session, so the clipboard is unaffected there.)
 
-DeckShift handles this automatically via `/usr/local/bin/deckshift-portal-recovery` (autostarted from `~/.config/hypr/autostart.conf`). If you installed before this fix, re-run `./deckshift.sh` to install the helper, or run the recovery manually:
+DeckShift handles this automatically via `/usr/local/bin/deckshift-portal-recovery`, autostarted from `~/.config/hypr/autostart.lua` (Omarchy 4) or `autostart.conf` (pre-4). **If you installed before v0.1.15 and are on Omarchy 4, re-run `./deckshift.sh`** — the old `autostart.conf` wiring is ignored by Omarchy 4's Lua config provider, so the helper never ran. You can also run the recovery manually:
 
 ```bash
 touch /tmp/.deckshift-just-returned && /usr/local/bin/deckshift-portal-recovery
@@ -554,7 +567,7 @@ sudo pkill -f steam-library-mount
 # Remove scripts
 sudo rm -f /usr/local/bin/{switch-to-gaming,switch-to-desktop,gamescope-session-nm-wrapper,\
 gaming-session-switch,gaming-keybind-monitor,gamescope-nm-start,gamescope-nm-stop,\
-steam-library-mount,deckshift-settings}
+steam-library-mount,deckshift-settings,deckshift-portal-recovery}
 sudo rm -f /usr/lib/os-session-select
 sudo rm -rf /usr/local/lib/gamescope-nvidia
 
@@ -570,6 +583,7 @@ sudo rm -f /etc/polkit-1/rules.d/50-gamescope-networkmanager.rules
 sudo rm -f /etc/polkit-1/rules.d/50-udisks-gaming.rules
 sudo rm -f /etc/udev/rules.d/99-gaming-performance.rules
 sudo rm -f /etc/security/limits.d/99-gaming-memlock.conf
+sudo rm -f /usr/share/libalpm/hooks/deckshift-gamescope-cap.hook
 
 # Remove configs
 sudo rm -f /etc/sddm.conf.d/zz-gaming-session.conf
@@ -584,8 +598,13 @@ rm -f ~/.config/environment.d/gamescope-session-plus.conf
 rm -rf ~/.cache/deckshift
 sudo rm -f /usr/share/applications/deckshift-settings.desktop
 
-# Strip the Hyprland keybind line
+# Strip the Hyprland keybind + portal-recovery autostart lines
+# Omarchy 4 (Lua config):
+sed -i '/switch-to-gaming/d; /SUPER + SHIFT + S/d' ~/.config/hypr/bindings.lua
+sed -i '/deckshift-portal-recovery/d' ~/.config/hypr/autostart.lua
+# Pre-4 Omarchy (.conf config):
 sed -i '/switch-to-gaming/d' ~/.config/hypr/bindings.conf
+sed -i '/deckshift-portal-recovery/d' ~/.config/hypr/autostart.conf
 
 # Reload polkit/udev
 sudo systemctl restart polkit

bin/deckshift-settings

@@ -2,7 +2,7 @@
 # ==============================================================================
 # deckshift-settings — Gaming Mode settings TUI
 #
-# Launched from Walker (Super+Space → "DeckShift Settings"). Lets the user
+# Launched from the app menu (Super+Space → "DeckShift Settings"). Lets the user
 # adjust which monitor, GPU, resolution, and refresh rate Gaming Mode uses,
 # without editing ~/.config/environment.d/gamescope-session-plus.conf by hand.
 #

deckshift.sh

@@ -3,13 +3,18 @@
 # DeckShift - Steam Deck Mode for Linux + Hyprland
 #
 # Forked from Super-Shift-S-Omarchy-Deck-Mode (v12.27) → renamed Omarchy Deck →
-# renamed DeckShift. Targets Omarchy (Arch + Hyprland + SDDM + Walker). Extended
-# with:
+# renamed DeckShift. Targets Omarchy (Arch + Hyprland + SDDM). Extended with:
 #   - NVIDIA GSP-aware driver branch selection (legacy 580xx for Pascal/Maxwell)
 #   - omarchy-pkg-add idempotent package installs
 #   - Optional Xbox Bluetooth controller support (xpadneo-dkms)
 #   - Intel GPU support (Iris Xe / Arc / iGPU)
-#   - Settings TUI launched from Walker (deckshift-settings)
+#   - Settings TUI launched from the app menu (deckshift-settings)
+#
+# Omarchy 4 note: Hyprland now runs on Omarchy's Lua config provider — the
+# *.conf files under ~/.config/hypr (bindings.conf, autostart.conf, ...) are
+# NOT read any more. Keybind and autostart wiring below prefers the .lua
+# override files when present and falls back to the legacy .conf files on
+# pre-4 installs.
 #
 # This script transforms an Omarchy (Arch Linux + Hyprland) desktop into a
 # dual-mode system: Desktop Mode (Hyprland) and Gaming Mode (Steam Big Picture
@@ -34,7 +39,7 @@ set -Euo pipefail
 # -u: Treat unset variables as errors (catches typos in variable names)
 # -o pipefail: A pipeline fails if ANY command in it fails, not just the last one
 
-DECKSHIFT_VERSION="0.1.13"
+DECKSHIFT_VERSION="0.1.15"
 
 # Resolve the directory this script lives in so we can find sibling files like
 # bin/deckshift-settings and applications/deckshift-settings.desktop when
@@ -1086,46 +1091,6 @@ EOF
   fi
 }
 
-# Configures the Elephant app launcher (used in Omarchy) to launch desktop
-# applications through uwsm-app. UWSM (Universal Wayland Session Manager)
-# ensures apps are properly associated with the Wayland session, which
-# prevents issues with apps losing track of their display server.
-configure_elephant_launcher() {
-  local cfg="$HOME/.config/elephant/desktopapplications.toml"
-  if [[ ! -f "$cfg" ]]; then
-    return 0
-  fi
-  if ! command -v uwsm-app >/dev/null 2>&1; then
-    return 0
-  fi
-
-  if grep -q '^launch_prefix[[:space:]]*=[[:space:]]*"uwsm-app --"' "$cfg" 2>/dev/null; then
-    return 0
-  fi
-
-  if grep -q '^launch_prefix[[:space:]]*=' "$cfg" 2>/dev/null; then
-    sed -i 's|^launch_prefix[[:space:]]*=.*|launch_prefix = "uwsm-app --"|' "$cfg"
-  else
-    echo 'launch_prefix = "uwsm-app --"' >> "$cfg"
-  fi
-  info "Configured Elephant desktopapplications launch_prefix (uwsm-app)"
-  restart_elephant_walker
-}
-
-# Restarts the Elephant/Walker launcher service so config changes take
-# effect immediately without requiring a logout.
-restart_elephant_walker() {
-  if ! systemctl --user show-environment >/dev/null 2>&1; then
-    return 0
-  fi
-  if command -v omarchy-restart-walker >/dev/null 2>&1; then
-    omarchy-restart-walker >/dev/null 2>&1 || true
-    return 0
-  fi
-  systemctl --user restart elephant.service >/dev/null 2>&1 || true
-  systemctl --user restart app-walker@autostart.service >/dev/null 2>&1 || true
-}
-
 # Installs the core packages that the Gaming Mode scripts themselves need
 # (as opposed to Steam's dependencies which are handled separately).
 # These include:
@@ -1159,7 +1124,6 @@ setup_requirements() {
   setup_performance_permissions
   setup_fcitx_silence
   setup_shader_cache
-  configure_elephant_launcher
 
   if [[ "${PERFORMANCE_MODE,,}" == "enabled" ]] && command -v gamescope >/dev/null 2>&1; then
     local hook_path="/usr/share/libalpm/hooks/deckshift-gamescope-cap.hook"
@@ -1269,11 +1233,11 @@ setup_xbox_controllers() {
   info "Pair controllers with Super+Ctrl+B (Omarchy Bluetooth menu)"
 }
 
-# Install the Gaming Mode settings TUI and its Walker launcher.
+# Install the Gaming Mode settings TUI and its app menu launcher.
 # The TUI lets users pick monitor / GPU / resolution / refresh rate after
 # install without hand-editing ~/.config/environment.d/gamescope-session-plus.conf.
 # The .desktop file uses Omarchy's TUI.float pattern so it pops up as a floating
-# terminal window from Walker (Super+Space → "DeckShift Settings").
+# terminal window from the app menu (Super+Space → "DeckShift Settings").
 setup_settings_tui() {
   echo ""
   echo "================================================================"
@@ -1297,21 +1261,14 @@ setup_settings_tui() {
   info "Installing settings TUI to $tui_dst"
   sudo install -m 0755 "$tui_src" "$tui_dst" || die "Failed to install settings TUI"
 
-  info "Installing Walker launcher to $desktop_dst"
+  info "Installing app launcher entry to $desktop_dst"
   sudo install -m 0644 "$desktop_src" "$desktop_dst" || die "Failed to install desktop entry"
 
   if command -v update-desktop-database >/dev/null 2>&1; then
     sudo update-desktop-database /usr/share/applications 2>/dev/null || true
   fi
 
-  # Refresh Walker so the new entry shows up immediately. omarchy-restart-walker
-  # handles the elephant.service + walker autostart restart for us; without
-  # this, the entry only appears after the next Walker restart / login.
-  if command -v omarchy-restart-walker >/dev/null 2>&1; then
-    omarchy-restart-walker 2>/dev/null || true
-  fi
-
-  info "Settings TUI installed — launch from Walker (Super+Space → 'DeckShift Settings')"
+  info "Settings TUI installed — launch from the app menu (Super+Space → 'DeckShift Settings')"
 }
 
 # ==============================================================================
@@ -1473,7 +1430,7 @@ setup_session_switching() {
   user_home=$(eval echo "~$current_user")
 
   # GPU detection only — the installer no longer chooses a monitor, resolution
-  # or refresh rate. Those are user choices, made later via Walker → "DeckShift
+  # or refresh rate. Those are user choices, made later via the app menu → "DeckShift
   # Settings". This avoids stale OUTPUT_CONNECTOR values when displays are
   # unplugged and lets the user pick whatever fits their setup.
   local -a dgpu_monitors=()
@@ -1532,7 +1489,7 @@ setup_session_switching() {
 
   info "Found $dgpu_type on $dgpu_card"
   info "Display selection (monitor / resolution / refresh) is left to the user."
-  info "After install, launch Walker → 'DeckShift Settings' to configure."
+  info "After install, open the app menu (Super+Space) → 'DeckShift Settings' to configure."
 
   info "Checking for old custom session files to clean up..."
 
@@ -1986,7 +1943,7 @@ UDISKS_POLKIT
   # The installer writes only GPU-specific and static keys here. Display keys
   # (SCREEN_WIDTH, SCREEN_HEIGHT, CUSTOM_REFRESH_RATES, OUTPUT_CONNECTOR) are
   # NOT written by the installer — they are owned by the user and managed via
-  # the settings TUI (Walker → "DeckShift Settings"). This keeps existing user
+  # the settings TUI (app menu → "DeckShift Settings"). This keeps existing user
   # selections intact across re-runs and avoids preselecting values that may
   # not match the user's setup.
   #
@@ -2598,8 +2555,10 @@ KEYBIND_MONITOR
   # screencast portal would bind to nothing. We now (a) push live session
   # env into D-Bus + systemd --user so portals activate against the new
   # Wayland socket, (b) stop portals first, (c) restart pipewire and wait
-  # for the graph, (d) start portals last, (e) restart Walker/elephant so
-  # the clipboard listener reattaches to the live Wayland socket too.
+  # for the graph, (d) start portals last. (Pre-Omarchy-4 versions also
+  # restarted Walker/elephant to reattach the clipboard listener; Omarchy 4's
+  # omarchy-shell owns the clipboard and starts fresh with each session, so
+  # that step is gone.)
   info "Creating portal recovery helper..."
   local portal_recovery="/usr/local/bin/deckshift-portal-recovery"
 
@@ -2634,18 +2593,28 @@ sleep 2
 
 # Now bring portals up cleanly.
 systemctl --user start xdg-desktop-portal-hyprland.service xdg-desktop-portal.service 2>/dev/null || true
-
-# Walker (elephant) holds the clipboard listener, which is also bound to the
-# dead Hyprland's Wayland socket and stays broken until restarted.
-omarchy-restart-walker >/dev/null 2>&1 || true
 PORTAL_RECOVERY
 
   sudo chmod +x "$portal_recovery"
   info "Created $portal_recovery"
 
-  # Hyprland autostart hook for portal recovery
+  # Hyprland autostart hook for portal recovery. Omarchy 4's Lua config
+  # provider ignores autostart.conf, so wire through autostart.lua when it
+  # exists; fall back to the legacy exec-once on pre-4 installs.
+  local hypr_autostart_lua="${user_home}/.config/hypr/autostart.lua"
   local hypr_autostart="${user_home}/.config/hypr/autostart.conf"
-  if [[ -f "$hypr_autostart" ]]; then
+  if [[ -f "$hypr_autostart_lua" ]]; then
+    if grep -q "deckshift-portal-recovery" "$hypr_autostart_lua" 2>/dev/null; then
+      info "Portal recovery already wired into autostart.lua"
+    else
+      sudo -u "$current_user" tee -a "$hypr_autostart_lua" > /dev/null << 'HYPR_PORTAL_LUA'
+
+-- DeckShift — restart xdg-desktop-portal stack after returning from Gaming Mode
+o.launch_on_start("/usr/local/bin/deckshift-portal-recovery")
+HYPR_PORTAL_LUA
+      info "Added portal recovery launch_on_start to $hypr_autostart_lua"
+    fi
+  elif [[ -f "$hypr_autostart" ]]; then
     if grep -q "deckshift-portal-recovery" "$hypr_autostart" 2>/dev/null; then
       info "Portal recovery already wired into autostart.conf"
     else
@@ -2657,8 +2626,8 @@ HYPR_PORTAL
       info "Added portal recovery exec-once to $hypr_autostart"
     fi
   else
-    warn "autostart.conf not found at $hypr_autostart — portal recovery not auto-wired"
-    warn "Add manually: exec-once = /usr/local/bin/deckshift-portal-recovery"
+    warn "No autostart.lua or autostart.conf under ${user_home}/.config/hypr — portal recovery not auto-wired"
+    warn "Add manually to autostart.lua: o.launch_on_start(\"/usr/local/bin/deckshift-portal-recovery\")"
   fi
 
   # SDDM Session Switching Config
@@ -2768,12 +2737,25 @@ SUDOERS_SWITCH
   fi
 
   info "Adding Hyprland keybind..."
+  local hypr_bindings_lua="${user_home}/.config/hypr/bindings.lua"
   local hypr_bindings_conf="${user_home}/.config/hypr/bindings.conf"
 
-  if [[ ! -f "$hypr_bindings_conf" ]]; then
-    warn "bindings.conf not found at $hypr_bindings_conf - skipping keybind setup"
-    warn "You can manually add: bindd = SUPER SHIFT, S, Gaming Mode, exec, /usr/local/bin/switch-to-gaming"
-  else
+  if [[ -f "$hypr_bindings_lua" ]]; then
+    # Omarchy 4: bindings live in Lua; bindings.conf is ignored. Omarchy's
+    # defaults claim SUPER+SHIFT+S, and duplicate Hyprland binds BOTH fire,
+    # so the default must be unbound before taking the key.
+    if grep -q "switch-to-gaming" "$hypr_bindings_lua" 2>/dev/null; then
+      info "Gaming Mode keybind already exists in bindings.lua"
+    else
+      sudo -u "$current_user" tee -a "$hypr_bindings_lua" > /dev/null << 'HYPR_GAMING_LUA'
+
+-- DeckShift — reclaim SUPER+SHIFT+S from the Omarchy default, bind Gaming Mode
+hl.unbind("SUPER + SHIFT + S")
+o.bind("SUPER + SHIFT + S", "Gaming Mode", "/usr/local/bin/switch-to-gaming")
+HYPR_GAMING_LUA
+      info "Added Gaming Mode keybind to bindings.lua"
+    fi
+  elif [[ -f "$hypr_bindings_conf" ]]; then
     if grep -q "switch-to-gaming" "$hypr_bindings_conf" 2>/dev/null; then
       info "Gaming Mode keybind already exists in bindings.conf"
     else
@@ -2783,6 +2765,9 @@ bindd = SUPER SHIFT, S, Gaming Mode, exec, /usr/local/bin/switch-to-gaming
 HYPR_GAMING
       info "Added Gaming Mode keybind to bindings.conf"
     fi
+  else
+    warn "No bindings.lua or bindings.conf under ${user_home}/.config/hypr - skipping keybind setup"
+    warn "Add manually to bindings.lua: o.bind(\"SUPER + SHIFT + S\", \"Gaming Mode\", \"/usr/local/bin/switch-to-gaming\")"
   fi
 
   info "Steam compatibility scripts provided by gamescope-session-steam-git"
@@ -2851,7 +2836,7 @@ HYPR_GAMING
   echo "    - /usr/local/bin/switch-to-gaming"
   echo "    - /usr/local/bin/switch-to-desktop"
   echo "    - /usr/local/bin/gaming-keybind-monitor (Super+Shift+R)"
-  echo "    - ~/.config/hypr/bindings.conf (keybind added)"
+  echo "    - ~/.config/hypr/bindings.lua (keybind added; bindings.conf on pre-Omarchy-4)"
   echo ""
   echo "  NetworkManager integration (Steam network access):"
   echo "    - /usr/local/bin/gamescope-nm-start"
@@ -2941,7 +2926,7 @@ verify_installation() {
     ["/etc/pipewire/pipewire.conf.d/10-gaming-latency.conf"]="644:PipeWire low-latency"
     ["/etc/environment.d/99-shader-cache.conf"]="644:Shader cache config"
     ["/usr/local/bin/deckshift-settings"]="755:Gaming Mode settings TUI"
-    ["/usr/share/applications/deckshift-settings.desktop"]="644:Walker launcher for settings TUI"
+    ["/usr/share/applications/deckshift-settings.desktop"]="644:app menu launcher for settings TUI"
     ["/usr/share/libalpm/hooks/deckshift-gamescope-cap.hook"]="644:Pacman hook re-applies cap_sys_nice on gamescope upgrade (optional)"
   )
   echo "  FILE STATUS:"
@@ -2980,8 +2965,16 @@ verify_installation() {
   echo ""
   echo "  HYPRLAND KEYBIND:"
   echo "  -----------------"
+  local hypr_bindings_lua="$HOME/.config/hypr/bindings.lua"
   local hypr_bindings="$HOME/.config/hypr/bindings.conf"
-  if [[ -f "$hypr_bindings" ]]; then
+  if [[ -f "$hypr_bindings_lua" ]]; then
+    if grep -q "switch-to-gaming" "$hypr_bindings_lua" 2>/dev/null; then
+      echo "  ✓ Gaming Mode keybind (Super+Shift+S) configured in bindings.lua"
+    else
+      echo "  ✗ Gaming Mode keybind NOT found in bindings.lua (Omarchy 4 ignores bindings.conf)"
+      all_ok=false
+    fi
+  elif [[ -f "$hypr_bindings" ]]; then
     if grep -q "switch-to-gaming" "$hypr_bindings" 2>/dev/null; then
       echo "  ✓ Gaming Mode keybind (Super+Shift+S) configured"
     else
@@ -2989,7 +2982,26 @@ verify_installation() {
       all_ok=false
     fi
   else
-    echo "  ⚠ bindings.conf not found - keybind needs manual setup"
+    echo "  ⚠ no bindings.lua or bindings.conf - keybind needs manual setup"
+  fi
+
+  echo ""
+  echo "  PORTAL RECOVERY AUTOSTART:"
+  echo "  --------------------------"
+  local hypr_autostart_lua="$HOME/.config/hypr/autostart.lua"
+  local hypr_autostart="$HOME/.config/hypr/autostart.conf"
+  if [[ -f "$hypr_autostart_lua" ]]; then
+    if grep -q "deckshift-portal-recovery" "$hypr_autostart_lua" 2>/dev/null; then
+      echo "  ✓ portal recovery wired into autostart.lua"
+    else
+      echo "  ✗ portal recovery NOT wired into autostart.lua (Omarchy 4 ignores autostart.conf)"
+      all_ok=false
+    fi
+  elif [[ -f "$hypr_autostart" ]] && grep -q "deckshift-portal-recovery" "$hypr_autostart" 2>/dev/null; then
+    echo "  ✓ portal recovery wired into autostart.conf"
+  else
+    echo "  ✗ portal recovery NOT wired into Hyprland autostart"
+    all_ok=false
   fi
 
   echo ""
@@ -3167,7 +3179,7 @@ verify_installation() {
 #   6. Install script requirements and performance permissions
 #   7. Set up session switching (the big one — all the scripts and configs)
 #   8. Optionally install Xbox Bluetooth controller support (xpadneo)
-#   9. Install the Gaming Mode settings TUI + Walker launcher
+#   9. Install the Gaming Mode settings TUI + app menu launcher
 #  10. Prompt for reboot/relogin if needed
 #  11. Optionally run verification to confirm everything worked
 execute_setup() {