From 6ef3f87d160be81737037d1f4393dcdaefb79559 Mon Sep 17 00:00:00 2001 From: ahuston-0 Date: Fri, 1 May 2026 01:23:19 -0400 Subject: [PATCH] add agents.md --- AGENTS.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..478673d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,105 @@ +> 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//default.nix`: Per-host parameters (users, home, sops, server role, extra modules). +- `systems//configuration.nix`: Main host config. +- `modules/*.nix`: Global modules automatically imported into all systems. +- `users//home.nix` and `users//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//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 .#`. +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//secrets.yaml` and `users//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//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//home.nix` and `users//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....`. + +## 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 .#` +- `nix flake check` +- `nix eval .#nixosConfigurations..config.`