Add CLAUDE.md with project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+NixOS + nix-darwin dotfiles managing multiple hosts via a single flake.
+Uses **flake-parts**, **import-tree**, **home-manager**, and **agenix** for secrets.
+
+## Hosts
+
+| Host | Platform | Role |
+|------|----------|------|
+| **endurance** | nixos (x86_64-linux) | Desktop workstation (AMD GPU, Niri compositor) |
+| **aepplet** | nixos (x86_64-linux) | Data/compute server |
+| **vasa** | darwin (x86_64-darwin) | macOS (minimal config) |
+
+Host configs live in `hosts/{name}/` with `default.nix`, `hardware.nix`, and `disko.nix`.
+
+## Key directories
+
+| Path | What's there |
+|------|-------------|
+| `flake.nix` | Entry point — all inputs and flake-parts imports |
+| `modules/flake/` | Flake-parts modules: host definitions, home-manager wiring, packages, formatter, lib |
+| `modules/generic/` | Shared config (nix settings, profiles, base packages) — applies to all platforms |
+| `modules/nixos/` | NixOS-specific: system, users, SSH, services (ollama, traefik, beszel, metrics) |
+| `modules/nixos/profiles/` | Composable feature profiles: `graphical`, `docker`, `work` |
+| `modules/darwin/` | macOS-specific modules |
+| `modules/home/` | Home-manager modules shared across hosts (helix, terminal, shell, kitty, GUI) |
+| `home/by-host/{name}/` | Per-host home-manager config (programs, services, theming) |
+| `home/by-host/{name}/config/` | Auto-imported config modules (dev, shell, git, etc.) |
+| `home/by-host/{name}/misc/` | Optional per-host services (launcher, browser, recording) |
+| `home/by-host/{name}/niri/` | Niri WM config (keybinds, window rules, autostart) |
+| `packages/` | Custom packages (each dir has `package.nix`, auto-discovered) |
+| `overlays/` | Nixpkgs overlays (lix, unstable channel packages, custom builds) |
+| `secrets/` | Age-encrypted secrets managed by agenix |
+
+## Custom options namespace
+
+This flake uses a `bosun` namespace for composable options:
+
+```nix
+bosun.profiles.graphical.enable = true;
+bosun.profiles.docker.enable = true;
+bosun.profiles.work.enable = true;
+bosun.key = "ssh-ed25519 ...";      # Host SSH public key
+bosun.secrets.npmrc = { ... };       # Secret definitions
+```
+
+Profile definitions are in `modules/generic/profiles.nix`, implementations in `modules/nixos/profiles/`.
+
+## Architecture patterns
+
+- **import-tree** auto-discovers and imports `.nix` files in `modules/flake/`. Files prefixed with `_` are excluded from auto-import.
+- **easy-hosts** manages host definitions in `modules/flake/hosts.nix`.
+- **Overlays** receive `inputs` and `channels` (multiple nixpkgs instances) via the `withChannels` wrapper in `overlays/default.nix`.
+- **Stylix** handles system-wide theming (colors, fonts) from a single config.
+- **Lix** is used instead of stock Nix.
+
+## Commands (`just`)
+
+```
+just deploy          # nixos-rebuild switch / darwin-rebuild switch
+just debug           # Build with --show-trace --verbose via nom
+just repl            # nix repl with flake loaded
+just shell <name>    # Enter a dev shell
+just up              # Update all flake inputs
+just upp <input>     # Update a single input
+just gc              # Garbage collect old generations
+just rekey           # Rekey all agenix secrets
+just edit-secret <f> # Edit an encrypted secret
+```
+
+## Where to find settings
+
+| Looking for... | Go to |
+|---------------|-------|
+| Which hosts exist and their platform | `modules/flake/hosts.nix` |
+| Home-manager host assignments | `modules/flake/homes.nix` |
+| Nix daemon settings, substituters, gc | `modules/generic/nix.nix` |
+| Locale, timezone, stateVersion | `modules/nixos/system.nix` |
+| User accounts | `modules/nixos/users.nix` |
+| SSH daemon config | `modules/nixos/ssh.nix` |
+| Shell config (Fish, Nushell) | `modules/home/common/terminal/shell/` |
+| Helix editor config | `modules/home/common/helix/` |
+| Kitty terminal | `modules/home/gui/kitty.nix` |
+| Desktop programs for endurance | `home/by-host/endurance/config/dev.nix` and `misc/` |
+| Niri keybinds & window rules | `home/by-host/endurance/niri/` |
+| Available packages | `packages/` (auto-discovered by flake-parts) |
+| Secret definitions | `modules/*/secrets.nix` + `secrets/*.age` |