diff --git a/agents.md b/agents.md
new file mode 100644
index 0000000..d255344
--- /dev/null
+++ b/agents.md
@@ -0,0 +1,28 @@
+# NixOS Repository Quick Reference
+
+## Quick Commands
+- **Test build**: `nixos-rebuild build --flake .#<system>`
+- **List systems**: `nix flake show`
+- **Commit**: `git add files && git commit -m "msg"`
+
+## Systems
+- **warp**: Server + nginx + forgejo
+- **skip**: Server + nginx only
+- **framework/aurora/labrizor**: Desktop systems
+
+## Key Files
+- `flake.nix`: System definitions
+- `systems/<name>.nix`: Hardware/boot configs
+- `servers/<name>.nix`: Service configs
+- `users/<name>.nix`: User configs
+
+## Testing Workflow
+1. Always `git status` first - affects flake evaluation
+2. Stage changes (`git add`) before building - prevents Nix store issues
+3. Test with `nixos-rebuild build --flake .#<system>`
+4. Check success message: `"Done. The new configuration is /nix/store/..."`
+
+## Important
+- Server configs may contain hardcoded credentials - use agenix or systemd credentials for production
+- Both warp and skip build successfully
+- Repository root: `/home/jsutter/src/nixos`