nix-darwin/AGENTS.md

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.