nixos/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• hosts/<host>/configuration.nix defines each machine; host modules, packages, and site configs live alongside for composability.
• Shared building blocks sit in utils/ (modules/, overlays/, pkgs/, bento.nix), while fleet.nix centralizes cross-host user provisioning.
• Provisioning assets (ISO profiles, Raspberry Pi imaging, helper scripts) live under iso/, raspberry*/, and scripts/—refer to them before reinventing steps.

Build, Test, and Development Commands

• Enter the dev shell via nix-shell (uses shell.nix) to populate MCP helper configs and standard tooling.
• Dry-run any change with ./scripts/test-configuration <host>; append -v to mirror nixos-rebuild --show-trace for deeper diagnostics.
• Deployment relies on the Git runner—once reviewed changes merge to main, the runner rebuilds and switches the relevant host automatically; treat a clean dry-run as the gate before pushing.

Coding Style & Naming Conventions

• Format Nix files with two-space indentation; run nixpkgs-fmt (via nix run nixpkgs#nixpkgs-fmt .) before committing complex edits.
• Keep module and derivation names in lower kebab-case (web-arm, home-assistant.nix) and align attribute names with actual host or service identifiers.
• Use comments sparingly to justify non-obvious decisions (open ports, unusual service options) and prefer explicit imports over wildcard includes.

Testing Guidelines

• Always run ./scripts/test-configuration <host> before raising a PR; it ensures evaluation succeeds and secrets are present.
• For service changes, confirm activation with nixos-rebuild test (or switch) on a staging machine and capture any notable logs.
• Document manual smoke checks (e.g., URLs defined in hosts/web-arm/sites/) in the PR so reviewers can repeat them quickly.

Commit & Pull Request Guidelines

• Follow the Conventional Commits pattern used in git log (fix:, chore:, update:) and scope by host when helpful (fix(mail):).
• Split refactors, secrets rotations, and package bumps into distinct commits to simplify review and rollback.
• PRs should call out affected hosts, link dry-build output (and confirm the runner result after merge), and tag the owners noted in hosts/<host>/users/*.nix; attach screenshots for UI-facing updates.

Security & Configuration Tips

• Configure config.sh before provisioning SFTP users so the values consumed by fleet.nix stay in sync with the chroot layout.
• Store API keys referenced in shell.nix (such as the Brave Search token) under ~/.config/mcp-servers/ and keep real secrets out of version control.
• Rotate and edit encrypted hosts/<host>/secrets.yaml via nix-shell -p sops --run 'sops hosts/<host>/secrets.yaml'; commit only the encrypted output.