feat: add AGENTS.md

AGENTS.md

@@ -0,0 +1,69 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository is a declarative macOS setup built with Nix flakes.
+
+- `flake.nix` and `flake.lock`: entrypoint and pinned inputs.
+- `modules/`: system-level nix-darwin modules (`nix-core.nix`, `system.nix`,
+  `apps.nix`, `host-users.nix`).
+- `home/`: Home Manager user configuration, with feature modules such as
+  `git.nix`, `zsh.nix`, and `nvf/`.
+- `secrets/`: encrypted SOPS files (for example `secrets/poby.yaml`).
+- `Justfile`: day-to-day contributor commands.
+
+Prefer adding new configuration as small focused modules, then importing them
+from `home/default.nix` or `flake.nix`.
+
+## Build, Test, and Development Commands
+
+Use `just` as the primary interface:
+
+- `just darwin <hostname>`: build and switch to the current host (ex: `fenrir`).
+- `just darwin-debug <hostname>`: same as above with verbose trace output.
+- `just fmt`: format all Nix files via `nix fmt` (Alejandra).
+- `just up`: update all flake inputs.
+- `just upp <input>`: update one input (example: `just upp nixpkgs-darwin`).
+- `just history`, `just gc`, `just clean`: inspect and prune Nix
+  generations/store.
+
+For validation without switching, run:
+`nix build .#darwinConfigurations.fenrir.system --extra-experimental-features 'nix-command flakes'`.
+
+## Coding Style & Naming Conventions
+
+- Use 2-space indentation in `.nix` files and keep attribute sets readable.
+- Run `just fmt` before committing; formatter is defined in `flake.nix`
+  (`alejandra`).
+- Name module files in lowercase kebab-case (example: `host-users.nix`).
+- Keep modules single-purpose and compose through `imports`.
+
+## Testing Guidelines
+
+There is no dedicated unit-test suite in this repo. Treat evaluation/build as
+the test gate:
+
+- Run `just fmt`.
+- Run `nix build .#darwinConfigurations.fenrir.system`.
+- Use `just darwin-debug` when diagnosing evaluation/runtime issues.
+
+Document manual verification for user-facing changes (shell, terminal, window
+manager, app defaults).
+
+## Commit & Pull Request Guidelines
+
+Commit history follows Conventional Commit style: `feat:`, `fix:`, `refactor:`,
+`style:`.
+
+- Keep subject lines imperative and concise.
+- Scope each commit to one logical change.
+- In PRs, include: summary, affected modules/paths, command output used for
+  validation, and any relevant screenshots for UI changes (for example
+  WezTerm/AeroSpace behavior).
+
+## Security & Configuration Tips
+
+- Never commit plaintext secrets.
+- Store secrets only in `secrets/*.yaml` and manage keys/rules in `.sops.yaml`.
+- If adding new secret files, ensure `path_regex` coverage and encrypted content
+  before pushing.