diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8a4f278
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Deploy
+
+From within this directory:
+
+```bash
+sudo nixos-rebuild switch --flake .
+```
+
+To update flake inputs first:
+
+```bash
+nix flake update
+sudo nixos-rebuild switch --flake .
+```
+
+To build without switching (dry run / check):
+
+```bash
+nixos-rebuild build --flake .#<hostname>
+nix flake check
+```
+
+To deploy to a remote host:
+
+```bash
+nixos-rebuild switch --flake . --target-host <hostname>.local --sudo
+```
+
+To list generations:
+
+```bash
+nixos-rebuild list-generations
+```
+
+## Architecture
+
+This is a NixOS flake repository managing 5 hosts with shared Home Manager configuration.
+
+**Entry point:** `flake.nix` — defines all host configurations via `nixosConfigurations`. A shared `mkHomeManagerConfig` helper wires Home Manager into each host. The `inputs` are passed as `specialArgs` so all modules can access them.
+
+**Two layers of configuration:**
+
+- `hosts/` — system-level (NixOS modules, hardware, services)
+  - `hosts/modules/` — reusable system modules (`base.nix`, `desktop.nix`, `laptop.nix`, `server.nix`, `personal.nix`, `sway.nix`, `niri.nix`, etc.)
+  - `hosts/<name>/configuration.nix` — host-specific config that imports from `hosts/modules/`
+
+- `alex/` — user-level (Home Manager modules)
+  - `alex/core.nix` — base for all hosts (shell, git, tools, starship, fish, neovim)
+  - `alex/desktop.nix`, `alex/personal.nix` — conditionally included per host
+
+**Hosts:**
+
+| Host | Type | Notable |
+|------|------|---------|
+| `case` | Laptop | WireGuard, ZeroTier, Syncthing, Sway/Niri |
+| `count` | Desktop | AMD GPU + ROCm, Ollama |
+| `armitage` | Laptop | systemd-boot, latest kernel |
+| `alt` | Proxmox LXC | Media server (Jellyfin, *arr stack, Caddy) |
+| `nightcity` | Proxmox LXC | Minimal server |
+
+**Theme:** Catppuccin Mocha (`alex/colours/catppuchin-mocha.nix`)
+
+**Stable channel:** nixpkgs 25.11. Unstable packages are selectively overlaid via the `nixpkgs-unstable` input passed through `specialArgs`.