refactor(agents): manage agent config in a home-manager module (#367)

home/README.md

@@ -15,6 +15,7 @@ home/
 │   │   ├── terminal/  # Terminal emulators (Ghostty, Kitty, etc.)
 │   │   └── ...
 │   ├── tui/           # Terminal/TUI applications
+│   │   ├── agents/    # AI coding agents (rules deployment, CLIs, env)
 │   │   ├── editors/   # Heavy editor/tooling pkgs only (`packages.nix`; core editors live under `core/editors`)
 │   │   ├── encryption/ # Encryption and security tooling
 │   │   └── ...

home/base/README.md

@@ -24,7 +24,7 @@ systems.
 ### Desktop Environment
 
 - **gui/**: Cross-platform GUI applications and configurations
-  - **dev-tools.nix**: Development tools and IDEs
+  - **dev-tools.nix**: Misc development and network tools (mitmproxy, wireshark)
   - **media.nix**: Media players and utilities
   - **zed-editor.nix**: Zed editor configuration (primary GUI editor)
   - **terminal/**: Terminal emulator configurations
@@ -34,7 +34,8 @@ systems.
 ### Terminal Interface
 
 - **tui/**: Terminal-based interface configurations
-  - **agent-env.nix**: Telemetry/auto-update opt-outs for AI coding agents
+  - **agents/**: AI coding agents — global rules deployment, CLIs, and telemetry/auto-update
+    opt-outs
   - **cloud/**: Cloud development tools (Terraform, etc.)
   - **container.nix**: Container tools (Docker, Podman)
   - **dev-tools.nix**: Terminal-based development tools

home/base/gui/dev-tools.nix

@@ -1,12 +1,8 @@
 {
   pkgs,
   lib,
-  llm-agents,
   ...
 }:
-let
-  agentPackages = llm-agents.packages.${pkgs.stdenv.hostPlatform.system};
-in
 {
   home.packages =
     with pkgs;
@@ -17,17 +13,5 @@ in
     ++ lib.optionals pkgs.stdenv.hostPlatform.isLinux [
       mitmproxy # http/https proxy tool
       wireshark # network analyzer
-    ]
-    # AI Agent Tools
-    ++ [
-      # Agents
-      agentPackages.codex
-      agentPackages.opencode2
-      agentPackages.kimi-code
-      agentPackages.pi
-      agentPackages.omp
-
-      # MCP servers, configured project-scoped in opencode.jsonc / .codex/config.toml
-      mcp-grafana
     ];
 }

home/base/tui/agents/README.md

@@ -0,0 +1,36 @@
+# Agents
+
+Home Manager module that owns the Nix side of the AI coding agents: deploying the global rules, the
+agent CLIs, and their environment.
+
+The canonical rules text, behavioral scenarios, and external-tool snippets live in the top-level
+[`agents/`](../../../../agents/README.md) directory. That directory stays portable Markdown with no
+Nix dependency; this module only wires it into place.
+
+## Files
+
+- `rules.nix`: links the global rules to every agent's config location.
+- `packages.nix`: agent CLIs (`codex`, `opencode2`, `kimi-code`, `pi`, `omp`) and the Grafana MCP
+  server, from the `llm-agents` flake input.
+- `env.nix`: telemetry and auto-update opt-outs for the agents.
+
+## Deployed rule targets
+
+`rules.nix` creates one out-of-store symlink per target, all pointing at
+`~/nix-config/agents/AGENTS.md`:
+
+| Agent                  | Target                         |
+| ---------------------- | ------------------------------ |
+| Codex                  | `~/.codex/AGENTS.md`           |
+| OpenCode               | `~/.config/opencode/AGENTS.md` |
+| Pi                     | `~/.pi/agent/AGENTS.md`        |
+| OMP                    | `~/.omp/agent/AGENTS.md`       |
+| Cross-tool (Kimi Code) | `~/.agents/AGENTS.md`          |
+
+Out-of-store means an edit to `agents/AGENTS.md` takes effect on the next agent session without a
+Home Manager switch. The trade-off is that the rules stay writable in the checkout; use a store
+symlink (`home.file.<target>.source = ../../../../agents/AGENTS.md`) if immutability matters more
+than fast iteration.
+
+The module is imported through `home/base/tui`, so it applies to every host that imports
+`home/linux/gui.nix` or the macOS `home/darwin` stack. Core-only servers do not get it.

home/base/tui/agents/default.nix

@@ -0,0 +1,4 @@
+{ mylib, ... }:
+{
+  imports = mylib.scanPaths ./.;
+}

home/base/tui/agents/packages.nix

@@ -0,0 +1,21 @@
+{
+  pkgs,
+  llm-agents,
+  ...
+}:
+let
+  agentPackages = llm-agents.packages.${pkgs.stdenv.hostPlatform.system};
+in
+{
+  home.packages = [
+    # Agents
+    agentPackages.codex
+    agentPackages.opencode2
+    agentPackages.kimi-code
+    agentPackages.pi
+    agentPackages.omp
+
+    # MCP servers, configured project-scoped in opencode.jsonc / .codex/config.toml
+    pkgs.mcp-grafana
+  ];
+}

home/base/tui/agents/rules.nix

@@ -0,0 +1,20 @@
+{ config, ... }:
+let
+  # The global rules are edited often, so link them out-of-store: an edit reaches
+  # the next agent session without a Home Manager switch. Same rationale as
+  # `home/base/tui/tuios`; the checkout path is hardcoded, like the repo's other
+  # out-of-store links.
+  rules = "${config.home.homeDirectory}/nix-config/agents/AGENTS.md";
+  link = config.lib.file.mkOutOfStoreSymlink rules;
+in
+{
+  # One canonical rules file, projected into every agent's config location.
+  home.file = {
+    ".codex/AGENTS.md".source = link; # Codex
+    ".pi/agent/AGENTS.md".source = link; # Pi
+    ".omp/agent/AGENTS.md".source = link; # OMP
+    ".agents/AGENTS.md".source = link; # cross-tool, read by Kimi Code
+  };
+
+  xdg.configFile."opencode/AGENTS.md".source = link; # OpenCode
+}