# CLAUDE.md

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

## Project Overview

This is a NixOS declarative system configuration repository using Nix flakes to manage multiple machines (kronos laptop, herra desktop) with modular, composable configurations. It uses NixOS 25.11 and Home Manager 25.11.

## Common Commands

```bash
# Apply configuration changes
sudo nixos-rebuild switch

# Test configuration without applying
sudo nixos-rebuild test

# Validate flake syntax
nix flake check

# Preview changes
sudo nixos-rebuild dry-run
```

## Architecture

The configuration uses a **layered orchestrator pattern** where `default.nix` files act as local aggregators that import related modules:

```
flake.nix                          # Entry point, defines inputs
  ↓
hosts/{kronos,herra}/              # Per-machine configs
  └─ configuration.nix             # System orchestrator
      ├─ modules/nixos/base/       # Base system (applied to all machines)
      └─ modules/nixos/des/        # Desktop environment (i3wm or gnome)

mun.nix                            # Home-manager orchestrator for user "mun"
  └─ modules/home/i3wm/            # User-level app configs
      └─ nord-blue/                # Current i3wm "rice" (theme/config)
```

### Four Configuration Layers

1. **System-Wide Base** (`modules/nixos/base/`): Boot, networking, users, services, packages - applied to all machines
2. **Environment-Specific System** (`modules/nixos/des/`): Desktop environment choice (i3wm vs gnome)
3. **Home-Manager User Config** (`mun.nix`): User-specific settings, shell, SSH, packages
4. **Environment-Specific Home** (`modules/home/i3wm/nord-blue/`): UI configs, keybindings, theming

### Key Files

- `flake.nix` - Defines nixpkgs and home-manager inputs
- `hosts/kronos/configuration.nix` - Laptop system config
- `hosts/herra/configuration.nix` - Desktop system config (dual-boot with Windows)
- `mun.nix` - Home-manager entry point for user "mun"
- `modules/nixos/base/packages.nix` - System-wide packages
- `modules/home/i3wm/nord-blue/variables.nix` - Color scheme and theme variables

## Adding Configurations

**New system package:** Add to `modules/nixos/base/packages.nix`

**New base system module:** Create file in `modules/nixos/base/`, add import to `modules/nixos/base/default.nix`

**New home-manager module:** Create file in the active rice directory (e.g., `modules/home/i3wm/nord-blue/`), add import to its `default.nix`

**New i3wm rice:** Create new directory under `modules/home/i3wm/` with its own `default.nix` orchestrator

## Environment Switching

To switch desktop environments, edit both:
1. `hosts/{machine}/configuration.nix` - Change import in `modules/nixos/des/`
2. `mun.nix` - Change import in `modules/home/`

Then run `sudo nixos-rebuild switch`.