docs: update homelab plans

configs/nixos/AGENTS.md

@@ -1,70 +0,0 @@
-# NixOS configuration instructions
-
-## Desktop
-
-- When adding a graphical application, register its workspace icon in `registry.window-icon`.
-  The workspace indicator uses this mapping to show an application icon instead of the generic default glyph.
-  Match the mapping on the window class.
-  Store the icon as the rendered string.
-  Run `hyprctl clients -j | jq -r '.[].class' | sort -u` to list classes in the running session.
-- TODO: Verify this path after the NixOS configuration is migrated.
-  Set Hyprland session environment variables in `modules/desktop/session/hyprland/default.nix` with `env = KEY,VALUE`.
-  `home.sessionVariables` do **not** reach the Hyprland session because UWSM does not source `hm-session-vars.sh`.
-  Source cursor values from `config.stylix.cursor`.
-  Set `XCURSOR_*` and `HYPRCURSOR_*` to the same theme for Bibata.
-
-## Firefox
-
-- Manage Firefox search engines through `programs.firefox.search` with `force = true`.
-  Hide built-in engines with `<engine>.metaData.hidden = true` because omission does not remove them.
-  Use current engine ids, such as `default = "ddg"` instead of `"DuckDuckGo"`.
-  Decode the built `search.json.mozlz4` with `mozlz4a -d <search.json.mozlz4>` to check the result.
-- Avoid Home Manager Firefox extension settings unless the whole profile can use the legacy extension-storage backend.
-  Any non-empty `profiles.<name>.extensions.settings.<id>.settings` sets `extensions.webextensions.ExtensionStorageIDB.enabled = false` for the whole profile.
-
-## Neovim
-
-- Nixvim's flake input follows the root nixpkgs source, but its Home Manager module does not reuse the host's `pkgs` instance.
-  Keep `programs.nixvim.nixpkgs.useGlobalPackages = true`.
-  That setting makes Nixvim use the shared package set without warning that its source default changed.
-
-## AI tooling
-
-- Use produced literals for Herdr key names that include shifted punctuation.
-  For example, use `prefix+<` instead of `prefix+shift+comma`.
-- Put monorepo Pi extension sources in `.pi/extensions/`.
-  Pi discovers them from subdirectories through the local ancestor-resource patch.
-- Treat Home Manager-managed Pi settings as generated output.
-  Do not edit them except for throwaway development or local experiments.
-  Promote finished settings into the NixOS configuration before treating them as deployed.
-
-## Gotchas
-
-- `configs/nixos/registry/stable-uid.nix` receives library functions through `lib`.
-  Qualify its library calls with `lib.`.
-- Guest modules are host-agnostic wiring, while host files own deployment-specific service configuration such as served volumes and host paths.
-  For example, `guests/copyparty.nix` should expose options and translate them into guest mounts/service settings, while `hosts/pikachu/default.nix` chooses `/inbox`, `/media`, and their backing paths.
-  Guest addresses and routes are host-level configuration because a guest module can be used on multiple hosts.
-- `sops.secrets.<name>.owner` must name a user known on the decrypting host.
-  Do not set the owner to a guest-only service user unless the host also declares that user.
-  Use a host-visible owner plus a shared group mode when the guest service can read the decrypted secret file through its group.
-- A read-only guest bind mount cannot contain nested writable bind mounts unless their mount-point
-  directories already exist inside the read-only source.
-  For aggregate Copyparty volumes such as `/srv` with nested `/srv/inbox`, keep the guest bind mount
-  writable and enforce read-only behavior through Copyparty access plus service `ReadWritePaths`.
-- `deploy-to` builds from the source checkout, records the imported closure as the target system profile,
-  and activates it. Do not rely on a target-local monorepo checkout for remote deployment.
-- On Pikachu, `nix copy --to ssh://pikachu` accepted a small `nix store add-file` probe,
-  but rejected locally built system paths that lacked trusted signatures.
-  Use a sudo `nix-store --import` path for unsigned deploy closures.
-- Public DNS entries are not managed through the NixOS configuration.
-  Do not describe NixOS route choices as public-DNS management.
-- Do not hand-author `hardware-configuration.nix` for a host that has not been generated on that machine.
-  Generate it on the target system or live ISO, then stage it before evaluating the flake.
-- Configure the Chaotic Nyx cache only on hosts that select `linuxPackages_cachyos` (currently Neogaia
-  and Zeus), not in the generic host module.
-- Module-relative paths resolve from the module file. Update them when moving a module into a subdirectory.
-- On Pikachu, `uptime` does not support `-s`. Use `who -b` to report the boot time.
-- Evaluating a NixOS guest's inner `config.services.nginx` can force incomplete ACME values.
-  Evaluate the parent host's `config.system.build.toplevel` to validate an ACME-enabled guest.
-- `pkgs.systemd` does not set `meta.mainProgram`. Use `lib.getExe' pkgs.systemd "systemctl"` instead of `lib.getExe pkgs.systemd`.

configs/nixos/guests/adguard.nix

@@ -0,0 +1,51 @@
+{
+  config,
+  lib,
+  registry,
+  ...
+}:
+let
+  cfg = config.guests.adguard;
+in
+{
+  options.guests.adguard.adminPasswordHash = lib.mkOption {
+    type = lib.types.str;
+    description = "Bcrypt verifier for the AdGuard Home administrator password.";
+  };
+
+  config = lib.mkIf cfg.enable {
+    assertions = [
+      {
+        assertion = cfg.address != null;
+        message = "guests.adguard.address must identify the AdGuard Home guest.";
+      }
+    ];
+
+    registry.homepage.${config.networking.hostName}.adguard = {
+      tab = "System";
+      section = "Network";
+      name = "AdGuard Home";
+      description = "Internal DNS";
+      icon = "adguard-home.svg";
+      href = "http://${cfg.address}";
+    };
+
+    guests.adguard = {
+      interior = {
+        modules.services.adguardhome = {
+          enable = true;
+          inherit (cfg) adminPasswordHash;
+          reverseProxyAddress = registry.address.${config.networking.hostName}."reverse-proxy";
+        };
+
+        services.resolved.settings.Resolve.DNSStubListener = false;
+      };
+
+      limits = {
+        memory = lib.mkDefault "256M";
+        cpu = lib.mkDefault "100%";
+        tasksMax = lib.mkDefault 128;
+      };
+    };
+  };
+}

