README.md

@@ -9,10 +9,11 @@ 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)                       |
+| `lyrathorpe-mbp`      | `aarch64-linux`  | MacBook Pro (Apple Silicon, Asahi)                                  |
+| `lyrathorpe-t400`     | `x86_64-linux`   | ThinkPad T400 — [install notes](./system/machine/T400/README.md)   |
+| `lyrathorpe-macpro31` | `x86_64-linux`   | Mac Pro 3,1, desktop — [install notes](./system/machine/MacPro31/README.md) |
+| `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/machine/MacPro31/README.md

@@ -0,0 +1,51 @@
+# Mac Pro 3,1 (Early 2008) — install notes
+
+Flake host: `lyrathorpe-macpro31`. Desktop (`portable = false`, imports
+`../../modules/desktop.nix`). Files: `configuration.nix`,
+`hardware-configuration.nix`.
+
+## Hardware configuration
+
+`hardware-configuration.nix` here is a hand-written **placeholder**. On the real
+machine, run `nixos-generate-config`, replace the file, and commit it. It assumes
+by-label partitions — ESP `ESP` (vfat, mounted at `/boot`), root `nixos` (ext4),
+and `swap` — so either label them at install time or swap in the generated UUIDs.
+
+## Bootloader
+
+The Mac Pro 3,1 has **64-bit EFI**, so it uses **systemd-boot** (no GRUB/CSM
+shim). `canTouchEfiVariables = false` because Apple's firmware does not reliably
+accept `efibootmgr` NVRAM writes.
+
+Apple-EFI quirk: if the firmware boot picker does not show NixOS after install,
+either
+
+- uncomment `boot.loader.efi.efiInstallAsRemovable = true;` in
+  `configuration.nix` (installs the fallback `\EFI\BOOT\BOOTX64.EFI`), and/or
+- "bless" the ESP from macOS.
+
+Partition the disk GPT with an ESP (vfat).
+
+## Graphics
+
+The stock card varies between units — **ATI Radeon HD 2600 XT** or **NVIDIA
+GeForce 8800 GT**. No proprietary driver is hardcoded; Sway relies on in-tree KMS:
+
+- ATI Radeon HD 2600 XT → `radeon` (or `amdgpu`) KMS
+- NVIDIA GeForce 8800 GT → `nouveau` KMS
+
+These come up automatically. If a card needs forcing, set
+`services.xserver.videoDrivers` and/or add the module to
+`boot.initrd.kernelModules` for early KMS (see the comment in
+`configuration.nix`).
+
+## Networking
+
+Wired Ethernet via NetworkManager (from `desktop.nix`) — the Mac Pro has two
+gigabit ports.
+
+## Apply
+
+```sh
+sudo nixos-rebuild switch --flake .#lyrathorpe-macpro31
+```

system/machine/MacPro31/configuration.nix

@@ -1,6 +1,7 @@
 # Apple Mac Pro 3,1 (Early 2008, dual Xeon Harpertown, x86_64). Desktop host:
 # shared graphical/wired options live in ../../modules/desktop.nix; only
-# host-specific settings are here.
+# host-specific settings are here. Install notes (EFI booting, GPU, partitions):
+# see ./README.md.
 { ... }:
 
 {

system/machine/T400/README.md

@@ -0,0 +1,39 @@
+# ThinkPad T400 — install notes
+
+Flake host: `lyrathorpe-t400`. Files: `configuration.nix`, the `boot-*.nix`
+variants, and `hardware-configuration.nix`.
+
+## Hardware configuration
+
+`hardware-configuration.nix` here is a hand-written **placeholder**. On the real
+machine, run `nixos-generate-config`, replace the file, and commit it. It assumes
+by-label partitions — root `nixos` (ext4) and `swap` — so either label them at
+install time or swap in the generated UUIDs.
+
+## Bootloader — import the module matching the flashed firmware
+
+`configuration.nix` imports exactly one boot module. Default is `boot-bios.nix`;
+switch by commenting it out and uncommenting the relevant alternative.
+
+| Firmware | Module | Notes |
+| --- | --- | --- |
+| Stock Lenovo BIOS, or coreboot + **SeaBIOS** payload | `boot-bios.nix` | GRUB on the MBR. Set `device` to the real install disk (`/dev/sda` by default). MBR/legacy layout. |
+| coreboot + **GRUB** payload | `boot-coreboot-grub.nix` | GRUB is config-only (`device = "nodev"`); NixOS does **not** write to a disk. Your coreboot `grub.cfg` (in the flash chip) must `search` for and `configfile` the on-disk `/boot/grub/grub.cfg`, or chainload the disk's GRUB. |
+| coreboot + **Tianocore/edk2 (UEFI)** payload | `boot-coreboot-uefi.nix` | systemd-boot. `canTouchEfiVariables = true` (coreboot honours NVRAM writes). The module **declares its own ESP** (`/boot` vfat, label `ESP`) — when you regenerate `hardware-configuration.nix`, do **not** let it also define `/boot`. Create + label an `ESP` vfat partition (GPT). |
+
+## Graphics
+
+This unit has the optional **discrete ATI Mobility Radeon HD 3470 (RV620)**. The
+open `radeon` KMS driver is loaded in the initrd for early modesetting; firmware
+comes from `enableRedistributableFirmware`.
+
+The T400 has switchable graphics (discrete ATI + Intel GMA 4500MHD). Select
+**Discrete** in the firmware's graphics setting so only the ATI is live. If you
+run **Integrated** instead, the Intel `i915` driver takes over with no config
+change and `radeon` stays idle.
+
+## Apply
+
+```sh
+sudo nixos-rebuild switch --flake .#lyrathorpe-t400
+```

system/machine/T400/configuration.nix

@@ -1,5 +1,6 @@
 # ThinkPad T400 (NixOS). Shared laptop options live in ../../modules/laptop.nix;
-# only host-specific settings are here.
+# only host-specific settings are here. Install notes (boot variants, GPU,
+# partitions): see ./README.md.
 { ... }:
 
 {