updated documentation

docs/flake-lock-automation.md

@@ -1,6 +1,7 @@
 # flake.lock automation
 
-This repository uses CI workflows to keep `flake.lock` up to date on a schedule and to verify that all declared NixOS hosts still evaluate after dependency updates.
+This repository uses CI workflows to keep `flake.lock` up to date on a schedule
+and to verify that declared NixOS hosts still evaluate after dependency updates.
 
 ## What this automation does
 
@@ -14,6 +15,7 @@ This repository uses CI workflows to keep `flake.lock` up to date on a schedule
   - `server`
   - `nix-cache`
   - `nix-minimal`
+  - `pxe-boot`
 
 ## Why hosts should stop using `--upgrade-all`
 
@@ -27,6 +29,9 @@ sudo nixos-rebuild switch --flake git+https://gitea.lan.ddnsgeek.com/beatzaplent
 
 Using the committed lock file keeps all hosts aligned and makes updates auditable through CI and code review.
 
+Codex and automated review sessions must not run rebuilds. Limit checks to
+evaluation, linting, formatting, and dry-run builds.
+
 ## Command differences
 
 - `nix flake update`

docs/nix-cache.md

@@ -8,6 +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`.
+- The `nix-cache` host imports `modules/nix/cache-server.nix`.
 
 ## Binary cache signing keys (on nix-cache)
 
@@ -20,6 +22,8 @@ cat /etc/nix/cache-pub.pem
 ```
 
 Do not commit private keys.
+Do not commit new password hashes or live credentials. Existing committed hashes
+should be rotated and moved to host-local secret management.
 
 ## Remote builder SSH keys
 
@@ -33,6 +37,9 @@ sudo ssh -i /root/.ssh/nixremote nixremote@nix-cache nix-store --version
 
 On `nix-cache`, install the matching public key used by `nixremote` authorized keys.
 
+The committed `nixremote` authorized keys are public SSH keys only. Keep the
+matching private keys on client hosts and out of the repository.
+
 ## Manual verification
 
 After deployment:

docs/pxe-boot.md

@@ -0,0 +1,52 @@
+# pxe-boot
+
+The `pxe-boot` host serves HTTP boot assets for iPXE clients.
+
+## Host Role
+
+- Hostname: `pxe-boot`
+- Web service: nginx on TCP port 80
+- PXE root: `/srv/pxe`
+- Generated iPXE menu: `/srv/pxe/boot/menu.ipxe`
+- Boot binaries copied from the Nix `ipxe` package:
+  - `/srv/pxe/boot/ipxe.efi`
+  - `/srv/pxe/boot/undionly.kpxe`
+
+## Directory Layout
+
+The host creates these directories with systemd tmpfiles:
+
+```text
+/srv/pxe
+/srv/pxe/boot
+/srv/pxe/nixos
+/srv/pxe/ubuntu
+/srv/pxe/rescue
+```
+
+The generated menu currently exposes entries for:
+
+- NixOS installer
+- Rescue environment
+- iPXE shell
+- Reboot
+
+Kernel and initrd artifacts for installer or rescue entries must be placed under
+the matching `/srv/pxe/<entry>/` directories by an operator or a separate build
+process. This repository defines the service and menu, not the installer images.
+
+## Validation
+
+Safe evaluation check:
+
+```bash
+nix eval .#nixosConfigurations.pxe-boot.config.system.build.toplevel.drvPath --raw
+```
+
+After deployment by an operator, basic service checks are:
+
+```bash
+curl http://pxe-boot/boot/menu.ipxe
+curl -I http://pxe-boot/boot/ipxe.efi
+curl -I http://pxe-boot/boot/undionly.kpxe
+```