# 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/`.

## Adding packages

Before writing a custom `packages/` derivation, always check if the package already exists in nixpkgs:
- Stable: https://search.nixos.org/packages?channel=25.11&query=<name>
- Unstable: https://search.nixos.org/packages?channel=unstable&query=<name>
- Master (bleeding edge): check open PRs at https://github.com/NixOS/nixpkgs/pulls

If it exists in `unstable` or `master` but not stable, pull it via `overlays/unstable.nix` using `channels.unstable` or `channels.master`. Only write a custom `packages/` derivation as a last resort.

## 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` |