Refresh stale architecture docs

CLAUDE.md's "Composition pattern" section still described the
pre-refactor layout (hosts/<host>/configuration.nix as a thin imports
list, hardware-configuration wired in from flake.nix) from before the
platform x build-type matrix landed. Rewrite it to match the current
mkTarget/host.nix architecture and the module moves from the prior
commit. Also fixes docs/nix-cache.md, which referenced a
modules/nix/ path that never existed in this repo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01La55Nsss8jZ7ZuzUV9mfot

CLAUDE.md

@@ -52,56 +52,76 @@ There is no test suite — "correctness" here means the flake evaluates and
 
 ## Architecture
 
-`flake.nix` is the single entry point. It defines one `nixosConfigurations.<host>`
+`flake.nix` is the single entry point. It generates one
-attribute per machine, each built the same way:
+`nixosConfigurations.<platform>-<buildtype>` attribute per target via the
+`mkTarget` function, composed from:
 
 ```
 nixosSystem {
   modules = [
     disko.nixosModules.disko
-    ./hosts/<host>/configuration.nix        # host-specific config
+    sops-nix.nixosModules.sops
-    ./modules/hardware-configuration/vm/<proxmox|linode>.nix
+    ./modules/common/configuration.nix
+    ./modules/platforms/${platform}.nix        # what it runs on
+    ./modules/build-types/${buildType}.nix     # what it's for
+    hostPath                                   # hosts/<name>/host.nix — per-machine identity
     home-manager.nixosModules.home-manager { ... }
-  ];
+  ] ++ (client-only modules, for every buildType except "nix-cache" itself)
 }
 ```
 
