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.

Justfile

@@ -1,8 +1,5 @@
 # just is a command runner, Justfile is very similar to Makefile, but simpler.
 
-# FIXME update hostname here!
-hostname := "fenrir"
-
 # List all the just commands
 default:
   @just --list
@@ -14,14 +11,14 @@ default:
 ############################################################################
 
 [group('desktop')]
-darwin:
+darwin hostname:
   nix build .#darwinConfigurations.{{hostname}}.system \
     --extra-experimental-features 'nix-command flakes'
 
   sudo -E ./result/sw/bin/darwin-rebuild switch --flake .#{{hostname}}
 
 [group('desktop')]
-darwin-debug:
+darwin-debug hostname:
   nix build .#darwinConfigurations.{{hostname}}.system --show-trace --verbose \
     --extra-experimental-features 'nix-command flakes'
 
@@ -70,9 +67,9 @@ gc:
   nix-collect-garbage --delete-older-than 7d
 
 [group('nix')]
-fmt:
+fmt range:
   # format the nix files in this repo
-  nix fmt
+  nix fmt {{range}}
 
 # Show all the auto gc roots in the nix store
 [group('nix')]

home/nvf/lsp/languages/nix.nix

@@ -10,10 +10,7 @@
   };
   format = {
     enable = true;
-    type = [
-      "alejandra"
-      "nixfmt"
-    ];
+    type = [ "alejandra" ];
   };
   lsp = {
     enable = true;