docs: update READMEs and .gitignore for the restructured layout

Point all path references at the new users/, home/, modules/, hosts/, lib/ locations, and document the user registry, the multi-user host model, and the portable homeConfigurations / homeModules outputs.
2026-06-29 12:27:52 +01:00
parent 10cc6cceed
commit ea3e75e0af
2 changed files with 65 additions and 34 deletions
@@ -7,22 +7,51 @@ single flake.

 Defined in the host table in [`flake.nix`](./flake.nix):

-| Configuration         | System           | Machine                                                                                                              |
-| --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `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-rpi5`     | `aarch64-linux`  | Raspberry Pi 5 headless server: Docker host + nginx reverse proxy — [install notes](./system/machine/RPi5/README.md) |
-| `lyrathorpe-mac`      | `aarch64-darwin` | macOS (nix-darwin)                                                                                                   |
+| Configuration         | System           | Machine                                                                                                     |
+| --------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| `lyrathorpe-mbp`      | `aarch64-linux`  | MacBook Pro (Apple Silicon, Asahi)                                                                          |
+| `lyrathorpe-t400`     | `x86_64-linux`   | ThinkPad T400 — [install notes](./hosts/T400/README.md)                                                     |
+| `lyrathorpe-macpro31` | `x86_64-linux`   | Mac Pro 3,1, desktop — [install notes](./hosts/MacPro31/README.md)                                          |
+| `emmathorpe-edaas`    | `x86_64-linux`   | Work WSL box (NixOS-WSL)                                                                                    |
+| `lyrathorpe-rpi5`     | `aarch64-linux`  | Raspberry Pi 5 headless server: Docker host + nginx reverse proxy — [install notes](./hosts/RPi5/README.md) |
+| `lyrathorpe-mac`      | `aarch64-darwin` | macOS (nix-darwin)                                                                                          |

-Shared layers: `lyrathorpe/home` (home-manager: shell, git, editor),
-`system/modules/common-nixos.nix` (all NixOS hosts: fonts, nix-ld, caches),
-`system/modules/workstation.nix` (physical graphical hosts: audio, thermald,
-earlyoom, fwupd), `system/modules/laptop.nix` (laptops: Wi-Fi, Bluetooth, power,
-lid), and `system/modules/ssh.nix` (key-only sshd). The x86 hosts also pull
+Shared layers: `home` (home-manager: shell, git, editor),
+`modules/common-nixos.nix` (all NixOS hosts: fonts, nix-ld, caches),
+`modules/workstation.nix` (physical graphical hosts: audio, thermald,
+earlyoom, fwupd), `modules/laptop.nix` (laptops: Wi-Fi, Bluetooth, power,
+lid), and `modules/ssh.nix` (key-only sshd). The x86 hosts also pull
 `nixos-hardware` profiles.

+## Users
+
+Identity is data, kept separate from the reusable modules:
+
+- [`users/registry.nix`](./users/registry.nix) — one entry per user (display
+  name, email, supplementary groups, authorized + signing keys). This is the
+  single source of identity; no user data is hardcoded in the modules.
+- Each host's table entry declares a `users` set keyed by username; every entry
+  lists that user's home-module composition (the shared `./home` bundle plus any
+  per-user modules, e.g. [`users/emmathorpe/work.nix`](./users/emmathorpe/work.nix))
+  and optional per-host-user system bits such as `linger`.
+- `mkHost` builds each account from the registry and injects the matching
+  identity into that user's home config as the `identity` module arg. A host can
+  therefore declare any number of users.
+
+### Portable home (off-NixOS / external consumers)
+
+The home config is also exposed for use beyond these hosts:
+
+- `homeConfigurations."<user>@<system>"` — a standalone home-manager profile
+  (the portable subset: shell + git + editor + claude) that can be activated on a
+  machine this flake does **not** manage:
+  `home-manager switch --flake .#"lyrathorpe@x86_64-linux"`. The desktop/sway
+  modules are intentionally excluded (they rely on a NixOS-provided Sway/Firefox
+  binary).
+- `homeModules` — the reusable modules exported so another flake can import them
+  (`inputs.<this>.homeModules.default`). Consumers must supply the module args
+  these expect: `inputs` always, `identity` for git/desktop, `portable` for sway.
+
 ## Applying

 ```sh
@@ -35,25 +64,25 @@ darwin-rebuild switch --flake .#lyrathorpe-mac
 ## Shell environment & keybindings

 - Interactive shell features (zsh, tmux, git, ssh, CLI tools, auto-tmux):
-  [`lyrathorpe/home/README.md`](./lyrathorpe/home/README.md).
+  [`home/README.md`](./home/README.md).
 - All Sway / tmux / foot / zsh keyboard shortcuts:
-  [`lyrathorpe/home/KEYBINDINGS.md`](./lyrathorpe/home/KEYBINDINGS.md).
+  [`home/KEYBINDINGS.md`](./home/KEYBINDINGS.md).

 ## Login / greeter

 Graphical (Sway) hosts log in through a Wayland greeter — `greetd` running
 ReGreet inside the `cage` kiosk compositor — implemented in
-[`lyrathorpe/swaywm.nix`](./lyrathorpe/swaywm.nix), gated on
+[`modules/sway.nix`](./modules/sway.nix), gated on
 `features.swayDesktop.enable` (the option is declared in
-[`system/modules/features.nix`](./system/modules/features.nix), so headless hosts
-can leave it off without importing `swaywm.nix`). The greeter is forced to Dvorak
+[`modules/features.nix`](./modules/features.nix), so headless hosts
+can leave it off without importing `modules/sway.nix`). The greeter is forced to Dvorak
 to match the console and Sway session. Headless hosts (the WSL work box and the
 Raspberry Pi server) keep plain TTY login. The target account needs a password
 (`passwd <user>`) before it can log in.

 ## MacBook (Asahi) firmware

-The MBP host references `system/modules/firmware/` for Apple peripheral
+The MBP host references `modules/firmware/` for Apple peripheral
 firmware (Wi-Fi/Bluetooth). These blobs are **committed** (tracked) even though
 `.gitignore` lists the directory: the flake is `git+file`, so it only sees
 tracked files — untracking them breaks `lyrathorpe-mbp` evaluation (and the CI
@@ -63,7 +92,7 @@ redistributable; the repo is private.
 To refresh them, copy the firmware extracted during the Asahi install (from
 `/etc/nixos/firmware`, or re-extract per the
 [Asahi NixOS docs](https://github.com/tpwrules/nixos-apple-silicon)) into
-`system/modules/firmware/` and commit with `git add -f`.
+`modules/firmware/` and commit with `git add -f`.

 ## Development