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

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;
+        };
+      };
+    };
+  };
+}