docs/00 INBOX/ai/romm-migration-design-tree.md

@@ -0,0 +1,106 @@
+# RomM migration design tree
+
+## Known facts
+
+- RomM is listed under the Pikachu and Pichu Proxmox migration.
+- Pikachu already runs VLAN 20 guests with persistent storage.
+- Nixpkgs provides a tested `services.romm` module at version 5.2.0.
+- `services.romm.dataDir` defaults to `/var/lib/romm`.
+- RomM stores the game library below `/var/lib/romm/library`.
+- RomM stores saves, states, user-uploaded screenshots, and profile avatars below `/var/lib/romm/assets/users/<user-id>/`.
+- RomM derives `<user-id>` from its database ID, so it is not a stable configured username.
+- RomM stores scraped covers and provider-sourced game screenshots below `/var/lib/romm/resources/roms/<platform-id>/<rom-id>/`.
+- RomM 5.4.0 exists upstream but Nixpkgs does not package it.
+- RomM 5.3.0 requires an explicit library-structure declaration in `config.yml`.
+- The 5.4.0 package phase must add the Structure A declaration for `roms/{platform}/{game}` and `bios/{platform}`.
+- RomM 5.4.0 can modify ROM files in place only when library conversion is explicitly enabled.
+- RomM 5.3.0 identifies hashed ROMs by CRC, MD5, and SHA-1 after a scan.
+- RomM 5.3.0 matches moved or renamed hashed ROMs to their existing database records.
+- This migration is a fresh installation.
+- The new library will receive selected ROMs from the old installation.
+- Copyparty serves `/pikachu/media` as its writable `/media` volume.
+
+## Decision tree
+
+- RomM deployment
+  - Target location
+    - Settled: Deploy a dedicated guest on Pikachu.
+    - Package source
+      - Settled: Start with Nixpkgs's RomM 5.2.0 package.
+      - Settled: Package RomM 5.4.0 locally as follow-up work.
+    - Persistent storage
+      - Settled: Use `/var/lib/romm` in the guest.
+      - Settled: Mount `/pikachu/data/romm` at `/var/lib/romm`.
+      - Settled: Mount the ROM library separately at `/var/lib/romm/library`.
+      - Settled: Mount user assets separately for Copyparty browsing.
+      - Settled: Keep scraped resources in `/pikachu/data/romm`.
+      - Settled: Mount `/pikachu/media/games/emulation/roms` at `/var/lib/romm/library/roms`.
+      - Settled: Mount `/pikachu/media/games/emulation/bios` at `/var/lib/romm/library/bios`.
+      - Settled: Mount `/pikachu/media/games/emulation/users` at `/var/lib/romm/assets/users`.
+      - Settled: Mount `/pikachu/data/romm/postgresql` at `/var/lib/postgresql`.
+      - Settled: Mount `/pikachu/data/romm/redis` at `/var/lib/redis-romm`.
+    - Guest networking
+      - Settled: Follow the standard guest-provisioning protocol, including its VLAN 20 DHCP reservation.
+    - Public route
+      - Settled: Retain the old installation's public domain.
+    - Metadata and authentication secrets
+      - Settled: Configure IGDB, ScreenScraper, and SteamGridDB.
+      - Settled: Use RomM's default metadata and artwork priority.
+      - Settled: Manage the 5.4.0 `config.yml` declaratively with Nix.
+      - Settled: Use RomM's default region and English-language priority.
+    - Save synchronization
+      - Settled: Disable automatic browser save synchronization in 5.4.0.
+    - Authentication
+      - Settled: Use RomM's built-in accounts initially.
+      - Deferred: Configure RomM as an OpenID Connect client after an identity provider exists.
+    - ROM selection and import
+      - Settled: The operator manually selects and copies ROMs after deployment.
+      - Settled: Do not create automatic import tooling or a ROM manifest.
+    - Capacity and service limits
+      - Settled: Limit the guest to `4G` memory, `200%` CPU, and `512` tasks.
+    - Library scanning
+      - Settled: Enable the filesystem watcher for library changes.
+    - Cutover and retirement
+      - Out of scope: The operator manages the old installation and public-domain cutover outside this monorepo.
+  - Work phases
+    - Settled: Create a RomM guest module with Nixpkgs's package in [[0014-romm-guest]].
+    - Settled: Package RomM 5.4.0 locally and reuse `services.romm` in [[0015-romm-5-4-package]].
+    - Settled: Move selected ROMs after the service deployment is ready in [[0016-romm-manual-rom-migration]].
+
+## Settled decisions
+
+- **Migration model:** Start with a fresh RomM installation.
+- **Data scope:** Copy selected ROMs from the old installation.
+- **Old application state:** Do not migrate the database, users, sessions, or job queue.
+- **Deployment target:** Deploy a dedicated guest on Pikachu.
+- **Initial package:** Use Nixpkgs's RomM 5.2.0 package.
+- **Package follow-up:** Package RomM 5.4.0 locally.
+- **Work phases:** Deploy the guest, update the package, then import selected ROMs.
+- **Guest data directory:** Use RomM's default `/var/lib/romm`.
+- **Host application data:** Mount `/pikachu/data/romm` at `/var/lib/romm`.
+- **ROM library:** Mount it separately at `/var/lib/romm/library`.
+- **Storage classification:** Preserve the distinction between application data and browsable media.
+- **User assets:** Mount `/pikachu/media/games/emulation/users` at `/var/lib/romm/assets/users` to expose saves, states, user-uploaded screenshots, and profile avatars through Copyparty.
+- **ROM paths:** Mount `/pikachu/media/games/emulation/roms` and `/pikachu/media/games/emulation/bios` at the corresponding children of `/var/lib/romm/library`.
+- **Guest networking:** Follow the standard guest-provisioning protocol.
+- **Public route:** Retain the old installation's public domain.
+- **Metadata providers:** Configure IGDB, ScreenScraper, and SteamGridDB in both package phases.
+- **Metadata priority:** Use RomM's default metadata and artwork priority.
+- **RomM configuration:** Manage the required 5.4.0 `config.yml` declaratively with Nix.
+- **Scan region and language priority:** Use RomM's defaults.
+- **Initial authentication:** Use RomM's built-in accounts.
+- **OIDC follow-up:** Track it in [[0013-oidc-provider]].
+- **ROM migration:** The operator manually selects and copies ROMs after deployment.
+- **Guest limits:** Cap the guest at `4G` memory, `200%` CPU, and `512` tasks.
+- **Library watcher:** Enable the filesystem watcher.
+- **PostgreSQL:** Mount `/pikachu/data/romm/postgresql` at `/var/lib/postgresql`.
+- **Redis:** Mount `/pikachu/data/romm/redis` at `/var/lib/redis-romm`.
+- **Browser save synchronization:** Disable it in 5.4.0 until browser emulation is needed.
+
+## Frontier
+
+No in-scope decisions remain.
+
+## Next question
+
+None. Present the settled design for confirmation before implementation.

