docs(nix): clarify completed Nix prose

flake.nix

@@ -2,13 +2,13 @@
   description = "alexion.dev";
 
   inputs = {
-    # Base nixpkgs channel.
+    # Provides the base nixpkgs channel.
     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
 
-    # Fresher packages, reachable per-package as `unstable.<name>`.
+    # Provides newer packages through `unstable.<name>`.
     nixpkgs-unstable.url = "github:nixos/nixpkgs/nixpkgs-unstable";
 
-    # Latest stable release, reachable per-package as `stable.<name>`.
+    # Provides the latest stable release through `stable.<name>`.
     nixpkgs-stable.url = "github:nixos/nixpkgs/nixos-26.05";
 
     home-manager = {
@@ -16,61 +16,62 @@
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # Signed AMO extensions, pinned by version and hash.
+    # Provides signed AMO extensions pinned by version and hash.
     firefox-addons = {
       url = "gitlab:rycee/nur-expressions?dir=pkgs/firefox-addons";
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # Follows our nixpkgs so its plugins build against the same package set.
+    # Uses this flake's nixpkgs so plugins build against the same package set.
     nixvim = {
       url = "github:nix-community/nixvim";
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # Declarative disk partitioning.
+    # Configures declarative disk partitioning.
-    # Each host declares its own layout.
+    # Each host declares its layout.
     disko = {
       url = "github:nix-community/disko";
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # Upstream per-machine hardware profiles.
+    # Provides upstream hardware profiles for each machine.
-    # Each host imports its own.
+    # Each host imports its profile.
     nixos-hardware = {
       url = "github:NixOS/nixos-hardware";
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # Decrypts committed secrets at activation, from an age identity on the host.
+    # Decrypts committed secrets at activation with an age identity on the host.
     sops-nix = {
       url = "github:Mic92/sops-nix";
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # Themes the graphical layer from one base16 scheme.
+    # Themes the graphical layer with one base16 scheme.
-    # Follows our nixpkgs so it themes the same package set the host builds.
+    # Uses this flake's nixpkgs so it themes the host package set.
     stylix = {
       url = "github:danth/stylix";
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # TODO: deprecate / remove
+    # TODO: Deprecate and remove this input.
-    # Agent-ergonomic CLI for Gitea, with a home-manager module for the agent context.
+    # Provides a Gitea CLI for agents.
+    # Its Home Manager module configures agent context.
     gitea-axi = {
       url = "git+https://git.alexion.dev/alexion/gitea-axi";
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # Repository formatter and Nix lint wiring.
+    # Configures the repository formatter and Nix linter.
     treefmt-nix = {
       url = "github:numtide/treefmt-nix";
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # CachyOS kernel and binary cache.
+    # Provides the CachyOS kernel and binary cache.
-    # This must not follow this flake's nixpkgs because Chaotic builds against its own pinned package set.
+    # Uses its pinned package set because Chaotic builds against it.
-    # Its cache serves the kernel only when the overlay stays on the cache-friendly path.
+    # Its cache serves the kernel only when the overlay uses the cache-friendly path.
     chaotic.url = "github:chaotic-cx/nyx/nyxpkgs-unstable";
   };
 

src/dotfiles/registry.nix

@@ -35,7 +35,8 @@ in
         type = lib.types.attrsOf (lib.types.attrsOf registry.type);
         default = { };
         description = ''
-          Lazily collected fleet-visible registry entries, nested by host and entry name.
+          Stores registry entries that the collector exposes to the fleet.
+          Nests entries by host and entry name.
         '';
       }
     ) definitions;

src/dotfiles/registry/schema.nix

@@ -5,14 +5,14 @@ let
       assertion = lib.mkOption {
         type = lib.types.functionTo lib.types.bool;
         description = ''
-          Predicate run against this registry's flattened collected entries.
+          Tests this registry's flattened collected entries.
         '';
       };
 
       message = lib.mkOption {
         type = lib.types.str;
         description = ''
-          Error message shown when this registry validation check fails.
+          Describes the registry validation failure.
         '';
       };
     };
@@ -23,7 +23,7 @@ in
     type = lib.mkOption {
       type = lib.types.raw;
       description = ''
-        NixOS option type for one registry entry.
+        Defines the NixOS option type for one registry entry.
       '';
     };
 
@@ -31,7 +31,7 @@ in
       type = lib.types.bool;
       default = false;
       description = ''
-        Whether collected entries are merged and published under every host key.
+        Replicates collected entries under every host key.
       '';
     };
 
@@ -39,7 +39,7 @@ in
       type = lib.types.listOf checkType;
       default = [ ];
       description = ''
-        Validation checks for this registry's flattened collected entries.
+        Contains validation checks for this registry's flattened collected entries.
       '';
     };
   };