Initial commit

AGENTS.md

@@ -0,0 +1,39 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+This repository is a Den-based NixOS flake. `flake.nix` evaluates `./modules` through `import-tree`, so normal `.nix` files under `modules/` are auto-imported.
+
+- `modules/hosts/` contains host-specific composition and hardware data for `polaris` and `orion`.
+- `modules/features/` contains aspects such as desktop, shell, services, and Neovim.
+- `modules/profiles/` holds higher-level bundles such as `workstation.nix`.
+- `modules/users/` defines user metadata and per-user behavior.
+- `modules/secrets/` wires `sops-nix` and stores the encrypted `secrets.yaml`.
+- `.agents/den/` is a local checkout of Den with source, docs, and examples.
+
+Keep host files thin. Shared behavior belongs in `modules/features/` or `modules/profiles/`.
+When Den behavior is unclear, read `.agents/den/docs/`, `.agents/den/modules/`, and `.agents/den/templates/ci/` before guessing.
+
+## Build, Test, and Development Commands
+Run commands from the repository root.
+
+- `nix build .#nixosConfigurations.polaris.config.system.build.toplevel --show-trace`: evaluate and build the Polaris system.
+- `nix build .#nixosConfigurations.orion.config.system.build.toplevel --show-trace`: evaluate and build the Orion system.
+- `nixos-rebuild build --flake .#<host>`: use the standard rebuild path without activating it.
+- `nix fmt`: format Nix files using the flake-provided formatter.
+- `nix eval .#nixosConfigurations.<host>.config.<option>`: inspect a single option while iterating.
+
+`nix flake check` is useful for evaluation, but this repo does not define an automated test suite.
+
+## Coding Style & Naming Conventions
+Use two-space indentation and standard Nix attrset formatting. Prefer small `let` bindings, lowerCamelCase local names, and lowercase file names such as `sops-password.nix`. Match the surrounding module style instead of reformatting unrelated code.
+
+Prefer Den composition through `includes`; avoid host-specific duplication when a reusable aspect is clearer.
+
+## Testing Guidelines
+There are no first-party unit tests. Treat evaluation and build-only checks as the baseline. For scoped changes, run the matching `nix build` target first, or `nixos-rebuild build --flake .#<host>` when you want the standard rebuild path without activation. Activation and switching are manual steps and should not be performed by contributors or agents.
+
+## Commit
+Follow the history style: short imperative subjects, optionally with a conventional prefix, for example `refactor: restructure openssh config`. Keep each commit focused on one concern.
+
+## Security & Configuration Tips
+Never commit plaintext secrets. Add or update secrets through `modules/secrets/secrets.yaml` and reference them via `config.sops.secrets.<name>.path`. Be explicit about firewall, SSH, disk, or boot changes; those are the highest-risk edits here.