feat(agents): make Pi a first-class agent

.agents/CONTEXT.md

@@ -0,0 +1,72 @@
+# NixOS Dotfiles
+
+A single flake that builds every machine the user owns — laptop, desktop, and three servers — from one shared, modular configuration.
+
+## Language
+
+**Host**:
+One physical machine the flake builds a NixOS configuration for. Each Host has a directory under `hosts/` holding its machine-specific `hardware-configuration.nix` and its choice of enabled Modules.
+_Avoid_: machine, node, system, box
+
+**Module**:
+A single `.nix` feature file under `modules/` that declares an `enable` option and the configuration it turns on. Every Module is always imported but stays inert until a Host enables it.
+_Avoid_: component, package, plugin
+
+**Guest**:
+A reusable, machine-independent definition under `guests/` that bundles the Modules it runs inside an isolated NixOS instance, realized on a Host as a nested container.
+Its `backend` defaults to `container` (systemd-nspawn).
+`microvm` is a reserved backend value that is not yet built.
+A Guest follows the Modules convention wholesale: the file-or-folder layout, the Namespace convention (`guests/media/jellyfin.nix` declares `guests.media.jellyfin`), and the Enable convention (imported always, inert until a Host sets its `enable`).
+The Guest owns only its interior Modules.
+The Host that enables it supplies the machine-specific placement, such as its VLAN, pool mounts, and resource caps.
+_Avoid_: container, VM, instance, LXC, appliance
+
+**Skeleton**:
+The flake's plumbing — the Auto-loader, the helper lib, the flake inputs/overlays, and the shared base config — as distinct from the Modules that sit on top of it.
+The shared base config splits in two: a host base (`system.nix`) and a slim guest-base that every nested Guest stands on.
+The host base carries host-only machinery, such as the bootloader, hardware profile, host identity, and the boot and garbage-collection timers.
+The guest-base carries only what a nested service needs and auto-enables the `toolkit` bundle and `modules.ssh`.
+Both include the primary user, home-manager, and the shared overlays.
+_Avoid_: framework, core, base, scaffolding
+
+**toolkit**:
+A deliberate bundle Module (`modules.toolkit`) that turns on the baseline interactive environment — fish, tmux, nvim, git, direnv — as one unit, so any Host or Guest shell feels identical.
+The guest-base auto-enables it; a Host enables it explicitly like any other Module, keeping the Host a full checklist.
+Distinct from the grouping-directory enables ADR 0004 rejected, since this is a bundle wanted as a unit.
+_Avoid_: base, workstation, essentials
+
+**Auto-loader**:
+The lib code that recursively discovers and imports every Module under `modules/`, every Host under `hosts/`, and every Guest under `guests/`, so new files wire themselves in without manual `imports` edits.
+_Avoid_: loader, importer, scanner
+
+**Enable convention**:
+The rule that every Module is imported unconditionally and guards its own body with `mkIf config.modules.<path>.enable`, so a Host reads as a checklist of `enable = true` flags.
+_Avoid_: feature flag, toggle, opt-in
+
+**Namespace convention**:
+The rule that a Module's option path mirrors its directory path under `modules/`, so a file's location is its namespace.
+A file whose name matches its enclosing directory is that directory's index node, declaring the directory's own segment rather than a doubled one.
+A directory with no such file is a pure namespace prefix that carries no aggregate enable.
+_Avoid_: option tree, module path, config key
+
+**admin identity**:
+The age identity held only in the operator's password manager, never committed, that is a recipient of every secrets file.
+It is the recovery path for any wiped machine and the credential that authorizes registering a new host.
+_Avoid_: master key, admin key, root key
+
+**host identity**:
+The dedicated age key on one machine's encrypted root, generated there and never transmitted, that decrypts that machine's own secrets and the shared file.
+Deliberately distinct from the machine's SSH host key.
+_Avoid_: machine key, node key, host key
+
+**secrets file**:
+One sops-encrypted file in the repo, encrypted to the admin identity plus whichever hosts may read it. Either shared across every host or specific to one.
+_Avoid_: vault, secret store, keyring
+
+**unstable overlay**:
+The overlay exposing `nixpkgs-unstable` packages as `unstable.<name>`, used to pull an individual package fresher than the `nixos-unstable` base.
+_Avoid_: bleeding-edge, latest
+
+**stable overlay**:
+The overlay exposing the latest stable release (`nixos-26.05`) as `stable.<name>`, used to pin an individual package to the rock-solid release from the `nixos-unstable` base.
+_Avoid_: LTS, release channel

