# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

This is "Atlas" - a modular, flake-based NixOS configuration for a desktop workstation. The system is AMD-specific (CPU + GPU) and optimized for gaming, development, and daily use.

## Common Commands

```bash
# Test configuration without switching (validate before applying)
sudo nixos-rebuild test --flake .#nixos

# Apply configuration
sudo nixos-rebuild switch --flake .#nixos

# Build and set as boot default (without switching)
sudo nixos-rebuild boot --flake .#nixos

# Update all flake inputs
nix flake update

# Update specific input
nix flake lock --update-input nixpkgs

# Garbage collection
sudo nix-collect-garbage --delete-older-than 14d
```

Shell aliases are defined in `modules/shell.nix`: `rebuild`, `rebuild-test`, `rebuild-boot`, `update`, `gc-nix`.

## Architecture

**Entry Points:**
- `flake.nix` - Flake definition with inputs (nixpkgs unstable, nix-cachyos-kernel, noctalia shell, vicinae launcher)
- `configuration.nix` - Main config that imports all modules, defines boot, networking, user, and nix settings
- `hardware-configuration.nix` - Auto-generated by `nixos-generate-config` (do not edit manually)

**Modular Structure:**
All feature configurations live in `modules/` as standalone NixOS modules:
- `desktop.nix` - XDG portals, Wayland, polkit, launcher (Vicinae)
- `gpu-amd.nix` - AMD drivers, Vulkan, VA-API, CoreCtrl
- `gaming.nix` - Steam, Gamemode, Wine/Proton, kernel tweaks
- `dev.nix` - Docker, Node.js, Rust, build tools, CLI utilities
- `shell.nix` - Fish shell config, aliases, plugins
- `services.nix` - fstrim, zram, avahi, profile-sync-daemon, earlyoom
- `audio.nix`, `theming.nix`, `power.nix`, `virtualization.nix`, `navidrome.nix`, `apps.nix`

Each module follows the pattern: `{ config, pkgs, lib, ... }:`

**Package Management Philosophy:**
- System packages (`environment.systemPackages`): Services, hardware support, desktop infrastructure, build tools
- User packages (`nix profile`): GUI apps and fast-updating tools - managed independently with `update-apps` alias

## Code Conventions

- 2-space indentation
- Standard module signature: `{ config, pkgs, lib, ... }:`
- Package lists use `with pkgs; [ ... ]` syntax
- Decorative comment separators (`# ═══...`) for major sections

## Critical Rules

1. **Never modify `hardware-configuration.nix`** - it's auto-generated
2. **Never change `system.stateVersion`** (currently 26.05)
3. **Always validate with `rebuild-test` before switching**
4. User groups are distributed across modules (docker in dev.nix, gamemode in gaming.nix, corectrl in gpu-amd.nix, libvirtd in virtualization.nix)

## Key System Details

- **Kernel**: CachyOS with x86_64-v3 optimizations, scx_lavd scheduler
- **Desktop**: Niri compositor, Ly display manager, Ghostty terminal
- **User**: `pinj` with Fish shell (Zsh as fallback)
- **State Version**: 26.05