# AGENTS.md: Nix flakes

## Commands
- Enter the dev environment: `nix develop` (or `direnv allow` with `use flake`). Run tools from inside it.
- Build: `nix build .#<package>` · Checks: `nix flake check` · Format: `nix fmt` (configured formatter, e.g. `nixfmt`)
- Update inputs only when asked: `nix flake update <input>`; commit `flake.lock` changes separately.

## Rules
- All inputs are pinned in `flake.lock`. Never use channels or `<nixpkgs>` lookup paths in new code; get packages from the flake's `nixpkgs` input.
- Support the systems the project lists (use `nixpkgs.lib.genAttrs` or `flake-utils`/`flake-parts` as already used). Don't hard-code `x86_64-linux` unless the flake does.
- Dev shells: add tools to `devShells.<system>.default` (`pkgs.mkShell { packages = [ ... ]; }`) instead of telling users to install them globally. Keep shell hooks minimal.
- Packages use the right builder for the language (`buildGoModule`, `rustPlatform.buildRustPackage`, `buildNpmPackage`, `python3Packages.buildPythonApplication`) with fixed-output hashes. When a hash changes, use `lib.fakeHash`, build, and copy the hash from the error.
- Use `lib` functions and `inherit` to keep expressions readable; split large flakes into `nix/*.nix` files.
- NixOS/home-manager modules expose `options` with types and descriptions and use `lib.mkIf cfg.enable`.
- Never put secrets in Nix expressions (they end up world-readable in `/nix/store`); use sops-nix/agenix.

## Done
`nix flake check` and `nix build` succeed, and `nix fmt` leaves no diff.