docs: add README with hosts, apply steps, and firmware caveat

Document the host table, rebuild commands, and that the MBP Asahi firmware dir is gitignored and must be populated out-of-band before that host builds. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-04 13:34:44 +00:00
parent de702d5ceb
commit f42b134ab1
1 changed files with 45 additions and 0 deletions
@@ -0,0 +1,45 @@
+# nixfiles
+
+NixOS / nix-darwin / home-manager configuration for all hosts, built from a
+single flake.
+
+## Hosts
+
+Defined in the host table in [`flake.nix`](./flake.nix):
+
+| Configuration       | System          | Machine                                  |
+| ------------------- | --------------- | ---------------------------------------- |
+| `lyrathorpe-mbp`    | `aarch64-linux` | MacBook Pro (Apple Silicon, Asahi)       |
+| `lyrathorpe-x1c`    | `x86_64-linux`  | ThinkPad X1                              |
+| `emmathorpe-edaas`  | `x86_64-linux`  | Work WSL box (NixOS-WSL)                 |
+| `lyrathorpe-mac`    | `aarch64-darwin`| macOS (nix-darwin)                       |
+
+Shared layers: `lyrathorpe/home` (home-manager: shell, git, editor),
+`system/modules/common-nixos.nix` (all NixOS hosts), and
+`system/modules/laptop.nix` (the physical laptops).
+
+## Applying
+
+```sh
+# NixOS
+sudo nixos-rebuild switch --flake .#<configuration>
+# Darwin
+darwin-rebuild switch --flake .#lyrathorpe-mac
+```
+
+## MacBook (Asahi) firmware
+
+The MBP host references `system/modules/firmware/` for Apple peripheral
+firmware (Wi-Fi/Bluetooth). Those blobs are **not** redistributable, so the
+directory is gitignored and a clean checkout will not build `lyrathorpe-mbp`
+until it is populated out-of-band.
+
+Copy the firmware extracted during the Asahi install (from
+`/etc/nixos/firmware` on the freshly-installed machine, or re-extract per the
+[Asahi NixOS docs](https://github.com/tpwrules/nixos-apple-silicon)) into
+`system/modules/firmware/` before rebuilding that host.
+
+## CI
+
+[`.gitea/workflows/ci.yaml`](./.gitea/workflows/ci.yaml) gates `nixfmt`
+formatting and evaluates every NixOS and Darwin host configuration on push/PR.