Add artifact vault contents

projects/dotfiles/029-pi-subagents-nix-config-seam-task.md

@@ -0,0 +1,128 @@
+---
+status: done
+claimed-by: "019fba91-eabf-76ae-b086-a37ac061d6e8"
+claimed-at: "2026-07-31T22:18:42-04:00"
+completed-at: "2026-07-31T22:19:18-04:00"
+parent: "[[021-pi-subagents-config-boundary-grill]]"
+blocked-by:
+  - "[[021-pi-subagents-config-boundary-grill]]"
+tags:
+  - ticket/task/afk
+---
+
+# Pi subagents Nix config seam
+
+## Question
+
+After the subagent configuration schema is settled, what Nix/Home Manager seam should deploy `subagents.json`, managed user agent definitions, and any related defaults without making the neutral extension Nix-aware?
+
+## Result
+
+Detailed dotfiles module option design is out of scope for the subagent extension specification.
+This repository's Pi module can later decide whether to link plain files, render JSON from Nix attrs, or expose typed `modules.agents.pi.subagents` options.
+The implementation-ready extension spec should only require stable runtime file paths and should not prescribe the dotfiles module's internal interface.
+
+Keep the extension Nix-unaware.
+The extension reads Pi-native runtime files:
+
+- Global extension config: `~/.pi/agent/subagents.json`.
+- Trusted project extension config: `.pi/subagents.json` through Pi's `CONFIG_DIR_NAME`.
+- Global named agent definitions: `~/.pi/agent/agents/*.md`.
+- Trusted project named agent definitions: `.pi/agents/*.md` through Pi's `CONFIG_DIR_NAME`.
+
+The dotfiles module may choose to manage the global files declaratively, but the extension should not know or care whether they came from Home Manager, direct user edits, or another deployment tool.
+This matches the configuration boundary from [[021-pi-subagents-config-boundary-grill]].
+
+Do not create or manage `~/.pi/agent/subagents.json` until the user has actual overrides to declare.
+The extension has in-code neutral defaults and must not write a default config file automatically.
+A missing `subagents.json` is therefore a valid, expected state.
+
+When global overrides are wanted, the dotfiles Pi module may manage the runtime JSON file however the module owner prefers.
+A plain source file such as `modules/agents/pi/subagents.json` is a simple option, but it is not mandated.
+Rendering the JSON from Nix attrs or adding typed module options is a dotfiles-module decision, not an extension-spec decision.
+Do not make any particular Nix option interface a prerequisite for version one.
+
+Do not link `~/.pi/agent/agents` until there are durable user agent definitions to manage.
+An empty Home Manager-managed agent directory would make direct local experiments under `~/.pi/agent/agents` awkward, because Home Manager would own the path.
+Until durable agent definitions exist, leave the directory unmanaged so the user can create throwaway local agents freely.
+When durable agent definitions are added, create:
+
+```text
+modules/agents/pi/agents/
+```
+
+and link it with:
+
+```nix
+"${piDir}/agents" = {
+  source = ./agents;
+  recursive = true;
+};
+```
+
+The first managed `agents/` rollout should include only user-intended Markdown agent definitions.
+Do not add opinionated bundled agents as part of the neutral extension.
+
+## Current module implications
+
+`modules/agents/pi/pi.nix` already manages `~/.pi/agent/settings.json`, `~/.pi/agent/extensions`, and `~/.pi/agent/prompts`.
+It intentionally leaves login credential state unmanaged.
+Source: `modules/agents/pi/pi.nix`.
+
+The implementation spec should extend that module only when there is an actual file or directory to deploy.
+The extension code itself should still live under:
+
+```text
+modules/agents/pi/extensions/subagents/
+```
+
+and the existing recursive extension link will deploy it.
+No package installation or `pi install` path is needed for version one.
+
+## Recommended version-one Nix stance
+
+Only the deployment paths are in scope here:
+
+- `modules/agents/pi/extensions/subagents/` for the extension implementation.
+- `~/.pi/agent/subagents.json` as the optional runtime config target.
+- `~/.pi/agent/agents/*.md` as the optional global named-agent target.
+
+Avoid these in the extension specification:
+
+- Prescribing typed `modules.agents.pi.subagents.*` options.
+- Prescribing a plain-file versus generated-json module implementation.
+- Requiring a generated default `subagents.json` when no overrides exist.
+- Requiring an empty managed `~/.pi/agent/agents` directory.
+- Nix-aware logic in the extension.
+- `pi install` or package-manager-managed Pi packages.
+
+## Verification commands
+
+Before implementation, existing checks still apply:
+
+```bash
+nix eval .#nixosConfigurations.neogaia.config.modules.agents.pi.enable
+```
+
+Expected result: `true`.
+
+```bash
+nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.home.file.'"/home/alexion/.pi/agent/extensions"'.source
+```
+
+Expected result: a Nix store path sourced from `modules/agents/pi/extensions`.
+
+If the dotfiles module later manages `subagents.json` or `agents/`, verify the resulting Home Manager file entries with targeted `nix eval` commands chosen for that module implementation.
+The exact attr paths depend on whether the module uses plain file links, generated JSON, or typed options, so they are intentionally left to that later dotfiles-module work.
+
+Before merging any implementation, run the repository's primary verification seam:
+
+```bash
+nix flake check
+```
+
+## Implementation-spec notes
+
+The implementation spec should state that missing global config and missing global agent directory are normal.
+The extension should create neither automatically.
+The extension may expose an explicit user-command to print or write a starter config later, but only after the user requests it.