.claude/CONTEXT.md

@@ -1,72 +0,0 @@
-# NixOS Dotfiles
-
-A single flake that builds every machine the user owns — laptop, desktop, and three servers — from one shared, modular configuration.
-
-## Language
-
-**Host**:
-One physical machine the flake builds a NixOS configuration for. Each Host has a directory under `hosts/` holding its machine-specific `hardware-configuration.nix` and its choice of enabled Modules.
-_Avoid_: machine, node, system, box
-
-**Module**:
-A single `.nix` feature file under `modules/` that declares an `enable` option and the configuration it turns on. Every Module is always imported but stays inert until a Host enables it.
-_Avoid_: component, package, plugin
-
-**Guest**:
-A reusable, machine-independent definition under `guests/` that bundles the Modules it runs inside an isolated NixOS instance, realized on a Host as a nested container.
-Its `backend` defaults to `container` (systemd-nspawn).
-`microvm` is a reserved backend value that is not yet built.
-A Guest follows the Modules convention wholesale: the file-or-folder layout, the Namespace convention (`guests/media/jellyfin.nix` declares `guests.media.jellyfin`), and the Enable convention (imported always, inert until a Host sets its `enable`).
-The Guest owns only its interior Modules.
-The Host that enables it supplies the machine-specific placement, such as its VLAN, pool mounts, and resource caps.
-_Avoid_: container, VM, instance, LXC, appliance
-
-**Skeleton**:
-The flake's plumbing — the Auto-loader, the helper lib, the flake inputs/overlays, and the shared base config — as distinct from the Modules that sit on top of it.
-The shared base config splits in two: a host base (`system.nix`) and a slim guest-base that every nested Guest stands on.
-The host base carries host-only machinery, such as the bootloader, hardware profile, host identity, and the boot and garbage-collection timers.
-The guest-base carries only what a nested service needs and auto-enables the `toolkit` bundle and `modules.ssh`.
-Both include the primary user, home-manager, and the shared overlays.
-_Avoid_: framework, core, base, scaffolding
-
-**toolkit**:
-A deliberate bundle Module (`modules.toolkit`) that turns on the baseline interactive environment — fish, tmux, nvim, git, direnv — as one unit, so any Host or Guest shell feels identical.
-The guest-base auto-enables it; a Host enables it explicitly like any other Module, keeping the Host a full checklist.
-Distinct from the grouping-directory enables ADR 0004 rejected, since this is a bundle wanted as a unit.
-_Avoid_: base, workstation, essentials
-
-**Auto-loader**:
-The lib code that recursively discovers and imports every Module under `modules/`, every Host under `hosts/`, and every Guest under `guests/`, so new files wire themselves in without manual `imports` edits.
-_Avoid_: loader, importer, scanner
-
-**Enable convention**:
-The rule that every Module is imported unconditionally and guards its own body with `mkIf config.modules.<path>.enable`, so a Host reads as a checklist of `enable = true` flags.
-_Avoid_: feature flag, toggle, opt-in
-
-**Namespace convention**:
-The rule that a Module's option path mirrors its directory path under `modules/`, so a file's location is its namespace.
-A file whose name matches its enclosing directory is that directory's index node, declaring the directory's own segment rather than a doubled one.
-A directory with no such file is a pure namespace prefix that carries no aggregate enable.
-_Avoid_: option tree, module path, config key
-
-**admin identity**:
-The age identity held only in the operator's password manager, never committed, that is a recipient of every secrets file.
-It is the recovery path for any wiped machine and the credential that authorizes registering a new host.
-_Avoid_: master key, admin key, root key
-
-**host identity**:
-The dedicated age key on one machine's encrypted root, generated there and never transmitted, that decrypts that machine's own secrets and the shared file.
-Deliberately distinct from the machine's SSH host key.
-_Avoid_: machine key, node key, host key
-
-**secrets file**:
-One sops-encrypted file in the repo, encrypted to the admin identity plus whichever hosts may read it. Either shared across every host or specific to one.
-_Avoid_: vault, secret store, keyring
-
-**unstable overlay**:
-The overlay exposing `nixpkgs-unstable` packages as `unstable.<name>`, used to pull an individual package fresher than the `nixos-unstable` base.
-_Avoid_: bleeding-edge, latest
-
-**stable overlay**:
-The overlay exposing the latest stable release (`nixos-26.05`) as `stable.<name>`, used to pin an individual package to the rock-solid release from the `nixos-unstable` base.
-_Avoid_: LTS, release channel