configs/nixos/guests/romm.nix

@@ -94,6 +94,14 @@ in
           }
         ];
 
+    registry.homepage.${config.networking.hostName}.romm = {
+      tab = "Apps";
+      section = "Media";
+      name = "RomM";
+      description = "Games";
+      icon = "romm.png";
+    };
+
     guests.romm = {
       interior = {
         modules.services.romm.enable = true;

configs/nixos/hosts/neogaia/default.nix

@@ -40,7 +40,6 @@
   modules.desktop.enable = true;
   modules.desktop.apps.firefox.uiScale = "1.25";
   modules.desktop.apps.obsidian.enable = true;
-  modules.desktop.apps.steam.enable = true;
 
   registry.waybar.neogaia.battery = {
     order = 70;

configs/nixos/hosts/pikachu/default.nix

@@ -29,6 +29,14 @@
 
   registry.address.pikachu.self = "10.23.10.102";
 
+  guests.adguard = {
+    enable = true;
+    vlan = 20;
+    mac = "bc:24:11:91:60:bf";
+    address = "10.23.20.33";
+    adminPasswordHash = "$2b$12$wariglnrCvJOnh4b8KnB9eDX4RdQRaaTZtyXMUOilaYSn7xTR0g1e";
+  };
+
   guests.valheim = {
     enable = true;
     vlan = 20;
@@ -104,6 +112,7 @@
         domain = "games.alexion.dev";
         protocol = "https";
         port = 80;
+        clientMaxBodySize = "0";
       };
     };
   };

configs/nixos/hosts/zeus/default.nix

@@ -44,9 +44,10 @@
   modules.desktop.enable = true;
   modules.desktop.apps.obsidian.enable = true;
   modules.desktop.apps.r2modman.enable = true;
+  modules.desktop.emulation.enable = true;
   modules.desktop.apps.signal.enable = true;
   modules.desktop.apps.steam.enable = true;
-  modules.desktop.apps.vencord.enable = true;
+  modules.desktop.apps.discord.enable = true;
 
   home-manager.users.${config.user.name}.wayland.windowManager.hyprland.settings.monitor = [
     {

configs/nixos/modules/desktop/apps/discord.nix

@@ -0,0 +1,23 @@
+{
+  config,
+  lib,
+  pkgs,
+  util,
+  ...
+}:
+# Official Discord provides chat, voice, and screen sharing.
+let
+  user = config.user.name;
+in
+{
+  options.modules.desktop.apps.discord.enable = lib.mkEnableOption "official Discord";
+
+  config = lib.mkIf config.modules.desktop.apps.discord.enable {
+    home-manager.users.${user}.home.packages = [ pkgs.discord ];
+
+    registry.window-icon.${config.networking.hostName}.discord = {
+      class = "[Dd]iscord";
+      icon = util.glyph "f1ff";
+    };
+  };
+}

configs/nixos/modules/desktop/apps/firefox.nix

@@ -67,6 +67,8 @@ in
 
           # Stylix uses a near-white selection background.
           # Use the Nord selection color because its text stays readable.
+          # Home Manager writes extension settings through Firefox's legacy storage backend.
+          # Extension settings disable `ExtensionStorageIDB` for the whole profile.
           extensions.settings."FirefoxColor@mozilla.com".settings.theme.colors.popup_highlight =
             let
               c = hm.config.lib.stylix.colors;

configs/nixos/modules/desktop/apps/steam.nix

@@ -14,6 +14,7 @@
 
     programs.steam = {
       enable = true;
+      remotePlay.openFirewall = true;
       package = pkgs.steam.override {
         extraEnv.STEAM_FORCE_DESKTOPUI_SCALING = "1.5";
       };
@@ -21,9 +22,10 @@
 
     hardware.steam-hardware.enable = true;
 
-    environment.systemPackages = [
-      pkgs.gamescope
-    ];
+    programs.gamescope = {
+      enable = true;
+      capSysNice = true;
+    };
 
     registry.window-icon.${config.networking.hostName}.steam = {
       class = "[Ss]team";

configs/nixos/modules/desktop/apps/vencord.nix

@@ -1,24 +0,0 @@
-{
-  config,
-  lib,
-  pkgs,
-  util,
-  ...
-}:
-# Vesktop, a Discord client with Vencord built in.
-let
-  user = config.user.name;
-in
-{
-  options.modules.desktop.apps.vencord.enable =
-    lib.mkEnableOption "Vesktop, a Discord client with Vencord built in";
-
-  config = lib.mkIf config.modules.desktop.apps.vencord.enable {
-    home-manager.users.${user}.home.packages = [ pkgs.vesktop ];
-
-    registry.window-icon.${config.networking.hostName}.vesktop = {
-      class = "[Vv]esktop";
-      icon = util.glyph "f1ff";
-    };
-  };
-}

configs/nixos/modules/desktop/emulation.nix

@@ -0,0 +1,36 @@
+{
+  config,
+  lib,
+  ...
+}:
+# Shared directories for emulators.
+let
+  user = config.user.name;
+  directory = "/home/${user}/emulation";
+in
+{
+  options.modules.desktop.emulation.enable = lib.mkEnableOption "shared emulation directories";
+
+  config = lib.mkIf config.modules.desktop.emulation.enable {
+    modules.desktop.emulation.retroarch = {
+      enable = lib.mkDefault true;
+      browserDirectory = "${directory}/roms";
+    };
+
+    home-manager.users.${user} = hm: {
+      home.file = {
+        ".config/retroarch/saves".source = hm.config.lib.file.mkOutOfStoreSymlink "${directory}/saves";
+        ".config/retroarch/states".source = hm.config.lib.file.mkOutOfStoreSymlink "${directory}/states";
+        ".config/retroarch/system".source = hm.config.lib.file.mkOutOfStoreSymlink "${directory}/bios";
+      };
+
+      systemd.user.tmpfiles.rules = map (path: "d ${path} 0700 - - -") [
+        directory
+        "${directory}/bios"
+        "${directory}/roms"
+        "${directory}/saves"
+        "${directory}/states"
+      ];
+    };
+  };
+}

configs/nixos/modules/desktop/emulation/retroarch.nix

@@ -0,0 +1,62 @@
+{
+  config,
+  lib,
+  pkgs,
+  util,
+  ...
+}:
+# RetroArch with the selected PlayStation and Sega Saturn cores.
+let
+  cfg = config.modules.desktop.emulation.retroarch;
+  user = config.user.name;
+in
+{
+  options.modules.desktop.emulation.retroarch = {
+    enable = lib.mkEnableOption "RetroArch with PlayStation and Sega Saturn cores";
+
+    browserDirectory = lib.mkOption {
+      type = lib.types.str;
+      default = "";
+      description = "Directory where RetroArch starts its content browser.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    home-manager.users.${user} = {
+      home.packages = [
+        (pkgs.wrapRetroArch {
+          cores = with pkgs.libretro; [
+            beetle-psx-hw
+            beetle-saturn
+          ];
+          settings = {
+            savefiles_in_content_dir = "false";
+            savestates_in_content_dir = "false";
+            system_directory = "/home/${user}/.config/retroarch/system";
+            video_fullscreen = "true";
+            sort_savefiles_enable = "true";
+            sort_savestates_enable = "true";
+            cloud_sync_enable = "true";
+            cloud_sync_driver = "webdav";
+            webdav_url = "https://games.alexion.dev/api/sync/retroarch/";
+            cloud_sync_sync_saves = "true";
+            cloud_sync_sync_configs = "true";
+            cloud_sync_sync_thumbs = "false";
+            cloud_sync_sync_system = "false";
+            cloud_sync_sync_mode = "0";
+            cloud_sync_destructive = "false";
+          }
+          // lib.optionalAttrs (cfg.browserDirectory != "") {
+            rgui_browser_directory = cfg.browserDirectory;
+          };
+        })
+      ];
+
+    };
+
+    registry.window-icon.${config.networking.hostName}.retroarch = {
+      class = "com.libretro.RetroArch";
+      icon = util.glyph "f11b";
+    };
+  };
+}

configs/nixos/modules/services/adguardhome.nix

@@ -0,0 +1,277 @@
+{ config, lib, ... }:
+let
+  cfg = config.modules.services.adguardhome;
+in
+{
+  options.modules.services.adguardhome = {
+    enable = lib.mkEnableOption "AdGuard Home";
+
+    adminPasswordHash = lib.mkOption {
+      type = lib.types.str;
+      description = "Bcrypt verifier for the AdGuard Home administrator password.";
+    };
+
+    reverseProxyAddress = lib.mkOption {
+      type = lib.types.str;
+      description = "IP address of the guest that handles internal HTTP requests.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    services.adguardhome = {
+      enable = true;
+      mutableSettings = false;
+      openFirewall = true;
+      settings = {
+        http = {
+          pprof = {
+            port = 6060;
+            enabled = false;
+          };
+          address = "0.0.0.0:80";
+          session_ttl = "720h";
+        };
+        users = [
+          {
+            name = config.user.name;
+            password = cfg.adminPasswordHash;
+          }
+        ];
+        auth_attempts = 5;
+        block_auth_min = 15;
+        http_proxy = "";
+        language = "";
+        theme = "auto";
+
+        dns = {
+          bind_hosts = [ "0.0.0.0" ];
+          port = 53;
+          anonymize_client_ip = false;
+          ratelimit = 20;
+          ratelimit_subnet_len_ipv4 = 24;
+          ratelimit_subnet_len_ipv6 = 56;
+          ratelimit_whitelist = [ ];
+          refuse_any = true;
+          upstream_dns = [
+            "https://dns.cloudflare.com/dns-query"
+            "tls://1.1.1.1"
+            "https://dns.google/dns-query"
+            "tls://8.8.8.8"
+            "https://dns10.quad9.net/dns-query"
+            "tls://9.9.9.9"
+          ];
+          upstream_dns_file = "";
+          bootstrap_dns = [
+            "9.9.9.10"
+            "149.112.112.10"
+            "2620:fe::10"
+            "2620:fe::fe:10"
+          ];
+          fallback_dns = [ ];
+          upstream_mode = "parallel";
+          fastest_timeout = "1s";
+          allowed_clients = [ ];
+          disallowed_clients = [ ];
+          blocked_hosts = [
+            "version.bind"
+            "id.server"
+            "hostname.bind"
+          ];
+          trusted_proxies = [
+            "127.0.0.0/8"
+            "::1/128"
+          ];
+          cache_enabled = true;
+          cache_size = 4194304;
+          cache_ttl_min = 0;
+          cache_ttl_max = 0;
+          cache_optimistic = false;
+          cache_optimistic_answer_ttl = "30s";
+          cache_optimistic_max_age = "12h";
+          bogus_nxdomain = [ ];
+          aaaa_disabled = false;
+          enable_dnssec = false;
+          edns_client_subnet = {
+            custom_ip = "";
+            enabled = false;
+            use_custom = false;
+          };
+          max_goroutines = 300;
+          handle_ddr = true;
+          ipset = [ ];
+          ipset_file = "";
+          bootstrap_prefer_ipv6 = false;
+          upstream_timeout = "10s";
+          private_networks = [ ];
+          use_private_ptr_resolvers = true;
+          local_ptr_upstreams = [ ];
+          use_dns64 = false;
+          dns64_prefixes = [ ];
+          serve_http3 = false;
+          use_http3_upstreams = false;
+          serve_plain_dns = true;
+          hostsfile_enabled = true;
+          pending_requests.enabled = true;
+        };
+
+        tls = {
+          enabled = false;
+          server_name = "";
+          force_https = false;
+          port_https = 443;
+          port_dns_over_tls = 853;
+          port_dns_over_quic = 853;
+          port_dnscrypt = 0;
+          dnscrypt_config_file = "";
+          allow_unencrypted_doh = false;
+          certificate_chain = "";
+          private_key = "";
+          certificate_path = "";
+          private_key_path = "";
+          strict_sni_check = false;
+        };
+
+        querylog = {
+          dir_path = "";
+          ignored = [ ];
+          interval = "2160h";
+          size_memory = 1000;
+          enabled = true;
+          ignored_enabled = false;
+          file_enabled = true;
+        };
+
+        statistics = {
+          dir_path = "";
+          ignored = [ ];
+          interval = "24h";
+          enabled = true;
+          ignored_enabled = false;
+        };
+
+        filters = [
+          {
+            enabled = true;
+            url = "https://adguardteam.github.io/HostlistsRegistry/assets/filter_1.txt";
+            name = "AdGuard DNS filter";
+            id = 1;
+          }
+          {
+            enabled = false;
+            url = "https://adguardteam.github.io/HostlistsRegistry/assets/filter_2.txt";
+            name = "AdAway Default Blocklist";
+            id = 2;
+          }
+        ];
+        whitelist_filters = [ ];
+        user_rules = [ ];
+
+        dhcp = {
+          enabled = false;
+          interface_name = "";
+          local_domain_name = "lan";
+          dhcpv4 = {
+            gateway_ip = "";
+            subnet_mask = "";
+            range_start = "";
+            range_end = "";
+            lease_duration = 86400;
+            icmp_timeout_msec = 1000;
+            options = [ ];
+          };
+          dhcpv6 = {
+            range_start = "";
+            lease_duration = 86400;
+            ra_slaac_only = false;
+            ra_allow_slaac = false;
+          };
+        };
+
+        filtering = {
+          blocking_ipv4 = "";
+          blocking_ipv6 = "";
+          blocked_services = {
+            schedule.time_zone = "Local";
+            ids = [ ];
+          };
+          protection_disabled_until = null;
+          safe_search = {
+            enabled = false;
+            bing = true;
+            duckduckgo = true;
+            ecosia = true;
+            google = true;
+            pixabay = true;
+            yandex = true;
+            youtube = true;
+          };
+          blocking_mode = "default";
+          parental_block_host = "family-block.dns.adguard.com";
+          safebrowsing_block_host = "standard-block.dns.adguard.com";
+          rewrites = [
+            {
+              domain = "*.home";
+              answer = "10.23.20.32";
+              enabled = true;
+            }
+            {
+              domain = "*.alexion.dev";
+              answer = cfg.reverseProxyAddress;
+              enabled = true;
+            }
+            {
+              domain = "home";
+              answer = cfg.reverseProxyAddress;
+              enabled = true;
+            }
+          ];
+          safe_fs_patterns = [ "/opt/AdGuardHome/userfilters/*" ];
+          safebrowsing_cache_size = 1048576;
+          safesearch_cache_size = 1048576;
+          parental_cache_size = 1048576;
+          cache_time = 30;
+          filters_update_interval = 24;
+          blocked_response_ttl = 10;
+          filtering_enabled = true;
+          rewrites_enabled = true;
+          parental_enabled = false;
+          safebrowsing_enabled = false;
+          protection_enabled = true;
+        };
+
+        clients = {
+          runtime_sources = {
+            whois = true;
+            arp = true;
+            rdns = true;
+            dhcp = true;
+            hosts = true;
+          };
+          persistent = [ ];
+        };
+
+        log = {
+          enabled = true;
+          file = "";
+          max_backups = 0;
+          max_size = 100;
+          max_age = 3;
+          compress = false;
+          local_time = false;
+          verbose = false;
+        };
+
+        os = {
+          group = "";
+          user = "";
+          rlimit_nofile = 0;
+        };
+      };
+    };
+
+    networking.firewall = {
+      allowedTCPPorts = [ 53 ];
+      allowedUDPPorts = [ 53 ];
+    };
+  };
+}

configs/nixos/modules/services/reverse-proxy.nix

@@ -71,7 +71,10 @@ let
         extraConfig = lib.optionalString (route.clientMaxBodySize != null) ''
           client_max_body_size ${route.clientMaxBodySize};
         '';
-        locations."/".proxyPass = mkBackend address port;
+        locations."/" = {
+          proxyPass = mkBackend address port;
+          proxyWebsockets = true;
+        };
       };
     };
 

configs/nixos/modules/services/romm.nix

@@ -1,6 +1,7 @@
 {
   config,
   lib,
+  pkgs,
   ...
 }:
 let
@@ -31,13 +32,33 @@ in
 
       services.romm = {
         enable = true;
+        package = pkgs.alexion.romm;
         group = "storage";
         database.createLocally = true;
         redis.createLocally = true;
         watcher.enable = true;
+        extraEnvironment = {
+          HASHEOUS_API_ENABLED = "true";
+          PLAYMATCH_API_ENABLED = "true";
+          ROM_CONVERTO_ENABLED = "false";
+        };
         inherit (cfg) environmentFile;
       };
 
+      systemd.services.romm-worker.serviceConfig.ExecStart =
+        lib.mkForce "${lib.getExe' config.services.romm.package "romm-worker"} scans";
+
+      systemd.tmpfiles.settings."10-romm"."${config.services.romm.dataDir}/config/config.yml"."L+".argument =
+        toString (
+          (pkgs.formats.yaml { }).generate "romm-config.yml" {
+            emulatorjs.auto_save_sync = false;
+            filesystem.structure = {
+              default = "roms/{platform}/{game}";
+              firmware = "bios/{platform}";
+            };
+          }
+        );
+
       users.users = {
         romm.uid = config.registry."stable-uid".${config.networking.hostName}.romm;
         redis-romm.uid = config.registry."stable-uid".${config.networking.hostName}."redis-romm";

configs/nixos/modules/shell/fish/functions/deploy-to.fish

@@ -47,6 +47,8 @@ or begin
     return $status
 end
 
+set remote_nar
+
 if test (count $missing_paths) -gt 0
     set nar_file (mktemp --suffix=.nar)
     or return $status
@@ -70,26 +72,23 @@ if test (count $missing_paths) -gt 0
         return $scp_status
     end
 
-    echo "deploy-to: importing closure on $host" >&2
-    ssh -t $host "sudo sh -c 'nix-store --import < $remote_nar' && rm -f $remote_nar"
-    or begin
-        echo "deploy-to: closure import failed for $host" >&2
-        return $status
-    end
+    echo "deploy-to: importing the closure, recording $system_path, and activating it on $host" >&2
 else
     echo "deploy-to: $host already has the full closure for $system_path" >&2
+    echo "deploy-to: recording $system_path and activating it on $host" >&2
 end
 
-echo "deploy-to: recording $system_path as the system profile on $host" >&2
-ssh -t $host sudo nix-env --profile /nix/var/nix/profiles/system --set $system_path
-or begin
-    echo "deploy-to: system profile update failed for $host" >&2
-    return $status
-end
+set remote_script (
+    string join '; ' \
+        'system_path=$1' \
+        'remote_nar=$2' \
+        'if test -n "$remote_nar"; then nix-store --import < "$remote_nar"; rm -f "$remote_nar"; fi' \
+        'nix-env --profile /nix/var/nix/profiles/system --set "$system_path"' \
+        '"$system_path/bin/switch-to-configuration" switch'
+)
 
-echo "deploy-to: activating $system_path on $host" >&2
-ssh -t $host sudo "$system_path/bin/switch-to-configuration" switch
+ssh -t $host sudo sh -e -c (string escape -- $remote_script) sh (string escape -- $system_path $remote_nar)
 or begin
-    echo "deploy-to: activation failed for $host" >&2
+    echo "deploy-to: deployment failed for $host" >&2
     return $status
 end

configs/nixos/modules/shell/nvim/default.nix

@@ -24,6 +24,9 @@ in
     home-manager.users.${user} = hm: {
       programs.nixvim = {
         enable = true;
+
+        # Aligns Nixvim plugins with this flake's `Nixpkgs`.
+        # `nixpkgs.useGlobalPackages` prevents Home Manager from creating a separate package set.
         nixpkgs.useGlobalPackages = true;
 
         extraPackages = with pkgs; [

docs/.obsidian/app.json

@@ -5,7 +5,7 @@
   "livePreview": false,
   "readableLineLength": false,
   "strictLineBreaks": true,
-  "propertiesInDocument": "visible",
+  "propertiesInDocument": "hidden",
   "showLineNumber": true,
   "autoPairMarkdown": false,
   "useTab": false,

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~",

docs/00 INBOX/ai/adguard-pikachu-migration-design-tree.md

@@ -0,0 +1,110 @@
+# AdGuard migration to Pikachu: design tree
+
+## Research facts
+
+- The pinned Nixpkgs revision provides `adguardhome` version `0.107.79`.
+- NixOS provides the `services.adguardhome` module.
+- The module runs AdGuard Home as a hardened dynamic systemd user.
+- It stores state in `/var/lib/AdGuardHome`.
+- It grants `CAP_NET_BIND_SERVICE` for DNS port 53.
+- It grants `CAP_NET_RAW` when AdGuard Home DHCP is enabled.
+- The module supports an arbitrary YAML configuration through `settings`.
+- The module supports fully declarative operation with `mutableSettings = false`.
+- In fully declarative operation, the module replaces `/var/lib/AdGuardHome/AdGuardHome.yaml` on each service start.
+- Fully declarative operation requires `dns.bootstrap_dns` as a list.
+- Declarative settings pass an AdGuard configuration check during the build.
+- `mutableSettings = true` merges declared settings into UI changes at service start.
+- `mutableSettings = false` replaces the state configuration on every service start.
+- `openFirewall` opens only the web interface port.
+- The migration must explicitly open DNS ports 53/TCP and 53/UDP when clients need them.
+- Pikachu has address `10.23.10.102` on its untagged network.
+- Pikachu carries VLAN 20 and creates bridge `br-vlan20`.
+- The guest framework runs each guest in its own systemd-nspawn container.
+- Each guest attaches to a host VLAN bridge and receives an address through DHCP.
+- Pikachu currently configures only VLAN 20 for guests.
+- The repository has no AdGuard configuration, Proxmox inventory, or DHCP-provider configuration.
+- The current DHCP provider remains unestablished.
+- The current Proxmox AdGuard container uses MAC `bc:24:11:91:60:bf`.
+- The current Proxmox AdGuard container uses address `10.23.20.33` on VLAN 20.
+- This environment has no Proxmox SSH target or local Proxmox control utility.
+- The current AdGuard configuration listens on all guest addresses at DNS port 53.
+- The current AdGuard configuration has no allowed-client or disallowed-client restrictions.
+- The current AdGuard configuration uses Cloudflare, Google, and Quad9 encrypted upstreams in parallel.
+- The current AdGuard configuration disables DNSSEC.
+- The current AdGuard configuration defines three local rewrites.
+- The repository configures no host backup system or monitoring system.
+- Hosts update through explicit `nixos-rebuild switch --flake` commands.
+- The working tree has unrelated operator changes.
+
+## Service tradeoffs
+
+| Service | NixOS support | Domain filtering | Administration UI | DHCP | Encrypted DNS | Main tradeoff |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| AdGuard Home | `services.adguardhome`; checked YAML and mutable or immutable state | Native block lists, rules, and per-client policy | Native | Native | Upstream and client-facing encrypted DNS | Direct migration with the closest state and feature match. UI state conflicts with fully declarative operation unless configuration is immutable. |
+| Blocky | `services.blocky`; checked declarative YAML | Native lists, allow lists, rewrites, and per-client groups | No UI; REST API and metrics only | No | Encrypted upstreams and client-facing DoH, DoT, and DoQ | Strong Git-managed configuration and low operational surface. It lacks an interactive administration interface and DHCP. |
+| Pi-hole | `services.pihole-ftl` plus `services.pihole-web`; declarative TOML, lists, and dashboard | Native gravity lists, allow lists, regex rules, and groups | Native | Native | Use a companion for encrypted upstream DNS | Familiar filtering product with a dashboard. The migration changes product data and uses more coupled services. |
+| Technitium DNS Server | `services.technitium-dns-server`; service and firewall options only | Native block lists and DNS applications | Native | Native | Upstream and client-facing encrypted DNS | Broadest DNS feature set, including authoritative DNS. NixOS does not expose its runtime configuration declaratively. |
+| Unbound | `services.unbound`; structured server and free-form settings | Local zones or response-policy zones require custom policy management | No | No | DNS-over-TLS support | Mature validating recursive resolver. Filtering and user operations require separate design. |
+| dnscrypt-proxy | `services.dnscrypt-proxy`; declarative TOML | Local block and allow rules, without a list-management UI | No | No | Encrypted upstream DNS, including DNSCrypt and DoH | Strong upstream privacy and resolver selection. It is not a full network filtering appliance. |
+| Knot Resolver | `services.kresd`; structured listener settings and extra Lua | Custom policy modules | No | No | Client-facing DoH and TLS listeners | Flexible high-performance recursive resolver. Filtering requires resolver expertise and custom policy. |
+| SmartDNS | `services.smartdns`; free-form settings | Domain and address rules | No NixOS-integrated UI | No | Encrypted upstream and client-facing DNS | Optimizes upstream selection and latency. It offers less complete filtering management than dedicated blockers. |
+
+`Native` means that the product provides the feature without a companion service.
+
+## Decision tree
+
+- **D1 — DNS service product** [settled]
+  - Retain AdGuard Home on Pikachu.
+    - Constraint: Preserve AdGuard Home as the DNS service product.
+    - **D2A — AdGuard Home role** [settled]
+      - Provides DNS filtering and resolution only.
+      - Constraint: The existing DHCP provider continues to assign addresses and DHCP options.
+    - **D3A — Execution placement** [settled]
+      - Runs in a dedicated guest on Pikachu's existing VLAN 20.
+      - Constraint: Isolate AdGuard Home from the Pikachu host.
+    - **D4A — Guest network identity** [settled]
+      - Reuses MAC `bc:24:11:91:60:bf` and address `10.23.20.33` on VLAN 20.
+      - Constraint: Stop the Proxmox container before the guest starts.
+    - **D5A — Network exposure** [settled]
+      - Listens on all guest addresses at port 53.
+      - Accepts requests from every reachable internal device.
+    - **D6A — Resolver policy** [settled]
+      - Preserves the existing upstream resolvers and parallel resolver mode.
+      - Preserves disabled DNSSEC and the three local rewrites.
+    - **D7A — Configuration authority** [settled]
+      - Uses fully declarative Nix configuration.
+      - Constraint: Set `services.adguardhome.mutableSettings = false`.
+      - Constraint: Declare `dns.bootstrap_dns` as a list.
+      - Constraint: Web UI changes do not persist.
+      - Constraint: Match existing service behavior except for the administrator password.
+    - **D8A — Migration data** [settled]
+      - Migrate functional DNS configuration only.
+      - Constraint: Do not migrate query history or statistics.
+    - **D9A — Operations** [settled]
+      - Declares a newly generated bcrypt verifier in Nix.
+      - Constraint: Keep the plaintext password outside the repository and Nix store.
+      - Constraint: The verifier is readable from the Nix store.
+    - **D10A — Cutover and rollback** [settled]
+      - Uses a planned atomic cutover with rollback.
+      - Stop the Proxmox container before starting the guest.
+      - Validate the guest before restoring the Proxmox container during rollback.
+    - **D11A — Runtime-state backup** [settled]
+      - Do not back up rebuildable AdGuard Home runtime state.
+    - **D12A — Monitoring** [settled]
+      - Do not add DNS availability monitoring.
+    - **D13A — Upgrade ownership** [settled]
+      - The normal flake update and explicit NixOS rebuild workflow owns upgrades.
+  - Replace AdGuard Home. [not selected]
+    - **D2B — Replacement product** [not applicable]
+      - Choose Blocky, Pi-hole, Technitium, or a composed resolver.
+
+## Frontier
+
+None.
+
+## Sources
+
+- Pinned Nixpkgs module: `nixos/modules/services/networking/adguardhome.nix`.
+- Pinned Nixpkgs modules: `blocky.nix`, `pihole-ftl.nix`, `pihole-web.nix`, `technitium-dns-server.nix`, `unbound.nix`, `dnscrypt-proxy.nix`, `knot-resolver.nix`, and `smartdns.nix`.
+- AdGuard Home README, release `v0.107.79`.
+- Technitium DNS Server README, current upstream.

docs/00 INBOX/ai/caps-escape-design.md

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

docs/00 INBOX/ai/nixos-agents-style-scope-design-tree.md

@@ -0,0 +1,130 @@
+# NixOS AGENTS and style-skill scope design tree
+
+This tree reviews `configs/nixos/AGENTS.md`.
+It decides which instructions belong in Nix style rules.
+
+## Known facts
+
+- `configs/nixos/AGENTS.md` has 70 lines.
+- Each frontier question quotes the complete instruction under review.
+- This review decides instruction placement only.
+- It supplies guidance for desktop, Firefox, Neovim, AI tooling, and NixOS gotchas.
+- The `/review` prompt loads `nix-style` for Nix files.
+- `nix-style` loads every rule under `src/skills/style/nix/rules/`.
+- The current Nix rules cover Nix syntax and flake structure.
+- `configs/nixos/AGENTS.md` includes a guest-module ownership rule.
+- The RomM session missed that ownership rule during implementation.
+- `registry.window-icon` exists in `configs/nixos/registry/window-icon.nix`.
+- Desktop application modules declare window classes and rendered icons in that registry.
+- Hyprland reads the registry to generate workspace icon mappings.
+- The AGENTS instruction named the registry after its introduction on 2026-10-11.
+- The `class` option describes its window-class match.
+- The `icon` option describes a string icon value.
+- The registry schema does not document the rendered-string requirement or the class-discovery command.
+- Hyprland renders `config.registry.env` as its `env` configuration.
+- The `env` registry replaced direct Hyprland environment declarations in commit `370cab8f8`.
+- `configs/nixos/modules/desktop/apps/r2modman.nix` enables a graphical application without a `registry.window-icon` declaration.
+- The current registry modules already validate value uniqueness and field combinations.
+- They do not validate required producer declarations.
+- The registry collector is specific to the NixOS dotfiles configuration.
+- A non-discoverable environment fact records local behavior that configuration, source code, and normal tool help do not reveal.
+- The current instruction groups are:
+  - Desktop: window icons, Hyprland environment variables, and cursor settings.
+  - Firefox: search-engine declarations and extension-storage compatibility.
+  - Neovim: Nixvim package-set selection.
+  - AI tooling: Herdr key names and Pi configuration locations.
+  - Gotchas: registry APIs, guest boundaries, SOPS ownership, guest mounts, deployment, DNS, hardware, module paths, and host commands.
+
+## Decision tree
+
+- Instruction review
+  - Settled: Review each complete instruction in source order.
+  - Registry conventions
+    - Settled: Create `src/skills/style/nix/rules/dotfiles.md`.
+    - Graphical application icon instruction
+      - Settled: Move the complete instruction to `src/skills/style/nix/rules/dotfiles.md`.
+    - Hyprland session environment instruction
+      - Settled: Remove it because `registry.env` superseded it.
+    - Firefox search-engine instruction
+      - Settled: Remove it because the Firefox module documents the configuration.
+    - Firefox extension-storage instruction
+      - Settled: Move it to a comment above `extensions.settings` in `modules/desktop/apps/firefox.nix`.
+    - Neovim package-set instruction
+      - Settled: Move it to a comment above `nixpkgs.useGlobalPackages` in `modules/shell/nvim/default.nix`.
+    - Herdr key-name instruction
+      - Settled: Remove it.
+    - Pi extension location instruction
+      - Settled: Remove it. It recorded a completed migration from NixOS-managed sources.
+    - Pi generated-settings instruction
+      - Settled: Remove it because the Pi module documents the managed boundary.
+    - Library-function qualification instruction
+      - Settled: Generalize it and move it to `src/skills/style/nix/rules/general.md`.
+    - Guest ownership instruction
+      - Settled: Move it to `src/skills/style/nix/rules/dotfiles.md`.
+    - SOPS guest-owner instruction
+      - Settled: Move it to `src/skills/style/nix/rules/dotfiles.md`.
+    - Nested guest-mount instruction
+      - Settled: Remove it because the example describes no active layout.
+    - `deploy-to` instruction
+      - Settled: Remove it. Agents cannot complete its remote sudo steps.
+    - Pikachu deploy-closure instruction
+      - Settled: Remove it because `deploy-to` encodes the required import path.
+    - Public-DNS instruction
+      - Settled: Remove it.
+    - Hardware-configuration instruction
+      - Settled: Remove it because the root auto-generated-file rule owns the policy.
+    - Chaotic-cache instruction
+      - Settled: Remove it because `modules.host.cachyos.enable` owns the cache configuration.
+    - Module-relative-path instruction
+      - Settled: Remove it because Nix evaluation reports invalid paths.
+    - Pikachu `uptime` instruction
+      - Settled: Remove it because the command exposes its supported options.
+    - Guest-ACME-evaluation instruction
+      - Settled: Remove it because current direct guest evaluation succeeds.
+    - systemd executable instruction
+      - Settled: Remove it because `general.md` already requires `lib.getExe'` for non-main executables.
+
+## Frontier
+
+The frontier is empty.
+
+## Shared understanding
+
+Remove these instructions from `configs/nixos/AGENTS.md`:
+
+- Hyprland session environment
+- Firefox search engines
+- Herdr shifted punctuation
+- Pi extension source location
+- Pi managed settings
+- Nested guest mounts
+- `deploy-to` behavior
+- Pikachu deploy closures
+- Public DNS boundary
+- Hardware configuration
+- Chaotic cache selection
+- Module-relative paths
+- Pikachu boot time
+- Guest ACME evaluation
+- systemd executable selection
+
+Move these instructions intact to `src/skills/style/nix/rules/dotfiles.md`:
+
+- Graphical application icons
+- Guest ownership
+- SOPS guest ownership
+
+Move the generalized library-function qualification convention to
+`src/skills/style/nix/rules/general.md`.
+
+Move these instructions to code comments:
+
+- Firefox extension storage: above `extensions.settings` in
+  `configs/nixos/modules/desktop/apps/firefox.nix`
+- Nixvim package set: above `nixpkgs.useGlobalPackages` in
+  `configs/nixos/modules/shell/nvim/default.nix`
+
+The review does not decide how to restore the auto-generated status of
+`configs/nixos/hosts/pikachu/hardware-configuration.nix`.
+
+The operator confirmed this design and authorized the edits.

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.

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.

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.

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

@@ -3,8 +3,8 @@ aliases:
   - "0015"
   - RomM 5.4 Package
 date-created: 2026-10-19 19:40
-date-modified: 2026-10-19 19:40
-status: open
+date-modified: 2026-10-21 00:01
+status: closed
 area: "[[homelab]]"
 blocked-by:
   - "[[0014-romm-guest]]"

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

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:
-

src/flake/packages/default.nix

@@ -4,5 +4,7 @@
     inherit root;
   };
 
+  romm = pkgs.callPackage ./romm.nix { };
+
   waybar = pkgs.callPackage ./waybar.nix { };
 }

src/flake/packages/romm.nix

@@ -0,0 +1,124 @@
+{
+  buildNpmPackage,
+  fetchFromGitHub,
+  lib,
+  python3,
+  romm,
+}:
+romm.overrideAttrs (
+  finalAttrs: previousAttrs:
+  let
+    frontend = buildNpmPackage {
+      pname = "romm-frontend";
+      inherit (finalAttrs) version;
+      src = "${finalAttrs.src}/frontend";
+
+      npmDepsHash = "sha256-f5IcpOVv7JYFzUPkZIq5nbT3dS1f/KCSllh8Vkgl1P0=";
+      npmFlags = [ "--ignore-scripts" ];
+      makeCacheWritable = true;
+
+      installPhase = ''
+        runHook preInstall
+        cp -r dist $out
+        chmod u+w $out/assets
+        cp -r assets/. $out/assets/
+        runHook postInstall
+      '';
+    };
+
+    # RomM 5.4 requires packages absent from the Nixpkgs 5.2 environment.
+    pythonEnv = python3.withPackages (
+      ps: with ps; [
+        aiohttp
+        alembic
+        anyio
+        apprise
+        asyncssh
+        authlib
+        bcrypt
+        colorama
+        croniter
+        cryptography
+        defusedxml
+        email-validator
+        fastapi
+        gunicorn
+        httpx
+        httpx2
+        itsdangerous
+        jinja2
+        joserfc
+        mariadb
+        mutagen
+        mysql-connector-python
+        opentelemetry-distro
+        opentelemetry-exporter-otlp
+        opentelemetry-instrumentation-aiohttp-client
+        opentelemetry-instrumentation-fastapi
+        opentelemetry-instrumentation-httpx
+        opentelemetry-instrumentation-redis
+        opentelemetry-instrumentation-sqlalchemy
+        passlib
+        pillow
+        psycopg
+        pydantic
+        pydash
+        python-dotenv
+        python-magic
+        python-multipart
+        python-socketio
+        pyyaml
+        redis
+        rq
+        rq-scheduler
+        sentry-sdk
+        sqlalchemy
+        starlette
+        streaming-form-data
+        strsimpy
+        ua-parser
+        unidecode
+        uvicorn
+        uvicorn-worker
+        watchfiles
+        yarl
+        zipfile-inflate64
+        zstandard
+      ]
+    );
+  in
+  {
+    version = "5.4.0";
+
+    src = fetchFromGitHub {
+      owner = "rommapp";
+      repo = "romm";
+      tag = finalAttrs.version;
+      hash = "sha256-oIYEdIAJgXkcqjZtWlWKD/NFiQ3gbo7gxwLhqZOCWpM=";
+    };
+
+    postPatch = previousAttrs.postPatch + ''
+      # Redis 8.0.1 removed this argument.
+      # RomM disables the related maintenance notifications.
+      substituteInPlace backend/handler/redis_handler.py \
+        --replace-fail 'from redis.maint_notifications import MaintNotificationsConfig' "" \
+        --replace-fail '    "maint_notifications_config": MaintNotificationsConfig(enabled=False),' ""
+    '';
+
+    installPhase =
+      lib.replaceStrings
+        [
+          "${previousAttrs.passthru.frontend}"
+          "${previousAttrs.passthru.pythonEnv}"
+        ]
+        [
+          "${frontend}"
+          "${pythonEnv}"
+        ]
+        previousAttrs.installPhase;
+
+    passthru = previousAttrs.passthru // {
+      inherit frontend pythonEnv;
+    };
+  }
+)

src/skills/grill/SKILL.md

@@ -3,16 +3,20 @@ name: grill
 description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
 ---
 
-Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: each decision branches into the decisions it unblocks.
 
 Maintain the design tree in a new Markdown file. Use the file as the source of truth.
 
-Work the tree one question at a time. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask now without guessing at answers you have not heard yet. Record the next frontier question in the file, then ask it and wait for the user's answer.
+Build the complete **frontier** before the first question.
+After each answer, recompute and display every frontier decision.
+
+Ask one frontier decision per turn.
+A clarification leaves that decision open.
 
 Format a question like so:
 
 ```
-❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+❓ **D1 — <decision title>**: <question body, might be multiple paragraphs, including multiple choices>
 
 **Options**
 
@@ -22,7 +26,7 @@ Format a question like so:
 
 ---
 
-❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+❓ **D2 — <decision title>**: <question body, might be multiple paragraphs, including multiple choices>
 
 **Options**
 
@@ -34,7 +38,10 @@ Format a question like so:
 List every viable answer in an ordered list and mark your recommended answer.
 Word each question so "yes" accepts your recommended answer.
 
-Each user answer reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier in the file and ask the next question. A question whose answer depends on another open question belongs later, not next.
+Before asking the next question, account for every decision that the response settles.
+Record preferences as constraints.
+Settle an implementation decision only after facts establish that it is viable.
+A decision with unresolved prerequisites belongs outside the frontier.
 
 Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), find it with available tools; don't ask the user for anything you could look up yourself. The _decisions_ are the user's: put each to them and wait.
 

src/skills/style/nix/rules/dotfiles.md

@@ -0,0 +1,43 @@
+## Register window icons
+
+### Rule
+
+Each graphical application has a `registry.window-icon` entry with a window-class match and rendered icon.
+
+### Rationale
+
+Hyprland uses this registry to render workspace icons for open application windows.
+
+Run this command to list window classes from the running compositor:
+
+```bash
+hyprctl clients -j | jq -r '.[].class' | sort -u
+```
+
+## Separate guest wrappers from service modules
+
+### Rule
+
+Each guest module wraps one service module.
+The guest enables its service through `guests.<name>.interior`.
+Service modules own service configuration.
+Guest modules configure bind mounts, secret delivery, resource limits, and registry entries.
+Host configuration supplies deployment-specific paths, volumes, addresses, and routes.
+
+### Rationale
+
+Service modules support a service without guest infrastructure.
+Guest modules adapt a service module to a guest.
+Host configuration provides deployment-specific values.
+
+## Decrypt guest secrets on the host
+
+### Rule
+
+A host user owns each guest secret before SOPS decrypts it.
+Each guest service group accesses its secrets through a read-only bind mount.
+
+### Rationale
+
+Guest service accounts do not exist on the host, where SOPS creates secrets.
+The shared service group preserves read access across the guest boundary.

src/skills/style/nix/rules/general.md

@@ -22,6 +22,17 @@ Do not call `lib.removeSuffix ".nix"` outside the utility definition.
 
 The utility centralizes Nix file-name normalization.
 
+## Qualify library functions
+
+### Rule
+
+Keep library functions qualified as `lib.<function>`.
+
+### Rationale
+
+Qualification makes library ownership explicit.
+It prevents local namespace collisions.
+
 ## Use executable helpers for package commands
 
 ### Rule