update documentation for nixos hosts

hosts/README.md

@@ -12,3 +12,15 @@ These are the individual machines managed by this flake.
 | [swan](./swan/default.nix)                 | Home server         |
 | [tempest](./tempest/default.nix)           | Linux desktop       |
 
+## NixOS Workflow
+
+Each hosts file is imported into [nixosConfigurations](../flake.nix) and passed
+the arguments from the flake (inputs, globals, overlays). The `nixosSystem`
+function in that hosts file will be called by the NixOS module system during a
+nixos-rebuild.
+
+Each module in the each host's `modules` list is either a function or an
+attrset. The attrsets will simply apply values to options that have been
+declared in the config by other modules. Meanwhile, the functions will be
+passed various arguments, several of which you will see listed at the top of
+each of their files.

hosts/flame/default.nix

@@ -1,6 +1,8 @@
 # The Flame
 # System configuration for an Oracle free server
 
+# See [readme](../README.md) to explain how this file works.
+
 # How to install:
 # https://blog.korfuri.fr/posts/2022/08/nixos-on-an-oracle-free-tier-ampere-machine/
 # These days, probably use nixos-anywhere instead.

hosts/hydra/default.nix

@@ -1,6 +1,8 @@
 # The Hydra
 # System configuration for WSL
 
+# See [readme](../README.md) to explain how this file works.
+
 { inputs, globals, overlays, ... }:
 
 inputs.nixpkgs.lib.nixosSystem {

hosts/swan/default.nix

@@ -1,6 +1,8 @@
 # The Swan
 # System configuration for my home NAS server
 
+# See [readme](../README.md) to explain how this file works.
+
 { inputs, globals, overlays, ... }:
 
 inputs.nixpkgs.lib.nixosSystem {

hosts/tempest/default.nix

@@ -1,6 +1,8 @@
 # The Tempest
 # System configuration for my desktop
 
+# See [readme](../README.md) to explain how this file works.
+
 { inputs, globals, overlays, ... }:
 
 inputs.nixpkgs.lib.nixosSystem {