nix-dotfiles/AGENTS.md

> Note: This document was AI-generated and reviewed by a maintainer.

# AGENTS Guide for nix-dotfiles

This file is the quick-start map for coding agents working in this repository.
Use this first, then follow the linked source files for full detail.

## Purpose and Scope

- Repository type: flake-based NixOS + Home Manager dotfiles/infrastructure.
- Primary goals: safe system/user config edits, reproducible builds, and clean secrets handling.
- Default assumption: preserve existing module patterns and avoid broad refactors unless requested.

## Source of Truth

Read these files before substantial changes:

- `.github/copilot-instructions.md`: Full repository guide for structure, workflows, dynamic system generation, module patterns, and SOPS handling.
- `.github/instructions/ai-doc-attribution.instructions.md`: Markdown rule for top-of-document attribution when docs are fully AI-generated.
- `flake.nix`: Flake inputs/outputs entrypoint; system generation begins here.
- `lib/systems.nix`: Core dynamic config assembly (`genSystems`, `constructSystem`, and wrapper generators).
- `systems/<hostname>/default.nix`: Per-host parameters (users, home, sops, server role, extra modules).
- `systems/<hostname>/configuration.nix`: Main host config.
- `modules/*.nix`: Global modules automatically imported into all systems.
- `users/<username>/home.nix` and `users/<username>/default.nix`: Home Manager and user account configuration.
- `hydra/jobs.nix` and `hydra/jobsets.nix`: CI/build orchestration details.

## Repo Mental Model

- `systems/` contains host-specific configs.
- `modules/` contains global modules applied across hosts.
- `users/` contains user and home-manager configs.
- `lib/systems.nix` auto-discovers hosts and composes final configs.
- SOPS secrets are colocated with hosts/users via `secrets.yaml` files.

## Dynamic Configuration Rules

- Hosts are auto-discovered from subdirectories in `systems/`.
- Each host's `default.nix` feeds `constructSystem` parameters.
- Effective module merge order matters. High-level order is: 1) base external
  modules, 2) host essentials (`hardware.nix`, `configuration.nix`), 3)
  host-specific modules from `systems/<host>/default.nix`, 4) global
  `modules/*.nix`, 5) optional SOPS and Home Manager/user layers.
- Global modules load after host config, so explicit overrides may require `lib.mkForce` depending on target option.

## Editing Conventions

- Keep changes minimal and scoped to the requested behavior.
- Preserve existing Nix style and option naming patterns.
- Prefer module options + `lib.mkIf` toggles over hard-coded behavior.
- Use `lib.mkDefault` for soft defaults and `lib.mkForce` only when necessary.
- Do not commit plaintext secrets.
- Update docs when behavior/workflow changes.

## Validation and Workflow

Typical local sequence:

1. Make targeted edits.
2. Evaluate and build with `nix flake check` and `nix build .#<hostname>`.
3. Optionally deploy/apply with `nh os switch` or `nh home switch`.
4. For secrets-related changes, edit with `sops .../secrets.yaml` and validate expected `config.sops.secrets` evaluation paths.

## Secrets and Safety

- Secrets live in `systems/<hostname>/secrets.yaml` and `users/<username>/secrets.yaml`.
- Use SOPS for create/edit/rekey operations.
- During merge conflicts in encrypted files, prefer repository SOPS merge tooling (`utils/sops-mergetool.sh`, `utils/sops-mergetool-new.sh`).

## Agent and Tool Routing

When a specialized agent is available, route work by intent:

- `Explore`: Fast read-only repository exploration and Q&A.
- `dependency-auditor`: Flake/module dependency security and CVE-oriented audits.
- `security-researcher`: Read-only server security configuration audits.
- `server-architect`: Server integration/review planning for `palatine-hill` style infra changes.

Use Nix lookup tooling for package/options discovery; prefer `unstable` channel when channel selection is available.

## Where To Look Next (By Task)

- Add a new host: see `.github/copilot-instructions.md` sections on "Adding a New NixOS System", plus `systems/<new-host>/default.nix`, `hardware.nix`, and `configuration.nix`.
- Add/modify a global capability: see `modules/*.nix` and the `.github/copilot-instructions.md` section "Adding a Global Module to modules/".
- Change user/home-manager behavior: see `users/<username>/home.nix` and `users/<username>/default.nix`.
- Modify build/release automation: see `hydra/jobs.nix` and `hydra/jobsets.nix`.
- Work with secrets: see `.sops.yaml`, `systems/*/secrets.yaml`, `users/*/secrets.yaml`, and the `.github/copilot-instructions.md` section "Secrets Management".
- Validate module composition/debug evaluation: see `lib/systems.nix` and `nix eval .#nixosConfigurations.<host>...`.

## Documentation Attribution Rule

For Markdown docs (`**/*.md`):

- If a document is fully AI-generated, include explicit attribution near the top.
- Accepted label includes "AI-generated documentation" wording.
- Do not imply fully human authorship for fully AI-authored content.

## Quick Command Reference

- `nh os build`
- `nh os switch`
- `nh home switch`
- `nix build .#<hostname>`
- `nix flake check`
- `nix eval .#nixosConfigurations.<hostname>.config.<path>`