1 files changed, 74 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..10ef3ce
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,74 @@
+# 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`.