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.