refactor(nixos): scope agent guidance

docs/00 INBOX/ai/nixos-agents-style-scope-design-tree.md

@@ -0,0 +1,130 @@
+# NixOS AGENTS and style-skill scope design tree
+
+This tree reviews `configs/nixos/AGENTS.md`.
+It decides which instructions belong in Nix style rules.
+
+## Known facts
+
+- `configs/nixos/AGENTS.md` has 70 lines.
+- Each frontier question quotes the complete instruction under review.
+- This review decides instruction placement only.
+- It supplies guidance for desktop, Firefox, Neovim, AI tooling, and NixOS gotchas.
+- The `/review` prompt loads `nix-style` for Nix files.
+- `nix-style` loads every rule under `src/skills/style/nix/rules/`.
+- The current Nix rules cover Nix syntax and flake structure.
+- `configs/nixos/AGENTS.md` includes a guest-module ownership rule.
+- The RomM session missed that ownership rule during implementation.
+- `registry.window-icon` exists in `configs/nixos/registry/window-icon.nix`.
+- Desktop application modules declare window classes and rendered icons in that registry.
+- Hyprland reads the registry to generate workspace icon mappings.
+- The AGENTS instruction named the registry after its introduction on 2026-10-11.
+- The `class` option describes its window-class match.
+- The `icon` option describes a string icon value.
+- The registry schema does not document the rendered-string requirement or the class-discovery command.
+- Hyprland renders `config.registry.env` as its `env` configuration.
+- The `env` registry replaced direct Hyprland environment declarations in commit `370cab8f8`.
+- `configs/nixos/modules/desktop/apps/r2modman.nix` enables a graphical application without a `registry.window-icon` declaration.
+- The current registry modules already validate value uniqueness and field combinations.
+- They do not validate required producer declarations.
+- The registry collector is specific to the NixOS dotfiles configuration.
+- A non-discoverable environment fact records local behavior that configuration, source code, and normal tool help do not reveal.
+- The current instruction groups are:
+  - Desktop: window icons, Hyprland environment variables, and cursor settings.
+  - Firefox: search-engine declarations and extension-storage compatibility.
+  - Neovim: Nixvim package-set selection.
+  - AI tooling: Herdr key names and Pi configuration locations.
+  - Gotchas: registry APIs, guest boundaries, SOPS ownership, guest mounts, deployment, DNS, hardware, module paths, and host commands.
+
+## Decision tree
+
+- Instruction review
+  - Settled: Review each complete instruction in source order.
+  - Registry conventions
+    - Settled: Create `src/skills/style/nix/rules/dotfiles.md`.
+    - Graphical application icon instruction
+      - Settled: Move the complete instruction to `src/skills/style/nix/rules/dotfiles.md`.
+    - Hyprland session environment instruction
+      - Settled: Remove it because `registry.env` superseded it.
+    - Firefox search-engine instruction
+      - Settled: Remove it because the Firefox module documents the configuration.
+    - Firefox extension-storage instruction
+      - Settled: Move it to a comment above `extensions.settings` in `modules/desktop/apps/firefox.nix`.
+    - Neovim package-set instruction
+      - Settled: Move it to a comment above `nixpkgs.useGlobalPackages` in `modules/shell/nvim/default.nix`.
+    - Herdr key-name instruction
+      - Settled: Remove it.
+    - Pi extension location instruction
+      - Settled: Remove it. It recorded a completed migration from NixOS-managed sources.
+    - Pi generated-settings instruction
+      - Settled: Remove it because the Pi module documents the managed boundary.
+    - Library-function qualification instruction
+      - Settled: Generalize it and move it to `src/skills/style/nix/rules/general.md`.
+    - Guest ownership instruction
+      - Settled: Move it to `src/skills/style/nix/rules/dotfiles.md`.
+    - SOPS guest-owner instruction
+      - Settled: Move it to `src/skills/style/nix/rules/dotfiles.md`.
+    - Nested guest-mount instruction
+      - Settled: Remove it because the example describes no active layout.
+    - `deploy-to` instruction
+      - Settled: Remove it. Agents cannot complete its remote sudo steps.
+    - Pikachu deploy-closure instruction
+      - Settled: Remove it because `deploy-to` encodes the required import path.
+    - Public-DNS instruction
+      - Settled: Remove it.
+    - Hardware-configuration instruction
+      - Settled: Remove it because the root auto-generated-file rule owns the policy.
+    - Chaotic-cache instruction
+      - Settled: Remove it because `modules.host.cachyos.enable` owns the cache configuration.
+    - Module-relative-path instruction
+      - Settled: Remove it because Nix evaluation reports invalid paths.
+    - Pikachu `uptime` instruction
+      - Settled: Remove it because the command exposes its supported options.
+    - Guest-ACME-evaluation instruction
+      - Settled: Remove it because current direct guest evaluation succeeds.
+    - systemd executable instruction
+      - Settled: Remove it because `general.md` already requires `lib.getExe'` for non-main executables.
+
+## Frontier
+
+The frontier is empty.
+
+## Shared understanding
+
+Remove these instructions from `configs/nixos/AGENTS.md`:
+
+- Hyprland session environment
+- Firefox search engines
+- Herdr shifted punctuation
+- Pi extension source location
+- Pi managed settings
+- Nested guest mounts
+- `deploy-to` behavior
+- Pikachu deploy closures
+- Public DNS boundary
+- Hardware configuration
+- Chaotic cache selection
+- Module-relative paths
+- Pikachu boot time
+- Guest ACME evaluation
+- systemd executable selection
+
+Move these instructions intact to `src/skills/style/nix/rules/dotfiles.md`:
+
+- Graphical application icons
+- Guest ownership
+- SOPS guest ownership
+
+Move the generalized library-function qualification convention to
+`src/skills/style/nix/rules/general.md`.
+
+Move these instructions to code comments:
+
+- Firefox extension storage: above `extensions.settings` in
+  `configs/nixos/modules/desktop/apps/firefox.nix`
+- Nixvim package set: above `nixpkgs.useGlobalPackages` in
+  `configs/nixos/modules/shell/nvim/default.nix`
+
+The review does not decide how to restore the auto-generated status of
+`configs/nixos/hosts/pikachu/hardware-configuration.nix`.
+
+The operator confirmed this design and authorized the edits.