flake.nix

@@ -97,10 +97,7 @@
           "lens-desktop"
         ];
 
-        # Identity registry: who each user is (name, email, keys, groups), keyed
-        # by username. Threaded into the system layer as the `userRegistry`
-        # specialArg and into each user's home config as the `identity` module
-        # arg. See users/registry.nix, modules/users.nix, home/git.nix.
+        # Per-user identity, keyed by username. See README "Users".
         userRegistry = import ./users/registry.nix;
 
         # nixpkgs + nix-daemon settings shared by NixOS and Darwin hosts.
@@ -132,14 +129,8 @@
           }
         ];
 
-        # mkHost :: { system, modules, users, portable } -> nixosSystem
-        # Builds one machine by appending its host-specific modules to the shared
-        # baseModules. `users` is an attrset keyed by username; each value carries
-        # that user's home-module list and optional per-host-user system bits
-        # (e.g. linger). Per-user identity is injected into each home config via
-        # the `identity` module arg (extraSpecialArgs is per-host, so it cannot
-        # carry per-user data); the system layer reads the global `userRegistry`
-        # restricted to this host's `hostUsers` set.
+        # Build one NixOS host. `users` is an attrset keyed by username (home
+        # modules + optional per-user system bits). See README "Users".
         mkHost =
           {
             system,
@@ -190,11 +181,8 @@
           }
         ];
 
-        # mkDarwinHost :: { system, username, modules, homeModules } -> darwinSystem
-        # Darwin counterpart of mkHost. macOS already owns the login user, so we
-        # only attach the platform and home-manager; no NixOS user module here.
-        # Stays single-user (macOS owns the account); identity is still sourced
-        # from the registry so the shared home modules behave as on NixOS.
+        # Darwin counterpart of mkHost: single-user (macOS owns the account),
+        # identity still from the registry. See README "Users".
         mkDarwinHost =
           {
             system,
@@ -223,12 +211,8 @@
               ];
           };
 
