refactor: centralize Nix-managed Codex assets and integrations

modules/capabilities/ai/README.md

@@ -0,0 +1,41 @@
+# Codex installation
+
+`ai.nix` installs binaries and Codex defaults on Polaris and Zenith.
+`_sources.nix` pins upstream assets; `_assets.nix` declares skills, MCP servers,
+the Ponytail marketplace and the upstream Herdr session hook.
+Edit `instructions/codex.md` for global Codex instructions.
+
+Nix owns installation files. Codex owns writable user settings, plugin toggles,
+trust, credentials and sessions. Bundled/service-delivered capabilities remain
+vendor-managed. Update Ponytail's revision, hash and `ponytailVersion` together.
+The cache uses real directories with linked files because Codex skips symlinked
+plugin version directories. Do not run plugin updaters on Nix-managed assets.
+
+Herdr's skill is linked directly from the same source as its binary. An agent
+can also read it with `herdr --skill`; no generated file is necessary.
+The upstream session hook supports restore, not model instruction injection.
+
+## Manual transition
+
+Close Codex before cleaning up the previous setup and activating the new one.
+No migration or compatibility code runs automatically.
+
+- Remove old standalone skills: `~/.codex/skills/ponytail`,
+  `~/.agents/skills/find-skills`, `~/.agents/skills/context7-mcp.bak`,
+  and `~/.codex/skills/nixos-maintainer.bak`.
+- Remove the old Ponytail cache `~/.codex/plugins/cache/ponytail/ponytail`.
+  Remove any unmanaged copy at `~/.codex/plugins/cache/nix-managed/ponytail/4.9.0`
+  if it blocks Home Manager activation. The obsolete managed
+  `~/.codex/plugins/ponytail` link is removed by Home Manager.
+- In `~/.codex/config.toml`, remove the old `marketplaces.ponytail` entry and
+  rename `plugins."ponytail@ponytail"` to `plugins."ponytail@nix-managed"`,
+  preserving its enabled preference. Remove user launch fields for the
+  `context7`, `nixos` and `openaiDeveloperDocs` MCP servers so system defaults
+  apply; preserve toggles and unrelated preferences.
+- Remove the old Herdr SessionStart command from `~/.codex/hooks.json` and its
+  `~/.codex/herdr-agent-state.sh` file. Preserve unrelated hooks.
+- Activate your Nix configuration, then restart Codex.
+
+If an earlier version of this work was activated, Home Manager removes its
+managed instruction and integration links for other harnesses. Unmanaged copies
+must be removed manually if no longer wanted.

modules/capabilities/ai/_assets.nix

@@ -0,0 +1,64 @@
+{ pkgs }:
+let
+  sources = import ./_sources.nix { inherit pkgs; };
+  json = pkgs.formats.json { };
+  ponytailVersion = "4.9.0";
+  context7Headers = pkgs.writeShellScript "context7-http-headers" ''
+    set -euo pipefail
+    CONTEXT7_KEY_FILE="''${XDG_CONFIG_HOME:-$HOME/.config}/context7/api-key"
+    CONTEXT7_KEY="$(< "$CONTEXT7_KEY_FILE")"
+    exec ${pkgs.jq}/bin/jq --null-input --compact-output \
+      --arg authorization "Bearer $CONTEXT7_KEY" '{ Authorization: $authorization }'
+  '';
+  codexHooks = {
+    SessionStart = [
+      {
+        hooks = [
+          {
+            type = "command";
+            command = "${pkgs.bash}/bin/bash ${sources.herdr}/src/integration/assets/codex/herdr-agent-state.sh session";
+            timeout = 10;
+          }
+        ];
+      }
+    ];
+  };
+in
+{
+  inherit sources ponytailVersion context7Headers;
+  inherit codexHooks;
+  codexCache = ".codex/plugins/cache/nix-managed/ponytail/${ponytailVersion}";
+  marketplace = pkgs.runCommand "ai-marketplace" { } ''
+    mkdir -p "$out/.agents/plugins" "$out/plugins"
+    ln -s ${sources.ponytail} "$out/plugins/ponytail"
+    cp ${
+      json.generate "ai-marketplace.json" {
+        name = "nix-managed";
+        plugins = [
+          {
+            name = "ponytail";
+            source = {
+              source = "local";
+              path = "./plugins/ponytail";
+            };
+            policy = {
+              installation = "AVAILABLE";
+              authentication = "ON_INSTALL";
+            };
+            category = "Productivity";
+          }
+        ];
+      }
+    } "$out/.agents/plugins/marketplace.json"
+  '';
+  skills = {
+    context7-mcp = ../skills/context7-mcp;
+    nixos-maintainer = ../skills/nixos-maintainer;
+    herdr = "${sources.herdr}/skills/herdr";
+  };
+  servers = {
+    context7.url = "https://mcp.context7.com/mcp";
+    nixos.command = "${pkgs.mcp-nixos}/bin/mcp-nixos";
+    openaiDeveloperDocs.url = "https://developers.openai.com/mcp";
+  };
+}

modules/capabilities/ai/_sources.nix

@@ -0,0 +1,10 @@
+{ pkgs }:
+{
+  ponytail = pkgs.fetchFromGitHub {
+    owner = "DietrichGebert";
+    repo = "ponytail";
+    rev = "356918eba965ee1eac64bd3a7f0dd02108350de5";
+    hash = "sha256-LPNMyHsri3+eeDmphEAKL1JgoRE4dLIPfZ4XZ+xu5UY=";
+  };
+  herdr = pkgs.llm-agents.herdr.src;
+}

modules/capabilities/ai/instructions/codex.md

@@ -0,0 +1,23 @@
+# Environment
+
+- This is Nix; use `nix run` for missing commands. Default Nix commands to `--quiet`.
+- Keep output bounded. Capture large Nix listings in `/tmp`; inspect targeted excerpts and failing logs only. Locate store files before reading them.
+- Manage persistent binaries, skills, plugins and MCP definitions in `/home/kiri/.config/nixos`. Keep interactive settings, credentials and session state outside Nix.
+- `HERDR_ENV=1` means you are inside Herdr. Read the Herdr skill or run `herdr --skill` when Herdr interaction is needed.
+
+# Work
+
+- Inspect relevant code and callers; follow project conventions and fix root causes.
+- Prefer existing code, standard libraries and native capabilities. Avoid speculative abstractions; optimize conceptual simplicity, not line count.
+- Keep changes focused. Prefer clean breaking changes over compatibility layers or migration scripts; explain required manual steps.
+- Use targeted reads and tool calls. Verify unfamiliar or consequential APIs against version-appropriate primary documentation; prefer Context7 when needed.
+- In reviews, distinguish confirmed problems from optional improvements and explain meaningful tradeoffs.
+- Never push without my explicit approval. Other remote actions must remain within the authorized task.
+- User instructions take precedence over skill guidelines, including testing defaults.
+
+# Validation
+
+Do not add or run tests unless explicitly requested or necessary to resolve a
+concrete correctness concern. Use the smallest relevant validation and stop once
+it provides sufficient confidence. Avoid broad suites and repeated builds without
+a specific reason. Report only checks actually performed.