diff --git a/docs/.obsidian/app.json b/docs/.obsidian/app.json index 848887e..cb100c3 100644 --- a/docs/.obsidian/app.json +++ b/docs/.obsidian/app.json @@ -5,7 +5,7 @@ "livePreview": false, "readableLineLength": false, "strictLineBreaks": true, - "propertiesInDocument": "visible", + "propertiesInDocument": "hidden", "showLineNumber": true, "autoPairMarkdown": false, "useTab": false, diff --git a/docs/.obsidian/workspace.json b/docs/.obsidian/workspace.json index cc6f287..35ef82e 100644 --- a/docs/.obsidian/workspace.json +++ b/docs/.obsidian/workspace.json @@ -4,21 +4,21 @@ "type": "split", "children": [ { - "id": "81c4860f495113bf", + "id": "880908ac22302761", "type": "tabs", "children": [ { - "id": "daab69fc3faab88f", + "id": "10ea163afc7dbc62", "type": "leaf", "state": { "type": "markdown", "state": { - "file": "00 INBOX/credits.md", + "file": "TODO.md", "mode": "source", "source": true }, "icon": "lucide-file", - "title": "credits" + "title": "TODO" } } ] @@ -91,7 +91,7 @@ "state": { "type": "localgraph", "state": { - "file": "00 INBOX/credits.md", + "file": "TODO.md", "options": { "collapse-filter": true, "search": "", @@ -217,34 +217,34 @@ "table-editor-obsidian:Advanced Tables Toolbar": false } }, - "active": "daab69fc3faab88f", + "active": "10ea163afc7dbc62", "lastOpenFiles": [ - "00 INBOX/ai/tldr-design.md", + "00 INBOX/ai/adguard-pikachu-migration-design-tree.md", "00 INBOX/ai/caps-escape-design.md", + "03 wrk/tasks/0016-romm-manual-rom-migration.md", + "03 wrk/tasks/0015-romm-5-4-package.md", + "00 INBOX/ai/retroarch-zeus-design-tree.md", + "TODO.md", + "00 INBOX/ai/romm-5-4-deployment-changes-design-tree.md", + "00 INBOX/ai/romm-migration-design-tree.md", + "00 INBOX/ai/romm-5-4-package-design-tree.md", + "00 INBOX/ai/steamvr-quest-3-design-tree.md", "AGENTS.md", + "03 wrk/homelab.md", + "00 INBOX/ai/nixos-agents-style-scope-design-tree.md", + "03 wrk/tasks/0014-romm-guest.md", "00 INBOX/ai/tldr-design-tree.md", + "00 INBOX/ai/tldr-design.md", + "00 INBOX/ai/valheim-items.md", + "03 wrk/tasks/0013-oidc-provider.md", + "03 wrk/tasks/0002-nixos-refactor.md", + "03 wrk/tasks/0011-gitea-axi-rust-migration.md", + "00 INBOX/credits.md", "00 INBOX/ai/grill-skill-design.md", "03 wrk/tasks/0012-gitea-axi-pr-merge-guardrail.md", - "03 wrk/tasks/0011-gitea-axi-rust-migration.md", "00 INBOX/ai/gitea-axi-pr-merge-guardrail.md", "00 INBOX/ai/gitea-axi-rust-migration.md", "00 INBOX/valheim progression.md", - "03 wrk/tasks/0010-fix-main-monitor-detection.md", - "00 INBOX/credits.md", - "03 wrk/tasks/0009-bazel-project-scaffolding.md", - "03 wrk/tasks/0005-rust-cli-scaffolding.md", - "03 wrk/tasks/0008-vim-obsidian-markdown-renderer.md", - "03 wrk/tasks/0002-nixos-refactor.md", - "TODO.md", - "technical-writing.md", - "dictionary.md", - "03 wrk/tasks/0007-obsidian-source-notes.md", - "03 wrk/tasks/0004-dictionary-cli.md", - "03 wrk/tasks/0006-wallpaper-randomizer.md", - "03 wrk/tasks/0003-whisper-dictation.md", - "03 wrk/monorepo.md", - "03 wrk/tasks/0001-todo-cli.md", - "03 wrk/productivity.md", "03 wrk/tasks", "00 INBOX/let order name resolution.md~", "00 INBOX/nix name resolution.md~", diff --git a/docs/00 INBOX/ai/caps-escape-design.md b/docs/00 INBOX/ai/caps-escape-design.md deleted file mode 100644 index ee22e60..0000000 --- a/docs/00 INBOX/ai/caps-escape-design.md +++ /dev/null @@ -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. diff --git a/docs/00 INBOX/ai/retroarch-zeus-design-tree.md b/docs/00 INBOX/ai/retroarch-zeus-design-tree.md new file mode 100644 index 0000000..c0205da --- /dev/null +++ b/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. diff --git a/docs/00 INBOX/ai/romm-5-4-deployment-changes-design-tree.md b/docs/00 INBOX/ai/romm-5-4-deployment-changes-design-tree.md new file mode 100644 index 0000000..9760f17 --- /dev/null +++ b/docs/00 INBOX/ai/romm-5-4-deployment-changes-design-tree.md @@ -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. diff --git a/docs/00 INBOX/ai/steamvr-quest-3-design-tree.md b/docs/00 INBOX/ai/steamvr-quest-3-design-tree.md new file mode 100644 index 0000000..a4243a1 --- /dev/null +++ b/docs/00 INBOX/ai/steamvr-quest-3-design-tree.md @@ -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. diff --git a/docs/03 wrk/homelab.md b/docs/03 wrk/homelab.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/AGENTS.md b/docs/AGENTS.md index e08380f..6bc4cc0 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -1,3 +1,7 @@ +--- +date-created: 2026-10-19 02:39 +date-modified: 2026-10-20 17:45 +--- # Brain Agent Instructions This repository is an Obsidian vault for an execution-focused second brain. @@ -32,6 +36,3 @@ Include negative decisions only when they prevent a likely, harmful, or repeated Remove template instruction text when writing a note from a template. -## Gotchas - - diff --git a/docs/TODO.md b/docs/TODO.md index 6d55af4..88bf037 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -51,11 +51,8 @@ - lidarr (requires raichu) - immich -- romm - gitea - nginxproxymanager (gradual migration to nginx guest) -- adguard - - manage DNS rewrites for local service names such as `home` ## Raichu Proxmox -> Nixos @@ -110,8 +107,3 @@ - Investigate Rust Bazel target structure. Prefer clear per-file dependency edges, but `rust_library` maps each target to a crate. Decide whether wrapper rules or another pattern can improve graph clarity without forcing artificial crate boundaries. - -## Nix Refactor - -Review Nix files in entrypoint order: -