docs: update homelab plans

docs/00 INBOX/ai/retroarch-zeus-design-tree.md

@@ -0,0 +1,98 @@
+---
+date-created: 2026-10-21 08:47
+date-modified: 2026-10-21 09:26
+---
+# RetroArch on Zeus design tree
+
+## Facts
+
+- Zeus is an `x86_64-linux` desktop with AMD graphics, 32-bit graphics support, Bluetooth, Hyprland, and Home Manager.
+- Nixpkgs provides `pkgs.retroarch.withCores` for an explicit set of Libretro cores.
+- Nixpkgs provides `pkgs.retroarch-free` and `pkgs.retroarch-full` for broad core sets.
+- The packaged RetroArch version is 1.22.2 and includes Cloud Sync on Linux.
+- Linux Cloud Sync uses a WebDAV endpoint.
+- RomM requires RetroArch 1.22 or newer for this integration.
+- RomM documents configuration synchronization as part of its Cloud Sync setup.
+- Cloud Sync supports saves, configuration, thumbnails, and system files as separate categories.
+- RomM matches a save or state to a ROM by its file name without the extension.
+- Local ROM files must use the same names as their RomM library records.
+- RomM 5.4 provides a WebDAV endpoint for RetroArch Cloud Sync.
+- The endpoint is `https://games.alexion.dev/api/sync/retroarch/`.
+- RomM stores its ROMs and BIOS files on Pikachu.
+
+## Constraints
+
+- Install RetroArch on Zeus.
+- Start with PlayStation and Sega Saturn cores.
+- Evaluate RetroArch Cloud Sync.
+- Keep package selection declarative.
+- Keep credentials out of the Nix store and version control.
+
+## Decision tree
+
+- D1 — Initial core selection [settled]
+  - Use `beetle-psx-hw` for PlayStation.
+  - Use `beetle-saturn` for Sega Saturn.
+  - D4 — Core package viability [settled]
+    - Both core packages support `x86_64-linux`.
+    - Neither package is marked broken or unfree.
+  - D5 — Package composition [settled]
+    - Build a RetroArch wrapper with `beetle-psx-hw` and `beetle-saturn` only.
+- D2 — Cloud Sync data scope [settled]
+  - Sync saves, states, and configuration.
+  - Do not sync thumbnails or system files.
+  - D6 — Sync endpoint [settled]
+    - Use RomM's RetroArch WebDAV endpoint.
+  - D7 — Sync identity [settled]
+    - Use the existing RomM account.
+    - D15 — Credential injection [settled]
+      - Store the RomM password in RetroArch's writable user configuration.
+  - D8 — Synchronization mode [settled]
+    - Synchronize automatically at startup and after play sessions.
+    - D16 — Launch order [settled]
+      - Do not add a game-launching frontend.
+      - Start RetroArch before loading local ROM content.
+  - D9 — Conflict and destructive-sync policy [settled]
+    - Use non-destructive synchronization.
+    - RetroArch backs up a local file when RomM reports its deletion.
+- D3 — ROM and firmware access [settled]
+  - Keep ROMs and BIOS files locally on Zeus.
+  - D10 — Mount or replication method [settled]
+    - Do not configure a remote mount or replication method.
+  - D11 — RetroArch directory settings [settled]
+    - Use `~/.local/share/retroarch/`.
+    - Use `roms/`, `system/`, `saves/`, and `states/` subdirectories.
+    - Keep saves and states outside the content directory.
+    - Sort saves and states into per-core folders.
+- D12 — User-configuration policy [settled]
+  - Nix declares the package, cores, and directory defaults.
+  - RetroArch manages and synchronizes its writable configuration.
+- D13 — User-facing integration [settled]
+  - Do not add a user-facing integration beyond RetroArch's desktop entry.
+- D14 — Validation [settled]
+  - Verify the NixOS evaluation and a manual Cloud Sync round trip.
+
+## Frontier
+
+No decisions remain open.
+
+## Decision log
+
+- D13: Do not add a user-facing integration beyond RetroArch's desktop entry.
+- D16: Do not add a game-launching frontend. Start RetroArch before loading local ROM content.
+- D14: Verify the NixOS evaluation and a manual Cloud Sync round trip.
+- D12: Nix declares the package, cores, and directory defaults. RetroArch manages and synchronizes its writable configuration.
+- D11: Use `~/.local/share/retroarch/` with `roms/`, `system/`, `saves/`, and `states/` subdirectories.
+- D9: Use non-destructive synchronization.
+- D8: Synchronize automatically at startup and after play sessions.
+- D15: Store the RomM password in RetroArch's writable user configuration.
+- D5: Build a RetroArch wrapper with `beetle-psx-hw` and `beetle-saturn` only.
+- D3: Keep ROMs and BIOS files locally on Zeus.
+- D10: Do not configure a remote mount or replication method.
+- D7: Use the existing RomM account.
+- D7 note: RomM accepts API client tokens as Bearer authentication. RetroArch Cloud Sync only supports WebDAV Basic authentication.
+- D6: Use RomM's RetroArch WebDAV endpoint.
+- D2: Sync saves, states, and configuration. Do not sync thumbnails or system files.
+- D11: Keep saves and states outside the content directory. Sort them into per-core folders.
+- D1: Use `beetle-psx-hw` for PlayStation and `beetle-saturn` for Sega Saturn.
+- D4: Both selected core packages support Zeus and have no broken or unfree package status.