-Hosts currently defined in `flake.nix`: `nixos`, `docker`, `server`,
+Platforms: `linode`, `proxmox`, `lxc`. Build types: `minimal`, `nix-cache`,
-`nix-cache`, `nix-minimal`, `pxe-boot`, `linode-minimal`. Treat `flake.nix` as
+`server`, `docker`, `gui`, `pxe-boot`. Not every combination is built — e.g.
-the source of truth for which hosts exist — `README.md`, `AGENTS.md`,
+`pxe-boot` has no `linode` variant (PXE/DHCP/TFTP need LAN L2 adjacency a
+Linode VPS doesn't have). Treat `flake.nix`'s `generatedTargets` as the source
+of truth for which hosts exist — `README.md`, `AGENTS.md`,
 `docs/flake-lock-automation.md`, and the CI eval workflows
 (`.github/workflows/check-nixos.yml`, `.gitea/workflows/check-nixos.yml`) list
-hosts by hand and can drift from it, so re-check them against `flake.nix` when
+hosts by hand (or, for the CI workflows, evaluate the flake dynamically) and
-adding or removing a host.
+can drift from it, so re-check them against `flake.nix` when adding or
+removing a host.
 
 ### Composition pattern
 
-Every host's real configuration lives in `hosts/<host>/configuration.nix`,
+- `hosts/<name>/host.nix` — per-machine identity **only**: hostname, hostId,
-which is a thin list of `imports` pulling in reusable pieces from `modules/`:
+  per-machine secrets, `system.stateVersion`. These files carry no `imports`
-
+  of their own beyond narrow parameterized helpers (see
-- `modules/common/configuration.nix` — base NixOS config imported by (almost)
+  `modules/beszel/host-token.nix` below) — all shared behavior comes from the
-  every host: locale, users, nix settings, git. Nearly always the first import.
+  platform/build-type modules composed in `flake.nix`, not from the host file.
-- `modules/common/home.nix` / `hosts/<host>/home.nix` — Home Manager config for
+- `modules/platforms/{linode,proxmox,lxc}.nix` — platform-specific config:
-  the `nixos` user; the `nixos` workstation has its own, other hosts share
+  boot method, guest tooling, and (for linode/proxmox) the hypervisor-specific
-  `modules/common/home.nix`.
+  hardware config, imported directly by the platform module itself
+  (`../hardware-configuration/vm/{proxmox,linode}.nix`) — **not** wired in
+  from `flake.nix`. `lxc.nix` has no hardware-configuration counterpart since
+  containers share the host kernel.
+- `modules/build-types/*.nix` — what a system is for:
+  minimal/server/docker/gui/pxe-boot/nix-cache.
+- `modules/common/configuration.nix` — base NixOS config imported by every
+  host: locale, users, nix settings, git.
+- `modules/common/home.nix` / `hosts/nixos/home.nix` — Home Manager config for
+  the `nixos` user; the `nixos` workstation (`gui` build type) has its own,
+  other hosts share `modules/common/home.nix`.
 - `modules/disko/proxmox.nix` — declarative disk layout (GPT: ESP + swap +
   ext4 root) via disko, used by all Proxmox-VM hosts.
 - `modules/boot/efi.nix` — systemd-boot + EFI vars, paired with the disko module.
-- `modules/hardware-configuration/vm/{proxmox,linode}.nix` — hypervisor-specific
+- `modules/nix-cache/{client,server,remote-builder-client}.nix` — binary cache
-  hardware config, wired in from `flake.nix` (not from the host file).
+  substituter + SSH remote-builder wiring; see `docs/nix-cache.md` for the
-- `modules/nix-cache/{client,server}.nix` + `modules/remote-builder-client.nix` —
+  full design (per-host local stores, no shared `/nix/store`, and how the
-  binary cache substituter + SSH remote-builder wiring; see `docs/nix-cache.md`
+  `nixremote` signing/SSH keys fit together).
-  for the full design (per-host local stores, no shared `/nix/store`, and how
+- `modules/beszel/host-token.nix` — parameterized helper module
-  the `nixremote` signing/SSH keys fit together).
+  (`{ name, sopsFile }`) that wires a host's beszel-agent sops secret/template
-- `modules/tailscale/`, `modules/docker/`, `modules/beszel/`,
+  and `environmentFile`; used by `hosts/server/host.nix` and
-  `modules/services/*` — single-purpose, single-host feature modules (e.g.
+  `hosts/nix-cache/host.nix` to avoid duplicating that boilerplate.
-  `docker/enable-service.nix`, `services/zfs/enable-service.nix`,
+- `modules/tailscale/`, `modules/docker/`, `modules/networking/`,
-  `beszel/enable-agent.nix` for monitoring). Grep `hosts/*/configuration.nix`
+  `modules/traefik/`, `modules/services/*` — single-purpose, single-host
-  for the `imports` list to see which modules apply to a given host.
+  feature modules (e.g. `docker/enable-service.nix`,
+  `services/zfs/enable-service.nix`). Grep `modules/build-types/*.nix` for
+  each build type's `imports` list to see which modules apply where.
 
-New host = new `hosts/<name>/configuration.nix` + a matching block added to
+New host = new `hosts/<name>/host.nix` + a matching
-`flake.nix`'s `nixosConfigurations`, composed from existing `modules/*` pieces
+`mkTarget { platform; buildType; hostPath; }` entry added to `flake.nix`'s
-rather than duplicating config.
+`generatedTargets`, composed from existing `modules/*` pieces rather than
+duplicating config.
 
 ### Other docs worth reading before touching these areas
 

docs/nix-cache.md

@@ -8,8 +8,8 @@ This repository configures `nix-cache` as a **binary cache server** and a **remo
 - Every machine still keeps and uses its own local `/nix/store`.
 - Clients prefer `http://nix-cache` for substitutes and keep `https://cache.nixos.org/` as fallback.
 - Clients can offload builds to `nix-cache` through SSH (`nix.distributedBuilds`).
-- Client hosts import `modules/nix/cache-client.nix` and, when remote building is enabled, `modules/nix/remote-builder-client.nix`.
+- Client hosts import `modules/nix-cache/client.nix` and, when remote building is enabled, `modules/nix-cache/remote-builder-client.nix`.
-- The `nix-cache` host imports `modules/nix/cache-server.nix`.
+- The `nix-cache` host imports `modules/nix-cache/server.nix`.
 
 ## Binary cache signing keys (on nix-cache)