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>