alexion/dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update homelab plans

Browse Source
This commit is contained in:
alexion
2026-10-21 20:35:18 -04:00
parent 4baafb7094
commit 5cf7109eaf
9 changed files with 343 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/00 INBOX/ai/caps-escape-design.md
View File

@@ -1,39 +0,0 @@
# Caps Escape Design
## Facts
- Commit `250b0b71f` removed `services.xserver.xkb.options` from the shared host module.
- The removed option was `caps:escape_shifted_capslock`.
- That XKB option maps Caps Lock to Escape.
- Shift+Caps Lock still enables Caps Lock.
- The shared host module configures Neogaia, Zeus, and Pikachu.
- Zeus has QMK firmware that provides equivalent keyboard behavior.
- Neogaia and Zeus enable `modules.host.cachyos` and `modules.desktop`.
- Pikachu enables neither module.
- `configs/nixos/hosts/neogaia/default.nix` directly sets Neogaia-specific hardware, networking, desktop application, and Waybar settings.
- The current configuration has no Caps Lock or Escape remapping.
- This session runs on Zeus, not Neogaia.
## Design Tree
- Restore Caps Lock behavior
- Scope the configuration
- Configure Neogaia only. ✓
- Select the mapping behavior.
- Restore `caps:escape_shifted_capslock`. ✓
- Set `services.xserver.xkb.options` in `configs/nixos/hosts/neogaia/default.nix`. ✓
- Define validation for Neogaia.
- Run static checks and manually verify both keys after deployment. ✓
- Stop after source and static validation. ✓
## Settled Decisions
1. Configure the mapping on Neogaia only.
2. Restore `caps:escape_shifted_capslock`.
3. Set `services.xserver.xkb.options` directly in Neogaia's host configuration.
4. Run static checks and manually verify both keys on Neogaia after deployment.
5. Stop after source and static validation.
## Frontier
None.

98
docs/00 INBOX/ai/retroarch-zeus-design-tree.md Normal file
View File

@@ -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.

107
docs/00 INBOX/ai/romm-5-4-deployment-changes-design-tree.md Normal file
View File

