lux/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This repository is a simplified flake-parts NixOS flake. flake.nix imports ./modules through import-tree, so normal .nix files under modules/ are loaded automatically unless their file or directory name starts with _.

• modules/flake-parts.nix defines the flake-parts setup, formatter, and the exported nixosConfigurations.
• modules/hosts/<name>/default.nix defines one top-level flake.modules.nixos.<host> module and assembles that machine by importing reusable features, user modules, and host-local helpers.
• modules/hosts/<name>/_*.nix are private host-local helper modules such as hardware and disk layout files.
• modules/users/<name>.nix defines one reusable NixOS user module and the baseline Home Manager imports for that account.
• modules/features/*.nix contains reusable NixOS and Home Manager feature modules.
• modules/features/<feature>/default.nix is used when a feature needs private helper files, for example niri/_bindings.nix.
• modules/features/services/*.nix contains reusable service-oriented NixOS modules.
• modules/secrets/sops.nix wires sops-nix for both NixOS and Home Manager.
• modules/secrets/secrets.yaml stores encrypted secrets, with .sops.yaml defining SOPS creation rules.
• modules/_treefmt.nix configures repository formatting.

Keep host files thin. Shared behavior belongs in modules/features/ or modules/users/. Host files should mainly compose imports and hold host-only settings such as monitor layouts, hardware quirks, boot tweaks, and machine-local firewall or service choices.

Mental Model

This repo is direct module composition around flake.modules, not the old inventory-driven dendritic design.

• Reusable building blocks are exposed as flake.modules.nixos.<name> and flake.modules.homeManager.<name>.
• Host modules are the composition root. They import the reusable NixOS modules they need, enable Home Manager, and add any host-specific Home Manager imports inline.
• User modules define the Unix user plus that account’s baseline Home Manager setup.
• There is no config.repo, inventory schema, profiles layer, or attachment builder anymore.

In practice:

• Prefer importing a feature module directly over inventing a repo-local option just to toggle it.
• Put cross-host reusable behavior in modules/features/.
• Put account-specific defaults in modules/users/.
• Keep private helper files _-prefixed so import-tree does not expose them as top-level modules.
• Match the existing split between NixOS composition in host modules and Home Manager composition in user or host modules.

Current Host Composition

There are three exported hosts:

• orion: server-oriented host with kiri, SOPS, and service modules such as Caddy, Gitea, Vaultwarden, Radicale, Actual, and OpenSSH.
• polaris: graphical desktop host with kiri and ergon, hardware imports, Niri, Steam, local desktop features, and host-specific monitor layout.
• zenith: graphical laptop host with kiri and ergon, Niri, laptop hardware support, firmware updates, and host-specific monitor layout.

When adjusting user-facing software, check whether it belongs in:

• a user baseline in modules/users/<name>.nix
• a reusable Home Manager feature in modules/features/*.nix
• a host-local extension inside modules/hosts/<name>/default.nix

Be careful not to move host-specific Home Manager imports into a user baseline unless that behavior should apply on every host that imports that user module.

Validation And Development Commands

Run commands from the repository root.

• nix build --no-link --show-trace .#nixosConfigurations.<host>.config.system.build.toplevel: baseline validation for one host.
• nix build --no-link --show-trace .#nixosConfigurations.orion.config.system.build.toplevel .#nixosConfigurations.polaris.config.system.build.toplevel .#nixosConfigurations.zenith.config.system.build.toplevel: validate all defined hosts in one invocation.
• nixos-rebuild build --flake .#<host>: use when you specifically want nixos-rebuild semantics without activation.
• nix eval --json .#nixosConfigurations.<host>.config.<option>: inspect a single evaluated option while iterating.
• nix fmt: format the repository using the flake-provided formatter from modules/_treefmt.nix.
• nix store diff-closures <old> <new>: compare built system closures when reviewing refactors for parity or regressions.

This repo does not define a first-party checks output. Validation is primarily host builds plus targeted nix eval checks.

Coding Style & Naming Conventions

Use two-space indentation and standard Nix attrset formatting. Prefer small let bindings, lowerCamelCase local names, and lowercase file names.

• Define reusable modules as flake.modules.nixos.<name> or flake.modules.homeManager.<name>.
• Keep one obvious feature per file or directory.
• Use default.nix only when the feature needs private helper files alongside it.
• Match surrounding style instead of reformatting unrelated code.
• Prefer explicit host imports over hidden indirection.

Commit

Follow the existing history style: short imperative subjects, optionally with a conventional prefix, for example refactor: simplify host composition.

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 and cautious with changes to:

• firewall and OpenSSH settings
• disk layout and boot configuration
• SOPS key handling and admin user access
• firmware, hardware, and authentication settings
• host-vs-user module boundaries, because it is easy to accidentally broaden behavior to the wrong machines