# AGENTS.md - NixOS Configuration Repository

This file provides guidance for AI coding assistants working on this NixOS configuration.

## Repository Overview

This is a NixOS system configuration for a desktop named "atlas". It uses flakes, modular organization, and includes customizations for gaming, development, and daily desktop use.

## Build/Validation Commands

```bash
# Validate Nix syntax and build configuration
nix flake check

# Build the configuration (dry-run, doesn't activate)
nixos-rebuild dry-build --flake .

# Format all .nix files with nixfmt
nixfmt **/*.nix

# Check for common issues
nixos-rebuild dry-activate --flake .
```

## Code Style Guidelines

### File Organization
- Entry point: `configuration.nix`
- Flake definition: `flake.nix`
- Modular structure under `modules/` organized by category:
  - `core/` - Boot, system, networking, users, localization
  - `hardware/` - GPU, audio, storage, power management
  - `desktop/` - Window manager, apps, theming, portals
  - `services/` - System services (avahi, printing, navidrome)
  - `dev/` - Development tools, docker, shells
  - `gaming/` - Steam, wine, gamemode

### Module Pattern
Each module follows this structure:
```nix
# modules/<category>/<name>.nix
# Brief description of what this module configures
{
  config,
  pkgs,
  lib,
  inputs,      # Only if using flake inputs
  username,    # Custom arg passed from flake
  ...
}:

{
  # Configuration options here
}
```

### Imports Pattern
`default.nix` files should only contain imports:
```nix
# modules/<category>/default.nix
{
  imports = [
    ./boot.nix
    ./system.nix
  ];
}
```

### Formatting Rules
- Use 2-space indentation
- No tabs
- Keep lines under 100 characters when possible
- Add blank lines between logical sections
- Use descriptive comments with `# Description` format

### Naming Conventions
- Module files: descriptive lowercase with hyphens (e.g., `gpu-amd.nix`)
- Use `username` variable from flake for user-specific paths
- Use `lib.mkIf` for conditional configuration
- Use `lib.mkDefault` for values that can be overridden

### Input Handling
- Pass `inputs` from flake when accessing external packages
- Access input packages via: `inputs.<name>.packages.${pkgs.stdenv.hostPlatform.system}.default`
- Use `pkgs.stdenv.hostPlatform.system` for system-specific packages

### Special Files
- `hardware-configuration.nix` - Generated by nixos-generate-config, DO NOT EDIT
- Scripts in `scripts/` are bash installers (not part of NixOS config)
- Overlays contain patched Python scripts

### Security Notes
- Never commit secrets, API keys, or tokens
- Sensitive files are in `.gitignore`
- Use proper LUKS encryption for swap and root partitions
- Secure Boot is enabled with custom Limine patches

## Common Tasks

### Adding a New Module
1. Create file in appropriate `modules/<category>/` subdirectory
2. Add to the category's `default.nix` imports
3. Follow existing module structure and formatting
4. Add brief header comment describing purpose

### Adding a Package
- System packages: add to `environment.systemPackages` in appropriate module
- User packages: prefer adding to system packages for shared use
- Flake packages: access via inputs with proper system attribute

### Testing Changes
```bash
# Before committing, always verify syntax
nix flake check

# Build to catch evaluation errors
nixos-rebuild dry-build --flake .
```

## Dependencies

External flake inputs:
- `nixpkgs` - Main NixOS packages (nixos-unstable)
- `noctalia` - Desktop shell
- `nix-cachyos-kernel` - CachyOS kernel with optimizations
- `zen-browser` - Zen browser
- `opencode` - AI coding assistant