.claude/CONTEXT.md

@@ -0,0 +1 @@
+../.agents/CONTEXT.md

.claude/adr

@@ -0,0 +1 @@
+../.agents/adr

.claude/spec

@@ -0,0 +1 @@
+../.agents/spec

.claude/tasks

@@ -0,0 +1 @@
+../.agents/tasks

AGENTS.md

@@ -0,0 +1,69 @@
+# dotfiles-nixos
+
+One flake that builds every machine the user owns.
+The domain model (Host, Module, Skeleton, Auto-loader, Enable convention, overlays) lives in `.agents/CONTEXT.md`.
+
+## Conventions
+
+- Comments posted to Gitea (pull requests, issues, reviews) go out under the operator's account, so sign every one to make clear the author is the agent, not the operator.
+  End the comment with a `— Claude` sign-off.
+  (A dedicated bot account may replace this later.
+  Until then, the sign-off is the only marker.)
+- Commit messages follow Conventional Commits, specified in `docs/conventional-commits.md`.
+  Scope is the module or host the change belongs to (`fish`, `nvim`, `neogaia`), omitted for repo-wide changes.
+  Keep messages free of Gitea-specific references: this repository is mirrored to GitHub, where issue and pull-request numbers resolve to unrelated things.
+- When a graphical application is added, give it a `window-rewrite` icon mapping in `modules/desktop/waybar.nix`.
+  Without one its windows fall back to the generic default glyph on the workspace indicator instead of showing a recognisable per-application icon.
+  Match on the window class, which `hyprctl clients -j | jq -r '.[].class' | sort -u` lists for the running session.
+
+## Gotchas
+
+- This repo pins no Nix formatter, and its committed `.nix` files are not clean under current `nixfmt-rfc-style`.
+  Running `nixfmt` across a file reflows untouched code (for example `lib.nix`'s `deriveMac` list and multi-line assertion messages) and injects churn unrelated to the change.
+  Format only the lines being written or changed, matching the surrounding style by hand.
+- This repo is developed on `neogaia`, which now runs the NixOS it builds.
+  Flakes and the chaotic substituter come from this flake's own `nix.settings`, so no `NIX_CONFIG` export or per-command `--extra-experimental-features` is needed, and building a toplevel with `boot.kernelPackages = linuxPackages_cachyos` fetches the kernel from `nyx-cache` rather than compiling it.
+  Both were true only while the machine still ran CachyOS against a distro Nix daemon.
+- Git identity is declared in the flake by `modules/git.nix`, which writes `alexion <contact@alexion.dev>` — the identity all history uses — on any host enabling `modules.git`.
+  Every new host has to enable it, so that a host reads as a full checklist of what it carries.
+  It is deployed on `neogaia` and verified: a commit in a repository outside this checkout is authored `alexion <contact@alexion.dev>` with no override.
+  Verify it that way rather than from this checkout, whose `.git/config` carries the same identity and would mask a broken module.
+  `~/.gitconfig` (a second global file that outranks the flake-managed `~/.config/git/config`) currently holds only a `tea` credential helper and no `user.*`, so it does not shadow the identity, but it is undeclared and will not survive a reimage.
+- The primary build/verify seam for any Host is `nix flake check`, which builds `checks.x86_64-linux.<host>` (the system toplevel).
+  Cheap targeted checks use `nix eval .#nixosConfigurations.<host>.config...`.
+- chaotic-nyx must **not** follow our `nixpkgs`, and its packages are built against chaotic's own pinned nixpkgs (its overlay defaults to `onTopOf = "flake-nixpkgs"`, the cache-friendly path).
+  That is what lets the `nyx-cache.chaotic.cx` binary cache hit instead of compiling the CachyOS kernel from source.
+  The tradeoff is that chaotic packages do not see our `unstable`/`stable` overlays.
+- The remote is self-hosted Gitea (`git.alexion.dev`), and the forge CLI is `gitea-axi` rather than `tea`.
+  `gitea-axi` resolves the repository from the `origin` remote and discovers credentials from a `tea` login whose host matches the remote, so both are implicit inside a checkout.
+  It is installed on `neogaia` by `modules.agents.tools.gitea-axi`, and verified: `gitea-axi` run from this checkout renders the `alexion/dotfiles` dashboard authenticated, so the claude-code `SessionStart` hook that runs it now resolves to a real binary rather than a missing one.
+  The package wraps the binary so `git` and `tea` are reachable without being on `PATH`, while still preferring the operator's own where present.
+  Credentials: `~/.config/tea/config.yml` holds a token-bearing login named `alexion`, which `gitea-axi` uses and which also opens pull requests directly with `nix run nixpkgs#tea -- pr create --login alexion --repo alexion/dotfiles --base main --head <branch> ...`.
+  The `--repo` flag is required on that path, since `tea` resolves `origin` only for a login whose SSH host matches.
+  The same token reads PR discussion, which `tea` itself does poorly: `tea pr <n> --comments` prints only the body, and `-f comments` returns no comments field at all.
+  Use the API instead, taking the token from `.logins[] | select(.name=="alexion") | .token`.
+  Review comments are **not** at `/issues/<n>/comments` — that endpoint holds only top-level discussion and is usually empty.
+  Inline comments need two calls: `/pulls/<n>/reviews` for the review ids, then `/pulls/<n>/reviews/<id>/comments` for the bodies, whose `path` and `diff_hunk` fields say what each one is attached to.
+  A review row with an empty `body` is the normal shape when the operator left only inline comments.
+- `~/.claude/skills` and `~/.pi/agent/skills` are home-manager-generated (`recursive = true`), so editing a skill in place fails and a new file created there silently escapes the repo.
+  Shared global skills come from the `skills` flake through `modules/agents/skills.nix`, applied by a rebuild.
+  Claude-specific legacy skills, when kept, live under `modules/agents/claude-code/skills/<name>/`.
+- nixpkgs `vimPlugins.nord-nvim` is `shaunsingh/nord.nvim` (no `require("nord").setup()`).
+  The config wants `gbprod/nord.nvim`, which is packaged as `vimPlugins.gbprod-nord`.
+- `nixos-generate-config --show-hardware-config` needs root on this machine even just to print: unprivileged it dies at `Failed to retrieve subvolume info for /`, because the root filesystem is btrfs.
+- This repo's claude-code module sets sudo's credential cache to per-user (`timestamp_type=global`, 60-minute window), so an authentication made in one real terminal counts for the agent's commands.
+  A `PreToolUse` hook refuses privileged commands while the cache is cold, so a cold cache announces itself instead of stalling.
+  A privileged-command failure *without* that message is the sandbox, not the cache.
+- Host GPUs: `neogaia` is Intel, `zeus` (the desktop) is **AMD**, and `raichu` (a headless server) is the only Nvidia machine.
+  The corrected fact also lives in ADR 0003.
+- This repo's `programs.firefox` `search` (with `force = true`) writes `search.json.mozlz4`.
+  Omission alone does not prune a built-in engine, since Firefox reconciles its app-provided engines back in, so remove one by listing it with `<engine>.metaData.hidden = true`.
+  Engines are referenced by their current id, so the default is `default = "ddg"`, not `"DuckDuckGo"`.
+  Decode the built file with `mozlz4a -d <search.json.mozlz4>` to check the result.
+- `home.sessionVariables` do **not** reach the Hyprland session, since UWSM does not source `hm-session-vars.sh`.
+  The cursor is therefore set through Hyprland's own `env = KEY,VALUE` in `modules/desktop/hyprland/hyprland.nix`, sourced from `config.stylix.cursor`.
+  Bibata ships XCursor format only (no `hyprcursor/` dir), rendered through Hyprland's XCursor fallback, so `XCURSOR_*` and `HYPRCURSOR_*` naming the same theme are both safe.
+- `neogaia`, the repo's only host, is a wifi laptop with a btrfs root and no ZFS pools, so it cannot honestly carry `modules.network`, `modules.zfs`, or a networked/pool-mounted guest.
+  Enabling networkd takes over its DNS, its CachyOS `zfs-kernel` build is marked broken, and it has no bridge or pool to attach to.
+  Verify these against it ad hoc through `nixosConfigurations.neogaia.extendModules` (forcing a ZFS-capable `boot.kernelPackages` for the zfs case) plus `nix eval` of the derived values, never by committing the enablement.
+  A committed guest therefore leaves `vlan`, `mounts`, and `secrets` unset, and the standing enablement waits for the first wired server host with real storage.

CLAUDE.md

@@ -1,64 +1,5 @@
-# dotfiles-nixos
+# Claude Code compatibility
 
-One flake that builds every machine the user owns.
-The domain model (Host, Module, Skeleton, Auto-loader, Enable convention, overlays) lives in `.claude/CONTEXT.md`.
-
-## Conventions
-
-- Comments posted to Gitea (pull requests, issues, reviews) go out under the operator's account, so sign every one to make clear the author is the agent, not the operator.
-  End the comment with a `— Claude` sign-off.
-  (A dedicated bot account may replace this later.
-  Until then, the sign-off is the only marker.)
-- Commit messages follow Conventional Commits, specified in `docs/conventional-commits.md`.
-  Scope is the module or host the change belongs to (`fish`, `nvim`, `neogaia`), omitted for repo-wide changes.
-  Keep messages free of Gitea-specific references: this repository is mirrored to GitHub, where issue and pull-request numbers resolve to unrelated things.
-- When a graphical application is added, give it a `window-rewrite` icon mapping in `modules/desktop/waybar.nix`.
-  Without one its windows fall back to the generic default glyph on the workspace indicator instead of showing a recognisable per-application icon.
-  Match on the window class, which `hyprctl clients -j | jq -r '.[].class' | sort -u` lists for the running session.
-
-## Gotchas
-
-- This repo pins no Nix formatter, and its committed `.nix` files are not clean under current `nixfmt-rfc-style`.
-  Running `nixfmt` across a file reflows untouched code (for example `lib.nix`'s `deriveMac` list and multi-line assertion messages) and injects churn unrelated to the change.
-  Format only the lines being written or changed, matching the surrounding style by hand.
-- This repo is developed on `neogaia`, which now runs the NixOS it builds.
-  Flakes and the chaotic substituter come from this flake's own `nix.settings`, so no `NIX_CONFIG` export or per-command `--extra-experimental-features` is needed, and building a toplevel with `boot.kernelPackages = linuxPackages_cachyos` fetches the kernel from `nyx-cache` rather than compiling it.
-  Both were true only while the machine still ran CachyOS against a distro Nix daemon.
-- Git identity is declared in the flake by `modules/git.nix`, which writes `alexion <contact@alexion.dev>` — the identity all history uses — on any host enabling `modules.git`.
-  Every new host has to enable it, so that a host reads as a full checklist of what it carries.
-  It is deployed on `neogaia` and verified: a commit in a repository outside this checkout is authored `alexion <contact@alexion.dev>` with no override.
-  Verify it that way rather than from this checkout, whose `.git/config` carries the same identity and would mask a broken module.
-  `~/.gitconfig` (a second global file that outranks the flake-managed `~/.config/git/config`) currently holds only a `tea` credential helper and no `user.*`, so it does not shadow the identity, but it is undeclared and will not survive a reimage.
-- The primary build/verify seam for any Host is `nix flake check`, which builds `checks.x86_64-linux.<host>` (the system toplevel).
-  Cheap targeted checks use `nix eval .#nixosConfigurations.<host>.config...`.
-- chaotic-nyx must **not** follow our `nixpkgs`, and its packages are built against chaotic's own pinned nixpkgs (its overlay defaults to `onTopOf = "flake-nixpkgs"`, the cache-friendly path).
-  That is what lets the `nyx-cache.chaotic.cx` binary cache hit instead of compiling the CachyOS kernel from source.
-  The tradeoff is that chaotic packages do not see our `unstable`/`stable` overlays.
-- The remote is self-hosted Gitea (`git.alexion.dev`), and the forge CLI is `gitea-axi` rather than `tea`.
-  `gitea-axi` resolves the repository from the `origin` remote and discovers credentials from a `tea` login whose host matches the remote, so both are implicit inside a checkout.
-  It is installed on `neogaia` by `modules.agents.tools.gitea-axi`, and verified: `gitea-axi` run from this checkout renders the `alexion/dotfiles` dashboard authenticated, so the claude-code `SessionStart` hook that runs it now resolves to a real binary rather than a missing one.
-  The package wraps the binary so `git` and `tea` are reachable without being on `PATH`, while still preferring the operator's own where present.
-  Credentials: `~/.config/tea/config.yml` holds a token-bearing login named `alexion`, which `gitea-axi` uses and which also opens pull requests directly with `nix run nixpkgs#tea -- pr create --login alexion --repo alexion/dotfiles --base main --head <branch> ...`.
-  The `--repo` flag is required on that path, since `tea` resolves `origin` only for a login whose SSH host matches.
-  The same token reads PR discussion, which `tea` itself does poorly: `tea pr <n> --comments` prints only the body, and `-f comments` returns no comments field at all.
-  Use the API instead, taking the token from `.logins[] | select(.name=="alexion") | .token`.
-  Review comments are **not** at `/issues/<n>/comments` — that endpoint holds only top-level discussion and is usually empty.
-  Inline comments need two calls: `/pulls/<n>/reviews` for the review ids, then `/pulls/<n>/reviews/<id>/comments` for the bodies, whose `path` and `diff_hunk` fields say what each one is attached to.
-  A review row with an empty `body` is the normal shape when the operator left only inline comments.
-- `~/.claude/skills` is home-manager-generated (`recursive = true`), so editing a skill in place fails and a new file created there silently escapes the repo.
-  Its real source is `modules/agents/claude-code/skills/<name>/`, applied by a rebuild.
-- nixpkgs `vimPlugins.nord-nvim` is `shaunsingh/nord.nvim` (no `require("nord").setup()`).
-  The config wants `gbprod/nord.nvim`, which is packaged as `vimPlugins.gbprod-nord`.
-- `nixos-generate-config --show-hardware-config` needs root on this machine even just to print: unprivileged it dies at `Failed to retrieve subvolume info for /`, because the root filesystem is btrfs.
-- This repo's claude-code module sets sudo's credential cache to per-user (`timestamp_type=global`, 60-minute window), so an authentication made in one real terminal counts for the agent's commands.
-  A `PreToolUse` hook refuses privileged commands while the cache is cold, so a cold cache announces itself instead of stalling.
-  A privileged-command failure *without* that message is the sandbox, not the cache.
-- Host GPUs: `neogaia` is Intel, `zeus` (the desktop) is **AMD**, and `raichu` (a headless server) is the only Nvidia machine.
-  The corrected fact also lives in ADR 0003.
-- This repo's `programs.firefox` `search` (with `force = true`) writes `search.json.mozlz4`.
-  Omission alone does not prune a built-in engine, since Firefox reconciles its app-provided engines back in, so remove one by listing it with `<engine>.metaData.hidden = true`.
-  Engines are referenced by their current id, so the default is `default = "ddg"`, not `"DuckDuckGo"`.
-  Decode the built file with `mozlz4a -d <search.json.mozlz4>` to check the result.
-- `home.sessionVariables` do **not** reach the Hyprland session, since UWSM does not source `hm-session-vars.sh`.
-  The cursor is therefore set through Hyprland's own `env = KEY,VALUE` in `modules/desktop/hyprland/hyprland.nix`, sourced from `config.stylix.cursor`.
-  Bibata ships XCursor format only (no `hyprcursor/` dir), rendered through Hyprland's XCursor fallback, so `XCURSOR_*` and `HYPRCURSOR_*` naming the same theme are both safe.
+You MUST read and follow [`AGENTS.md`](AGENTS.md) before doing any work in this repository.
+`AGENTS.md` is the canonical project instruction file.
+This file exists only so Claude Code discovers that canonical instruction file.

flake.lock

@@ -494,11 +494,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1785010240,
-        "narHash": "sha256-s/3PMHATZlUzZ9p0MYZF1hhZF8AfrKVxhYFlvp9tTog=",
+        "lastModified": 1785340476,
+        "narHash": "sha256-+uVjxpCBKtwsFBhkHTtCfnCZIZa8xLzwpe1k71DM4hM=",
         "ref": "refs/heads/main",
-        "rev": "ea8e2c50bc1c1a0ab8a31f5eb807ef601d531ad6",
-        "revCount": 18,
+        "rev": "02f2017b4026cb51f04070e62bc4775a2e5d2edd",
+        "revCount": 21,
         "type": "git",
         "url": "https://git.alexion.dev/alexion/skills"
       },

modules/agents/claude-code/claude-code.nix

@@ -36,9 +36,6 @@ in
       programs.claude-code = {
         enable = true;
 
-        # The global agent-instructions file.
-        context = ./CLAUDE.md;
-
         # One directory per skill, symlinked under ~/.claude/skills.
         skills = ./skills;
 

modules/agents/context/AGENTS.md

@@ -32,9 +32,9 @@ These are common instructions for Alexion's agents across all scenarios.
   Established ecosystem or tool conventions count as a valid reason automatically (e.g. `README.md`, `LICENSE`, `CHANGELOG.md`, `Makefile`, `Dockerfile`, `.github/` files), without needing to ask each time.
 - When you discover that a belief you held about an objective fact or convention of the current project was wrong, write it down so it isn't relearned next time.
   This applies whether the user corrected you or you caught the mistake yourself, and only to things that are true regardless of who is operating the project (a wrong build command, a wrong file path, a convention you guessed at instead of checking) — not personal working-style preferences or one-off task details.
-  Record it in that project's own CLAUDE.md, not this global file, under a dedicated `## Gotchas` section (create the section if the file doesn't have one yet).
-  If the project has nested CLAUDE.md files, use the one nearest to where the mistake occurred, falling back to the project's top-level CLAUDE.md.
-  Append to an existing CLAUDE.md immediately, without asking; if no CLAUDE.md exists yet for the project, ask before creating one.
+  Record it in that project's own AGENTS.md, not this global file, under a dedicated `## Gotchas` section (create the section if the file doesn't have one yet).
+  If the project has nested AGENTS.md files, use the one nearest to where the mistake occurred, falling back to the project's top-level AGENTS.md.
+  Append to an existing AGENTS.md immediately, without asking; if no AGENTS.md exists yet for the project, ask before creating one.
   Briefly mention the edit in your response rather than making it silently.
   If an existing entry is later found to be wrong or stale, correct or remove it the same way.
 