@@ -0,0 +1,107 @@
---
date-created: 2026-10-20 19:15
date-modified: 2026-10-20 19:20
---
# RomM 5.4 deployment changes
## Known facts
- The deployed Nixpkgs package is RomM 5.2.0.
- RomM 5.4.0 requires Python 3.14 or later.
- The pinned Nixpkgs contains Python 3.14.
- The pinned Python package set lacks some RomM 5.4.0 dependency versions.
- For example, it provides RQ 2.10 while RomM requires RQ 2.12 or later.
- In this design, upstream means the Nixpkgs repository.
- Nixpkgs upstream still packages RomM 5.2.0.
- Two open Nixpkgs pull requests update RomM to 5.4.0.
- Pull request 574089 adds a required compatibility patch for Nixpkgs Redis 8.0.1.
- Pull request 574089 has not run the NixOS module test.
- The existing `romm` derivation already uses Python 3.14 from the pin.
- The package can override the current derivation without copying it.
- The override evaluates successfully with the RomM 5.4.0 source and frontend hashes.
- RomM reads `config.yml` from `/var/lib/romm/config/config.yml`.
- Systemd tmpfiles `L+` replaces that path with a generated Nix-store symlink.
- NixOS modules use `L+` symlinks for declaratively managed files in persistent application directories.
- The existing Nixpkgs RomM NixOS test starts the application with PostgreSQL, Redis, nginx, and the filesystem watcher in a local VM.
- The test does not deploy to Pikachu.
- The automated update changes only the version, source hash, and frontend dependency hash.
- The manual update also removes a Redis maintenance-notification import and argument.
- RomM does not require the `rom-converto` executable while `ROM_CONVERTO_ENABLED` is false.
- As checked on 2026-10-20, both pull requests remain open.
- Neither pull request has a review or a discussion comment.
- Both pull requests request review from the RomM package maintainers.
- Both pull requests pass evaluation and lint checks.
- Their package-test checks have a neutral result.
- The Darwin package-test jobs remain queued.
- RomM 5.3.0 added a required `filesystem.structure` declaration.
- RomM will not start without that declaration.
- The existing mounts match Structure A.
- Structure A maps ROMs to `roms/{platform}/{game}`.
- Structure A maps firmware to `bios/{platform}`.
- RomM 5.4.0 enables `emulatorjs.auto_save_sync` by default.
- RomM 5.4.0 adds optional in-place library conversion through `rom-converto`.
- Library conversion requires `ROM_CONVERTO_ENABLED=true`.
- Conversion deletes original files after conversion.
- The task requires declarative `config.yml` management.
- The task requires disabled browser save synchronization.
- The task requires disabled library conversion.
- The task retains the IGDB, ScreenScraper, and SteamGridDB configuration.
- The task reuses the Nixpkgs `services.romm` module.
## Sources
- [RomM 5.3.0 release](https://github.com/rommapp/romm/releases/tag/5.3.0)
- [RomM 5.4.0 release](https://github.com/rommapp/romm/releases/tag/5.4.0)
- [RomM 5.4.0 configuration example](https://github.com/rommapp/romm/blob/5.4.0/examples/config.example.yml)
- [RomM 5.4.0 Python requirement](https://github.com/rommapp/romm/blob/5.4.0/pyproject.toml)
- [[0015-romm-5-4-package]]
## Decision tree
- RomM 5.4 deployment
- Package runtime
- Settled: Build the local package with Python 3.14.
- Package source
- Settled: Maintain a local package.
- Constraint: Do not rely on either unreviewed Nixpkgs pull request.
- Package exposure
- Settled: Expose the package as `pkgs.alexion.romm`.
- Library layout
- Settled: Manage `config.yml` declaratively with Nix.
- Configuration materialization
- Settled: Replace the configuration file with a Nix-store symlink on activation.
- Settled: Declare Structure A.
- Settled: Set `filesystem.structure.default` to `roms/{platform}/{game}`.
- Settled: Set `filesystem.structure.firmware` to `bios/{platform}`.
- File safety
- Settled: Keep library conversion disabled.
- Settled: Do not enable `ROM_CONVERTO_ENABLED`.
- Browser emulation
- Settled: Set `emulatorjs.auto_save_sync` to `false`.
- Existing integration
- Settled: Reuse `services.romm`.
- Settled: Keep IGDB, ScreenScraper, and SteamGridDB configuration unchanged.
- Validation
- Settled: Build the local package and the Pikachu configuration.
- Settled: Do not run a local NixOS VM test.
- Settled: The operator validates the deployment on Pikachu.
## Settled decisions
- Build a local RomM 5.4.0 package.
- Do not rely on either unreviewed Nixpkgs pull request.
- Expose the package as `pkgs.alexion.romm`.
- Reuse `services.romm`.
- Generate `config.yml` with Nix.
- Replace `config.yml` with a Nix-store symlink on activation.
- Declare Structure A with `roms/{platform}/{game}` and `bios/{platform}`.
- Keep `ROM_CONVERTO_ENABLED` disabled.
- Set `emulatorjs.auto_save_sync` to `false`.
- Keep IGDB, ScreenScraper, and SteamGridDB configuration unchanged.
- Build the local package and Pikachu configuration.
- Do not run a local NixOS VM test.
- Let the operator validate the deployment on Pikachu.
## Frontier
No in-scope decisions remain.

109
docs/00 INBOX/ai/steamvr-quest-3-design-tree.md Normal file
View File

@@ -0,0 +1,109 @@
---
date-created: 2026-10-20 17:45
date-modified: 2026-10-20 17:52
---
# SteamVR to Meta Quest 3 design tree
## Goal
Stream PCVR from Zeus to a Meta Quest 3.
The design must produce a repeatable and diagnosable SteamVR session.
## Observed facts
- Zeus runs NixOS with a CachyOS kernel.
- Zeus uses an AMD Radeon RX 9070-series GPU with the `amdgpu` driver.
- Zeus runs Hyprland on Wayland.
- Zeus has Steam and Gamescope configured.
- SteamVR 2.17.10 is installed.
- SteamVR includes Valve's Linux `vrlink` driver.
- A previous `vrlink` session detected the Quest 3 and its Touch controllers.
- That session selected 90 Hz from the Quest's 72, 80, 90, and 120 Hz modes.
- SteamVR setup lacks `cap_sys_nice` on `vrcompositor-launcher`.
- NixOS can declare host packages, permissions, services, and diagnostics.
- Steam owns the Quest pairing and SteamVR user settings.
- Zeus connects by Ethernet at `10.23.50.221`.
- The local Wi-Fi scan finds the `Tracion` 5 GHz network at 5220 MHz.
- The scan reports a 1170 Mbit/s link rate.
- The operator has no external tracked devices.
## Decision tree
- **D1: Host platform commitment** — Settled: Linux-native on the current NixOS installation.
- Linux-native on the current NixOS installation.
- **D2: Transport** — Blocked by D1
- Wireless LAN. — Settled: primary transport.
- **D3: Streaming stack** — Settled: SteamVR with its built-in VRLink driver.
- SteamVR with its built-in VRLink driver.
- **D3a: SteamVR acceptance criteria** — Settled: reliable session test.
- Run a SteamVR game for 30 minutes at 90 Hz.
- Verify visuals, audio, and Touch controllers.
- Verify one reconnect.
- ALVR only after SteamVR fails the agreed acceptance criteria.
- **D4: Wi-Fi topology** — Settled: keep the current access point.
- Keep the current access point.
- Add a dedicated access point.
- Use a direct Wi-Fi link.
- **D5: Session performance target** — Settled: selectable refresh-rate profiles.
- Selectable refresh-rate profiles.
- **D5a: Default refresh rate** — Settled: 90 Hz.
- **D5b: Included refresh rates** — Settled: 72, 80, 90, and 120 Hz.
- **D6: Network isolation** — Settled: existing trusted LAN.
- Existing trusted LAN.
- Dedicated VR VLAN or SSID.
- **D7: Controller and tracking scope** — Settled: Quest Touch controllers only.
- Quest Touch controllers only.
- Also support external tracked devices.
- **D8: Launch workflow** — Settled: automatic service and headset connection.
- Start SteamVR when Steam Link connects from the Quest.
- **D9: Diagnostics and recovery** — Settled: capture health checks and logs.
- Capture SteamVR logs and health checks.
- Recover failed sessions manually.
- USB tether.
- **D10: USB streaming stack** — Blocked by D2
- ALVR over USB.
- Meta Quest Link through a Windows installation.
- **D11: USB role** — Blocked by D2
- Primary transport.
- Fallback transport.
- Both wireless LAN and USB tether.
- **D12: Primary transport** — Blocked by D2
- **D13: Fallback behavior** — Blocked by D12
- **D14: System integration** — Settled: hybrid configuration.
- NixOS manages system integration.
- Steam manages Quest pairing and user settings.
- Dual-boot or replace NixOS with Windows.
- **D15: Windows streaming stack** — Blocked by D1
- Steam Link.
- Virtual Desktop.
- Meta Quest Link or Air Link.
- ALVR.
- **D16: Windows installation scope** — Blocked by D1
- Dedicated VR installation.
- General-use Windows installation.
- **D2: Transport** — Blocked by D1
- Keep NixOS and add a separate Windows VR host.
- **D17: Host placement** — Blocked by D1
- **D15: Windows streaming stack** — Blocked by D17
- **D2: Transport** — Blocked by D17
## Frontier
None.
## Settled decisions
- **D1: Host platform commitment** — Linux-native on the current NixOS installation.
- **D2: Transport** — Wireless LAN as the primary transport.
- **D4: Wi-Fi topology** — Keep the current access point.
- **D5: Session performance target** — Selectable profiles at 72, 80, 90, and 120 Hz.
- **D5a: Default refresh rate** — 90 Hz.
- **D5b: Included refresh rates** — 72, 80, 90, and 120 Hz.
- **D6: Network isolation** — Existing trusted LAN.
- **D7: Controller and tracking scope** — Quest Touch controllers only.
- **D3: Streaming stack** — SteamVR with its built-in VRLink driver.
- **D3a: SteamVR acceptance criteria** — 30-minute session at 90 Hz, with visuals, audio, Touch controllers, and one reconnect.
- **D8: Launch workflow** — Start SteamVR when Steam Link connects from the Quest.
- **D9: Diagnostics and recovery** — Capture health checks and logs. Recover failed sessions manually.
- **D14: System integration** — NixOS manages system integration. Steam manages Quest pairing and user settings.