docs/03 wrk/tasks/0013-oidc-provider.md

@@ -0,0 +1,17 @@
+---
+aliases:
+  - "0013"
+  - OIDC Provider
+date-created: 2026-10-19 19:40
+date-modified: 2026-10-19 19:40
+status: open
+area: "[[homelab]]"
+blocked-by: []
+subtasks: []
+---
+
+# OIDC Provider
+
+Deploy an OpenID Connect provider for homelab services.
+
+Configure a RomM client after the provider is available.

docs/03 wrk/tasks/0014-romm-guest.md

@@ -0,0 +1,42 @@
+---
+aliases:
+  - "0014"
+  - RomM Guest
+date-created: 2026-10-19 19:40
+date-modified: 2026-10-19 19:40
+status: open
+area: "[[homelab]]"
+blocked-by: []
+subtasks: []
+---
+
+# RomM Guest
+
+Deploy a dedicated RomM guest on Pikachu with Nixpkgs RomM 5.2.0.
+
+Follow the standard guest-provisioning protocol.
+Keep the old installation's public domain.
+
+Use the local PostgreSQL and Redis instances from `services.romm`.
+Set guest limits to `4G` memory, `200%` CPU, and `512` tasks.
+Enable the library watcher.
+Use RomM built-in accounts.
+
+Mount persistent application data:
+
+```text
+/pikachu/data/romm             -> /var/lib/romm
+/pikachu/data/romm/postgresql  -> /var/lib/postgresql
+/pikachu/data/romm/redis       -> /var/lib/redis-romm
+```
+
+Mount browsable media:
+
+```text
+/pikachu/media/games/emulation/roms  -> /var/lib/romm/library/roms
+/pikachu/media/games/emulation/bios  -> /var/lib/romm/library/bios
+/pikachu/media/games/emulation/users -> /var/lib/romm/assets/users
+```
+
+Configure IGDB, ScreenScraper, and SteamGridDB from secrets.
+Use RomM's default metadata, artwork, region, and language priorities.

docs/03 wrk/tasks/0015-romm-5-4-package.md

@@ -0,0 +1,31 @@
+---
+aliases:
+  - "0015"
+  - RomM 5.4 Package
+date-created: 2026-10-19 19:40
+date-modified: 2026-10-19 19:40
+status: open
+area: "[[homelab]]"
+blocked-by:
+  - "[[0014-romm-guest]]"
+subtasks: []
+---
+
+# RomM 5.4 Package
+
+Package RomM 5.4.0 locally.
+Reuse `services.romm`.
+
+Manage `config.yml` declaratively with Nix.
+Declare the Structure A library layout:
+
+```yaml
+filesystem:
+  structure:
+    default: "roms/{platform}/{game}"
+    firmware: "bios/{platform}"
+```
+
+Keep library conversion disabled.
+Disable automatic browser save synchronization until browser emulation is needed.
+Keep the IGDB, ScreenScraper, and SteamGridDB configuration unchanged.

docs/03 wrk/tasks/0016-romm-manual-rom-migration.md

@@ -0,0 +1,24 @@
+---
+aliases:
+  - "0016"
+  - RomM Manual ROM Migration
+date-created: 2026-10-19 19:40
+date-modified: 2026-10-19 19:40
+status: open
+area: "[[homelab]]"
+blocked-by:
+  - "[[0014-romm-guest]]"
+subtasks: []
+---
+
+# RomM Manual ROM Migration
+
+Manually copy selected ROMs and BIOS files from the old installation.
+
+Copy ROMs to `/pikachu/media/games/emulation/roms`.
+Copy BIOS files to `/pikachu/media/games/emulation/bios`.
+
+Do not migrate the old database, users, sessions, job queue, or other application state.
+Do not add automatic import tooling or a ROM manifest.
+
+This task does not change monorepo configuration.