updated documentation

README.md

@@ -1,25 +1,72 @@
-
-## `README.md`
-
-```markdown
 # NixOS LAN Configurations
 
-Flake-based NixOS configuration repository for Wayne’s LAN machines.
+Flake-based NixOS configuration repository for Wayne's LAN servers and
+workstation.
 
 ## Hosts
 
 This flake currently defines:
 
 | Host | Purpose |
-|---|---|
-| `nixos` | Main NixOS workstation / desktop |
+| --- | --- |
+| `nixos` | Main NixOS workstation / Cinnamon desktop |
 | `docker` | Docker host for the main container stack |
 | `kuma` | Docker-enabled Uptime Kuma style host |
-| `server` | Storage / NFS / backup style server |
-| `nix-cache` | Local Nix binary cache host |
-| `nix-minimal` | Minimal NixOS host profile |
+| `server` | Storage, NFS, backup, and monitoring exporter host |
+| `nix-cache` | Local Nix binary cache and remote builder |
+| `nix-minimal` | Minimal NixOS host profile with SSHFS tooling |
+| `pxe-boot` | HTTP/iPXE boot asset host |
 
 List hosts with:
 
 ```bash
 nix eval --json .#nixosConfigurations --apply builtins.attrNames | jq -r '.[]'
+```
+
+## Layout
+
+| Path | Purpose |
+| --- | --- |
+| `flake.nix` | Flake inputs and `nixosConfigurations` outputs |
+| `hosts/<host>/configuration.nix` | Host-specific NixOS configuration |
+| `hosts/nixos/home.nix` | Workstation-specific Home Manager config |
+| `common/` | Shared NixOS, Home Manager, aliases, and hardware config |
+| `modules/nix/` | Binary cache and remote builder client/server modules |
+| `docs/` | Operational notes for cache, builders, lock updates, and boot services |
+| `scripts/` | Codex setup and validation helpers |
+
+## Validation
+
+Safe validation commands for Codex and local review:
+
+```bash
+bash scripts/codex-setup.sh
+bash scripts/codex-maintenance.sh dry-run
+bash scripts/codex-maintenance.sh
+```
+
+For individual host evaluation:
+
+```bash
+nix eval .#nixosConfigurations.<host>.config.system.build.toplevel.drvPath --raw
+```
+
+Use `nix build --dry-run --no-link` when build planning is needed. Do not run
+deployment, install, disk formatting, mount, or reboot commands from automated
+review sessions.
+
+## Operations
+
+- Host rebuilds should consume the committed `flake.lock`.
+- Routine dependency updates should happen through the flake lock automation
+  described in `docs/flake-lock-automation.md`.
+- `nix-cache` serves substitutes over HTTP and can act as a remote builder for
+  client hosts.
+- `pxe-boot` serves iPXE boot files over HTTP from `/srv/pxe`.
+
+## Security Notes
+
+Do not commit tokens, private keys, live credentials, or new password hashes.
+This repository currently contains committed password hashes in shared NixOS
+configuration; rotate those passwords and move hashes into host-local secret
+management before treating the repository as public or widely shared.