# AGENTS.md

## Overview
This repository contains NixOS configurations for multiple machines using flakes, home-manager, and sops-nix for secrets.

## Working with this Repository

### DO
- Use `nix fmt` or `nix fmt .` to format files before committing (uses nixfmt-tree)
- Test builds with `nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel`
- Use the included devShell run `nix develop` to get formatting and linting tools
- When adding packages, check both overlays in `flake.nix` and `home/programs/` 
- Follow the directory structure: `hosts/` for system configs, `home/` for home-manager configs
- **CRITICAL: When adding NEW files, run `git add <newfile>` BEFORE building. Nix flakes ignore untracked files in the build context, so newly added files won't be copied and builds will fail until they're git-tracked**

### DON'T
- Don't work directly on master branch, always create a new branch if editing something
- Don't run `nix flake update` to update inputs, this should only be done by the user manually
- Don't directly edit files in `secrets/` - they should be manually managed by the user
- Don't add secrets to Git
- Don't format with tools other than `nix fmt` (the formatter is defined in flake.nix)
- Don't modify `.sops.yaml` or any secrets, ask the user to do it manually
- Don't use `nix-shell` directly - use `nix develop` for the devShell environment
- Don't skip builds after configuration changes - test before pushing
- Don't mix stable and unstable packages arbitrarily in the same expression
- Don't commit without running `nix fmt` - formatted Nix is required
- **Don't try to build with newly created but untracked files - `nix build` will fail to find them**

## Specific Patterns

### Adding a New Program
- DO add to `home/packages` if no nixos or home-manager options are used.
- DO create a subdirectory in `home/programs/` if nixos or home-manager options are used.
- DO `git add` the new configuration files before attempting to build
- DON'T add programs directly to user configs unless absolutely necessary

### Modifying System Configuration
- DO check `system/` for shared configs across hosts
- DO check individual `hosts/<hostname>/` for host-specific overrides
- DON'T duplicate configuration - use `system/` modules for shared settings

### Working with Secrets
- DON'T add unencrypted secrets to the repository
- DON'T commit decrypted secrets
- DON'T add secrets, ask the user do it themselves

### Testing
- DO run `nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel` to test
- DON'T push untested configuration changes
- DON'T attempt to build configurations with newly added but untracked files

### Git
If change is small, and can be described sufficiently in the summary, dont add a long
body to the commit, prefer just the summary if sufficient.

Commits should match the format:
`topic: description of change`

Some examples:
- hyprland: convert deprecated windowrules
- packages: nixfmt-rfc-style renamed
- gunter: use beta nvidia driver


## Repository Structure Guide
- `flake.nix` - Entrypoint, inputs, overlays, and configurations
- `hosts/` - System-level NixOS configs per host
- `home/` - Home-manager configs (programs, editor, window managers)
- `system/` - Shared system modules (fonts, security, services)
- `secrets/` - Encrypted secrets (managed by sops-nix)
- `scripts/` - Utility scripts