# 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.