# AGENTS.md - NixOS Flake Configuration

## Before Starting Work

Run `hostname` to identify current machine. Hostname = flake config name (e.g., `frame12` → `.#frame12`).

## Repository Structure

```
flake.nix           # Defines all nixosConfigurations
<hostname>/         # Per-host configs (frame12, nate, jaci, scrappy, nate-work, luci)
  default.nix       # Host entry point, sets deskCfg or serverConfig
  desktop-configuration.nix  # Desktop systems only
  modules/          # Host-specific modules (niri, home-manager, user)
  nixos/hardware-configuration.nix  # Auto-generated, do not edit
shared/             # Reusable modules imported by hosts
  modules/          # apps/, home-manager/, services/, system/, user/
  server-configuration.nix  # Server base (luci uses this)
```

**Host types:**
- **Desktop** (frame12, nate, jaci, nate-work, scrappy): Use `deskCfg` options, Home Manager, Stylix theming
- **Server** (luci): Uses `serverConfig` options, minimal packages

## Build/Test Commands

```bash
nix flake check                    # Validate syntax
nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel --dry-run
# Must be done by user, agent lacks admin privileges.
sudo nixos-rebuild test --flake .#<hostname>  # Test without switching
sudo nixos-rebuild switch --flake .#<hostname>  # Apply changes
```

## Key Patterns

**Configuration options:** Desktops set `deskCfg = { userName, hostName, de }`, servers set `serverConfig = { userName, hostName, hostId, ... }`

**Module structure:** Options in `options.<name>`, config in `config = lib.mkIf cfg.enable { ... }`

**Home Manager:** User config in `<host>/modules/home-manager/home.nix`, packages in `home.packages`

**Shared imports:** `../shared/modules/<path>` for reusable modules

## Code Style

- Nix expression language, 2-4 space indent
- camelCase options (`userName`), kebab-case hostnames, underscores for modules (`main_user`)
- `lib.mkOption` with types (`lib.types.str`, `lib.types.bool`), `lib.mkEnableOption` for toggles
- `lib.mkIf` for conditionals, `lib.mkMerge` for combining sets
- Minimal comments; use self-documenting option descriptions