-        # Host table — declarative registry of every machine. To add a host:
-        # give it a name, its `system`, its `users` set (each user's home-module
-        # list, plus optional per-host-user bits like linger), and the system
-        # `modules`. mapAttrs below turns each entry into a nixosConfiguration of
-        # the same name. Per-user home configs compose ./home (the shared bundle)
-        # with any per-user modules (e.g. ./users/emmathorpe/work.nix).
+        # Host table — one entry per machine, realised into a nixosConfiguration
+        # of the same name below. See README "Hosts" / "Users".
         hosts = {
           lyrathorpe-mbp = {
             system = "aarch64-linux";
@@ -418,14 +402,8 @@
         flake.nixosConfigurations = lib.mapAttrs (_name: mkHost) hosts;
         flake.darwinConfigurations = lib.mapAttrs (_name: mkDarwinHost) darwinHosts;
 
-        # Reusable home modules, exported so this config can be consumed off these
-        # hosts -- by a standalone home-manager on a non-NixOS machine, or as an
-        # input to someone else's flake. `default` is the portable bundle
-        # (shell + git + editor + claude). Consumers must supply the module args
-        # these expect: `inputs` always; `identity` (see users/registry.nix) for
-        # git/desktop; `portable` for sway. `desktop`/`sway` additionally require
-        # a NixOS host that provides the Sway/Firefox binary -- they are not
-        # standalone-portable.
+        # Reusable home modules, exported for use off these hosts. See README
+        # "Portable home" for the consumer module-arg expectations.
         flake.homeModules = {
           default = ./home;
           shell = ./home/shell.nix;
@@ -436,13 +414,8 @@
           sway = ./home/sway.nix;
         };
 
-        # Standalone home-manager configurations: the portable bundle built for a
-        # machine NOT managed by this flake (`home-manager switch --flake
-        # .#"<user>@<system>"`). Only the portable subset is exposed; the desktop
-        # suite stays NixOS-only. homeConfigurations are not per-system, so the
-        # system is encoded in the attribute name, and home.username/homeDirectory
-        # are set explicitly (the NixOS module sets them automatically; standalone
-        # does not).
+        # Standalone home-manager configs (portable bundle) for machines not
+        # managed by this flake. See README "Portable home".
         flake.homeConfigurations =
           let
             mkHome =

home/git.nix

@@ -1,6 +1,5 @@
-# Version control: git + delta pager + commitizen + lazygit. The committer
-# identity (name, email, signing key) comes from the per-user `identity` arg,
-# derived from the registry (users/registry.nix) by mkHost.
+# Version control: git + delta + commitizen + lazygit. Committer identity comes
+# from the per-user `identity` arg (the registry). See README "Users".
 {
   pkgs,
   lib,
@@ -20,8 +19,7 @@ in
     package = pkgs.gitFull;
     settings = {
       user.name = identity.fullName;
-      # Identity from the registry. mkDefault so a host-specific module can still
-      # override it without conflicting.
+      # mkDefault so a host-specific module can still override it.
       user.email = lib.mkDefault identity.email;
       push.autoSetupRemote = true;
       init.defaultBranch = "main";
@@ -78,9 +76,8 @@ in
         cc = "!cz commit";
       };
 
-      # SSH commit signing, key from the registry. mkDefault on the key and on
-      # gpgsign so a host without that key in its ssh-agent can override gpgsign
-      # to false rather than fail every commit.
+      # SSH signing, key from the registry. mkDefault so a host lacking the key
+      # in its agent can set gpgsign = false instead of failing every commit.
       gpg.format = "ssh";
       user.signingkey = lib.mkDefault identity.signingKey;
       commit.gpgsign = lib.mkDefault true;

modules/ssh.nix

@@ -1,9 +1,6 @@
-# Key-only SSH hardening, imported by the hosts that run sshd (T400, Mac Pro,
-# RPi5). The host config still does `services.openssh.enable = true` and opens
-# port 22 next to where it documents the listening service; this module only
-# tightens the policy so a host opting into sshd cannot accidentally ship
-# password/root login. Authorized keys are owned per-user by the identity
-# registry (users/registry.nix, applied via modules/users.nix), not here.
+# Key-only sshd hardening, imported by hosts that run sshd (T400, Mac Pro,
+# RPi5). Authorized keys are owned per-user by the registry (modules/users.nix),
+# not here.
 { ... }:
 {
   services.openssh.settings = {

modules/users.nix

@@ -1,9 +1,5 @@
-# System-level user accounts, built from the identity registry
-# (users/registry.nix). `hostUsers` is the host's user set, threaded by mkHost
-# from the flake host table; `userRegistry` is the global identity table passed
-# as a specialArg. Every account's identity -- description, groups, authorized
-# keys -- comes from its registry entry, so no user data is hardcoded here and a
-# host may declare any number of users.
+# System user accounts, built from the registry (users/registry.nix) for the
+# host's `hostUsers` set. See README "Users".
 {
   config,
   pkgs,
@@ -29,9 +25,7 @@
       openssh.authorizedKeys.keys = id.sshAuthorizedKeys;
       shell = pkgs.zsh;
     }
-    # Keep this user's systemd --user instance running without an open login
-    # session (e.g. for home-manager user timers). Only emitted when the host
-    # table opts in, so hosts that don't set it leave linger entirely unmanaged.
+    # linger opt-in (host table); left unmanaged when unset.
     // lib.optionalAttrs (spec ? linger) { inherit (spec) linger; }
   ) hostUsers;
 

users/emmathorpe/work.nix

@@ -1,7 +1,5 @@
-# Home-manager module for the work (EDaaS/WSL) profile: corporate work toolchain
-# packages and tmux tweaks. Imported only by the work host. The corporate git
-# identity (email + signing key) is the emmathorpe entry in the identity
-# registry (users/registry.nix), applied by the shared home/git.nix.
+# Work (EDaaS/WSL) home profile: corporate toolchain + tmux tweaks. Git identity
+# comes from the registry (users/registry.nix), not here.
 { pkgs, lib, ... }:
 
 {

users/registry.nix

@@ -1,14 +1,5 @@
-# User identity registry -- pure data, no machinery. Keyed by username.
-#
-# Each entry describes WHO a user is (display name, email, authorized/signing
-# keys, supplementary groups). The reusable modules read this indirectly:
-#   - system: modules/users.nix builds users.users.* from `userRegistry`
-#     (specialArg) restricted to the host's `hostUsers` set.
-#   - home:   home/git.nix and home/desktop.nix read the per-user `identity`
-#     module arg, which mkHost derives from the matching registry entry.
-#
-# The login name is injected by mkHost as `identity.username`, so it is not
-# repeated inside each entry here.
+# User identity registry -- pure data, keyed by username. See README "Users".
+# (`identity.username` is injected by mkHost, so it is not repeated here.)
 {
   lyrathorpe = {
     fullName = "Lyra Thorpe";
@@ -30,10 +21,7 @@
       "wheel"
       "docker"
     ];
-    # No personal authorized key on file yet. The previous shared user module
-    # applied Lyra's key to every account, including this one -- a defect. Leave
-    # this empty until a real key is provisioned; SSH login is moot on the WSL
-    # host (entered via wsl.exe, not sshd).
+    # No personal key on file yet; add one if SSH login as emmathorpe is wanted.
     sshAuthorizedKeys = [ ];
     signingKey = "key::ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAJMVgeRKnfX1G8coU3nAobI485aeUpGTMqH7+zbKI8o emma.thorpe@cloud.com";
   };