lux/AGENTS.md

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.