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

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.