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.