feat(nixos): add Valheim service module

configs/nixos/hosts/pikachu/default.nix

@@ -66,35 +66,13 @@
 
   registry.address.pikachu.self = "10.23.10.102";
 
-  modules.services.steamcmd = {
+  modules.services.games.valheim = {
     enable = true;
     steamDir = "/pikachu/data/steamcmd";
-    serviceName = "valheim";
-    appId = 896660;
     installDir = "/pikachu/data/servers/valheim/main";
     stateDir = "/pikachu/media/games/servers/valheim/main";
-    executable = "./valheim_server.x86_64";
+    serverName = "main";
-    arguments = [
+    password = "foobarbaz";
-      "-nographics"
-      "-batchmode"
-      "-name"
-      "main"
-      "-port"
-      "2456"
-      "-world"
-      "main"
-      "-savedir"
-      config.modules.services.steamcmd.stateDir
-      "-password"
-      "foobarbaz"
-      "-public"
-      "0"
-    ];
-    udpPorts = [
-      2456
-      2457
-      2458
-    ];
   };
 
   guests.actualbudget = {

configs/nixos/modules/services/games/valheim.nix

@@ -0,0 +1,81 @@
+{
+  config,
+  lib,
+  ...
+}:
+{
+  options.modules.services.games.valheim = {
+    enable = lib.mkEnableOption "Valheim dedicated server";
+
+    steamDir = lib.mkOption {
+      type = lib.types.str;
+      example = "/data/steamcmd";
+      description = "Directory where SteamCMD stores metadata and cache files.";
+    };
+
+    installDir = lib.mkOption {
+      type = lib.types.str;
+      example = "/data/servers/valheim/main";
+      description = "Directory where SteamCMD installs the Valheim server files.";
+    };
+
+    stateDir = lib.mkOption {
+      type = lib.types.str;
+      example = "/data/state/valheim/main";
+      description = "Directory where Valheim stores world data.";
+    };
+
+    serverName = lib.mkOption {
+      type = lib.types.str;
+      default = "valheim";
+      description = "Name shown for the Valheim server.";
+    };
+
+    port = lib.mkOption {
+      type = lib.types.port;
+      default = 2456;
+      description = "Base UDP port for the Valheim server.";
+    };
+
+    password = lib.mkOption {
+      type = lib.types.str;
+      description = "Valheim server password.";
+    };
+
+  };
+
+  config = lib.mkIf config.modules.services.games.valheim.enable (
+    let
+      service = config.modules.services.games.valheim;
+    in
+    {
+      modules.services.steamcmd = {
+        enable = true;
+        inherit (service) steamDir installDir stateDir;
+        serviceName = "valheim";
+        appId = 896660;
+        executable = "./valheim_server.x86_64";
+        arguments = [
+          "-nographics"
+          "-batchmode"
+          "-name"
+          service.serverName
+          "-port"
+          (toString service.port)
+          "-world"
+          service.serverName
+          "-savedir"
+          service.stateDir
+          "-password"
+          service.password
+          "-public"
+          "0"
+        ];
+        udpPorts = [
+          service.port
+          (service.port + 1)
+        ];
+      };
+    }
+  );
+}

docs/00 INBOX/ai/steamcmd servers.md

@@ -0,0 +1,71 @@
+# SteamCMD servers
+
+Use `modules.services.steamcmd` as the low-level runner for one SteamCMD server.
+Create a game module under `configs/nixos/modules/services/games/` for each game.
+
+The game module owns game-specific defaults and command-line flags.
+The host owns deployment-specific paths, names, secrets, and network placement.
+
+## Create a game module
+
+1. Create `configs/nixos/modules/services/games/<game>.nix`.
+2. Define options under `modules.services.games.<game>`.
+3. Expose only values the host must choose.
+4. Map those values to `modules.services.steamcmd`.
+5. Set the Steam dedicated-server app ID in the game module.
+6. Set the server executable in the game module.
+7. Generate game-specific arguments in the game module.
+8. Open the game's documented UDP ports in the game module.
+
+Keep `modules.services.steamcmd` focused on shared SteamCMD behavior.
+Do not put game-specific flags or port rules there.
+
+## Configure a host
+
+During validation, enable the game module directly on a host.
+
+```nix
+modules.services.games.valheim = {
+  enable = true;
+  steamDir = "/pikachu/data/steamcmd";
+  installDir = "/pikachu/data/servers/valheim/main";
+  stateDir = "/pikachu/media/games/servers/valheim/main";
+  serverName = "main";
+  password = "foobarbaz";
+};
+```
+
+Use host paths for direct host deployment.
+Use guest paths after the server moves into a guest.
+
+## Deploy and test
+
+1. Evaluate the host configuration.
+
+   ```sh
+   nix eval .#nixosConfigurations.<host>.config.system.build.toplevel.drvPath --raw
+   ```
+
+2. Deploy the host.
+
+   ```sh
+   deploy-to <host>
+   ```
+
+3. Check the game service.
+
+   ```sh
+   sudo systemctl status <game>.service
+   sudo journalctl -u <game>.service -n 200 --no-pager
+   ```
+
+4. Check UDP listeners.
+
+   ```sh
+   sudo ss -lunp | grep -E '<port>|<port-plus-one>|<game>'
+   ```
+
+5. Connect from the game client.
+
+The Valheim server is ready after the log contains `Game server connected`.
+It can spend time generating a new world before it accepts connections.

docs/AGENTS.md

@@ -13,9 +13,10 @@ This repository is an Obsidian vault for an execution-focused second brain.
 
 ## AI boundary
 
-AI may freely create and edit files inside `00 INBOX/ai/`.
+Use `00 INBOX/ai/` for AI-authored documentation drafts and captures.
-Creating or editing files elsewhere requires explicit user approval, unless the user explicitly requested that specific file change.
+Create documentation there when the user does not name an exact path.
-AI-generated material outside the boundary is provisional until reviewed or explicitly promoted.
+Create or edit documentation elsewhere only when the user names the exact file path.
+Treat all other vault areas as reviewed or operator-owned.
 
 ## Working style
 
@@ -33,3 +34,4 @@ Remove template instruction text when writing a note from a template.
 
 ## Gotchas
 
+