@@ -46,7 +46,7 @@ These are common instructions for Alexion's agents across all scenarios.
   Do not write about history ("used to be X", "now moved here") or future state, about how a value is consumed elsewhere, or to justify the choice against alternatives; state the positive reason a thing exists, keeping any real stakes as a present-tense consequence.
   The only permitted cross-file mention is a bare pointer explaining why something is *absent* here (e.g. a value another tool derives, which this file therefore does not declare), never narrating what the other file or tool does.
   Do not use a project's domain-model or ubiquitous-language capitalized terms as glossary references; describe things in plain language, using ordinary lowercase nouns.
-  Never reference agent-facing state (anything under `.claude/` or `CLAUDE.md`).
+  Never reference agent-facing state (anything under `.agents/`, `.claude/`, `AGENTS.md`, or `CLAUDE.md`).
   A file-top header is one concise purpose line, added only where the filename or path does not already say it — never a feature inventory of the code below.
   For a placeholder, say so plainly plus any actionable present-tense directive ("Placeholder: regenerate with <tool> on the target machine"), never "placeholder for <missing feature>".
   User-facing documentation strings (an option's `description`, a generated help string) are documentation rather than comments, so they may describe behaviour more fully — but the self-contained rule and the bans on glossary terms and agent-state references still apply.

modules/agents/context/context.nix

@@ -0,0 +1,21 @@
+{
+  config,
+  lib,
+  ...
+}:
+# Shared global instructions for agent harnesses.
+let
+  user = config.user.name;
+  context = builtins.readFile ./AGENTS.md;
+in
+{
+  config = lib.mkMerge [
+    (lib.mkIf config.modules.agents.claude-code.enable {
+      home-manager.users.${user}.programs.claude-code.context = context;
+    })
+
+    (lib.mkIf config.modules.agents.pi.enable {
+      home-manager.users.${user}.programs.pi-coding-agent.context = context;
+    })
+  ];
+}

modules/agents/pi.nix

@@ -1,29 +0,0 @@
-{
-  config,
-  lib,
-  ...
-}:
-# Pi, a terminal coding agent, for the primary user, configured through
-# home-manager, which ships the package and manages ~/.pi/agent.
-# The login credential is left unmanaged, so it survives rebuilds.
-let
-  cfg = config.modules.agents.pi;
-  user = config.user.name;
-in
-{
-  options.modules.agents.pi.enable = lib.mkEnableOption ''
-    Pi, a terminal coding agent, configured via home-manager'';
-
-  config = lib.mkIf cfg.enable {
-    home-manager.users.${user}.programs.pi-coding-agent = {
-      enable = true;
-
-      settings = {
-        defaultProvider = "openai";
-        # Pi's catalogue id for OpenAI's Codex model, served by the ChatGPT subscription.
-        defaultModel = "gpt-5.3-codex";
-        enableAnalytics = false;
-      };
-    };
-  };
-}

modules/agents/pi/pi.nix

@@ -0,0 +1,50 @@
+{
+  config,
+  lib,
+  ...
+}:
+# Pi, a terminal coding agent, for the primary user, configured through
+# home-manager, which ships the package and manages ~/.pi/agent.
+# The login credential is left unmanaged, so it survives rebuilds.
+let
+  cfg = config.modules.agents.pi;
+  user = config.user.name;
+  piDir = "${config.users.users.${user}.home}/.pi/agent";
+in
+{
+  options.modules.agents.pi.enable = lib.mkEnableOption ''
+    Pi, a terminal coding agent, configured via home-manager'';
+
+  config = lib.mkIf cfg.enable {
+    home-manager.users.${user} = {
+      programs.pi-coding-agent = {
+        enable = true;
+
+        settings = {
+          defaultProvider = "openai-codex";
+          defaultModel = "gpt-5.5";
+          defaultThinkingLevel = "medium";
+          theme = "dark";
+          enableInstallTelemetry = false;
+          enableAnalytics = false;
+        };
+      };
+
+      home.file = {
+        # The first declarative rollout replaces the interactive settings file.
+        # Login state stays in auth.json, which this module does not manage.
+        "${piDir}/settings.json".force = true;
+
+        "${piDir}/extensions" = {
+          source = ./extensions;
+          recursive = true;
+        };
+
+        "${piDir}/prompts" = {
+          source = ./prompts;
+          recursive = true;
+        };
+      };
+    };
+  };
+}