From 185087e479de4c57130ce2820ccd57149d121e51 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Torjus=20H=C3=A5kestad?= <torjus@usit.uio.no>
Date: Fri, 30 Jan 2026 15:00:10 +0100
Subject: [PATCH] vibecoding: add AGENTS.md

---
 AGENTS.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6eba75e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,71 @@
+# 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