docs(nix): tighten writing style

This reverts commit 4a422599c7.

AGENTS.md

@@ -4,13 +4,16 @@ One flake builds every machine I own.
 
 ## Repository Conventions
 
-- Follow `docs/technical-writing.md` for comments, user-facing descriptions, commit prose, pull-request prose, and Markdown documentation.
+- Use `docs/technical-writing.md` and `docs/dictionary.md` while authoring any file.
+  Apply them to comments, user-facing descriptions, commit prose, pull-request prose, and Markdown documentation.
 - Comments posted to the forge under the operator's account must end with `— Pi`.
   The sign-off identifies the agent as the author instead of the operator.
 - Commit messages follow Conventional Commits, defined in `docs/conventional-commits.md`.
   Use a scope for the changed module or host, such as `fish`, `nvim`, or `neogaia`.
 - Keep commit messages about the Git history, not the forge workflow.
   Do not reference issue or pull-request numbers unless the commit itself requires a stable external reference.
+- During pull-request development, add follow-up commits instead of amending existing commits.
+  Preserve review history until the pull request is ready to merge.
 - Use `gitea-axi` for Gitea issues, pull requests, labels, reviews, comments, and milestones.
   It resolves this repository from the `origin` remote inside the checkout.
 
@@ -66,7 +69,7 @@ One flake builds every machine I own.
 - Guest modules are host-agnostic wiring, while host files own deployment-specific service configuration such as served volumes and host paths.
   For example, `guests/copyparty.nix` should expose options and translate them into guest mounts/service settings, while `hosts/pikachu/default.nix` chooses `/inbox`, `/media`, and their backing paths.
   Guest addresses and routes are host-level configuration because a guest module can be used on multiple hosts.
-- `self.lib.registry.collect { hosts = self.nixosConfigurations; }` reads only top-level host `config.registry` declarations.
+- The registry collector reads only top-level host `config.registry` declarations.
   Registry declarations inside guest interiors live under `config.containers.<guest>.config.registry`.
   The collected registry does not include those guest-interior declarations.
   Publish guest values from host-side code, or extend the collector to recurse into guests.

docs/dictionary.md

@@ -45,11 +45,15 @@ Use the simplest accurate word when a term is not listed.
 | operator | Agent tooling | The human driving the development process. Use when distinguishing the human from the agent acting on their behalf. |
 | guest | dotfiles | A systemd-nspawn container managed by this flake. Use for configured containers under `guests/`. |
 | host | dotfiles | A machine with a NixOS configuration built by this flake. |
-| module | dotfiles | In this repository, a self-contained configuration under `modules/`, usually scoped to one program, service, or subsystem. Use `Nix module` for the language-level module-system concept. |
+| module | dotfiles | In this repository, a self-contained configuration under `modules/`. Use for one program, service, or subsystem. |
 | registry | dotfiles | A typed configuration namespace whose entries can be collected across hosts and reused by other configuration. |
 | Conventional Commits | Git | A commit-message format defined in `docs/conventional-commits.md`. |
 | forge | Git | A web service that hosts Git repositories, pull requests, issues, and code review comments. Use when the exact provider does not matter. |
 | flake | Nix | A Nix project with pinned inputs and declared outputs. Use for the repository-level build unit defined by `flake.nix`. |
-| Nix module | Nix | A Nix language unit that declares or sets options through the Nix module system. |
+| assembly file | Nix | A Nix file under `flake/` that constructs flake outputs or arguments passed to NixOS modules. |
+| assembly function | Nix | A project function exposed under `dotfiles` because it creates modules, systems, or assembly values. |
+| library file | Nix | A Nix file that defines reusable project functions instead of a NixOS module or flake output. |
+| library function | Nix | A pure project function exposed under `dotfiles.lib`. |
+| NixOS module | Nix | A Nix file evaluated by `nixosSystem` for a NixOS configuration. |
 | overlay | Nix | A function that modifies a Nix package set by adding or replacing packages. |
 | workspace | Window management | A named or numbered group of windows in a graphical session. Some desktop environments call this a virtual desktop. |

docs/nix.md

@@ -0,0 +1,197 @@
+# Nix Conventions
+
+This document records local Nix style and design conventions.
+Use these conventions when changing this flake.
+Read this document with `docs/dictionary.md`.
+
+## Names
+
+### Reserve `lib` for `nixpkgs.lib`
+
+Use `lib` only for the base `nixpkgs.lib` value.
+Do not use `lib` for project functions.
+Use `dotfiles.lib` for library functions passed through module arguments.
+Use `dotfiles.<name>` for assembly functions passed through module arguments.
+
+Avoid:
+
+```nix
+{
+  lib = dotfilesFunctions;
+}
+```
+
+Use:
+
+```nix
+{
+  lib = nixpkgs.lib;
+  dotfiles.lib = dotfilesFunctions;
+}
+```
+
+### Name project function namespaces by role
+
+Put pure project functions under `dotfiles.lib`.
+Put functions that create modules, systems, or assembly values under `dotfiles`.
+This keeps data-only functions separate from functions that carry flake context.
+
+Avoid:
+
+```nix
+dotfiles.lib.mkHost { hostName = "neogaia"; }
+```
+
+Use:
+
+```nix
+dotfiles.mkHost { hostName = "neogaia"; }
+```
+
+## File Placement
+
+### Put files in the directory that owns their role
+
+Choose the file location before writing a Nix file.
+Put assembly files under `flake/`.
+Do not add library files until this repository has a library directory.
+Put modules under `modules/`.
+Put host configurations under `hosts/<name>/`.
+Put host-side guest wiring under `guests/`.
+Put registry definitions under `registry/`.
+Keep `flake.nix` focused on inputs and output wiring.
+Do not add root-level Nix files other than `flake.nix`.
+
+A module is self-contained configuration under `modules/`.
+A module configures one program, service, or subsystem.
+Files under `hosts/`, `guests/`, and `modules/` return NixOS modules.
+
+## Function Arguments
+
+### Use closed interfaces for assembly files and library files
+
+Use exact function argument patterns for assembly files and library files.
+The caller owns the argument set for these files.
+The imported file names each accepted attribute.
+The imported file rejects stale or accidental extra attributes.
+
+Avoid:
+
+```nix
+{
+  inputs,
+  lib,
+  self,
+  ...
+}:
+```
+
+Use:
+
+```nix
+{
+  inputs,
+  lib,
+  self,
+}:
+```
+
+### Pass function arguments explicitly
+
+Pass only the values an assembly file or library file needs.
+Bind `lib` to the base `nixpkgs.lib` value at the call site.
+Use `inherit` only for values that keep the same name.
+
+Avoid:
+
+```nix
+import ./flake inputs
+```
+
+Use:
+
+```nix
+let
+  inherit (nixpkgs) lib;
+in
+import ./flake { inherit lib inputs self; }
+```
+
+### Keep NixOS module interfaces open
+
+Files under `hosts/`, `guests/`, and `modules/` return NixOS modules.
+`nixosSystem` owns their argument shape.
+Name each argument the module uses.
+Keep `...` so the module accepts standard arguments and special arguments.
+
+Avoid:
+
+```nix
+{
+  config,
+  lib,
+  pkgs,
+  registry,
+}:
+```
+
+Use:
+
+```nix
+{
+  config,
+  lib,
+  pkgs,
+  registry,
+  ...
+}:
+```
+
+## `let` Bindings
+
+### Use role-specific binding names
+
+A `let` binding name must explain the value's role in the expression.
+Avoid names that describe only the value's type.
+
+Avoid:
+
+```nix
+let
+  names = lib.attrNames hosts;
+in
+lib.genAttrs names mkHost
+```
+
+Use:
+
+```nix
+let
+  hostNames = lib.attrNames hosts;
+in
+lib.genAttrs hostNames mkHost
+```
+
+## Standard Library Calls
+
+### Qualify standard library calls in flake assembly
+
+Use qualified standard library calls inside assembly files.
+Use `lib.mapAttrs` instead of inheriting `mapAttrs` from `lib`.
+This keeps the source of each function visible.
+
+Avoid:
+
+```nix
+let
+  inherit (lib) mapAttrs;
+in
+mapAttrs f attrs
+```
+
+Use:
+
+```nix
+lib.mapAttrs f attrs
+```
+

flake.nix

@@ -76,14 +76,11 @@
     { self, nixpkgs, ... }@inputs:
     let
       inherit (nixpkgs) lib;
-      my = import ./lib { inherit lib inputs self; };
+      flake = import ./flake { inherit lib inputs self; };
     in
     {
-      # Helper functions for discovering and building hosts.
-      lib = my;
-
       # Every host under hosts/ is discovered and built.
-      nixosConfigurations = my.mkHosts (self + "/hosts");
+      nixosConfigurations = flake.mkHosts (self + "/hosts");
 
       # A project shell for agent-local resources that should travel with this
       # checkout rather than the operator's global profile.

flake/default.nix

@@ -4,28 +4,19 @@
   self,
 }:
 let
-  inherit (lib)
-    attrNames
-    filterAttrs
-    genAttrs
-    flatten
-    hasSuffix
-    mapAttrsToList
-    ;
-
-  registry = import ./registry.nix { inherit lib self; };
+  registryAssembly = import ./registry.nix { inherit lib self; };
 
   collectNixFiles =
     dir:
-    flatten (
-      mapAttrsToList (
+    lib.flatten (
+      lib.mapAttrsToList (
         name: type:
         let
           path = dir + "/${name}";
         in
         if type == "directory" then
           collectNixFiles path
-        else if type == "regular" && hasSuffix ".nix" name then
+        else if type == "regular" && lib.hasSuffix ".nix" name then
           [ path ]
         else
           [ ]
@@ -35,14 +26,28 @@ let
   moduleFiles = collectNixFiles (self + "/modules");
   guestFiles = collectNixFiles (self + "/guests");
 
+  collectedRegistry = registryAssembly.collect { hosts = self.nixosConfigurations; };
+
   specialArgs = {
-    inherit inputs self;
-    my = self.lib;
-    registry = self.lib.registry.collect { hosts = self.nixosConfigurations; };
+    inherit
+      dotfiles
+      inputs
+      self
+      ;
+    registry = collectedRegistry;
   };
 
   bridgeName = id: "br-vlan${toString id}";
 
+  dotfiles = {
+    inherit (guests) guest;
+
+    lib = {
+      inherit bridgeName;
+      inherit (guests) deriveMac;
+    };
+  };
+
   guests = import ./guests.nix {
     inherit
       inputs
@@ -51,7 +56,7 @@ let
       specialArgs
       bridgeName
       moduleFiles
-      registry
+      registryAssembly
       ;
   };
 
@@ -70,7 +75,7 @@ let
           inputs.disko.nixosModules.disko
           inputs.sops-nix.nixosModules.sops
           inputs.stylix.nixosModules.stylix
-          registry.module
+          registryAssembly.module
           (self + "/hosts/${hostName}")
           {
             networking.hostName = hostName;
@@ -82,19 +87,10 @@ let
   mkHosts =
     hostsDir:
     let
-      hostNames = attrNames (filterAttrs (_name: type: type == "directory") (builtins.readDir hostsDir));
+      hostNames = lib.attrNames (lib.filterAttrs (_name: type: type == "directory") (builtins.readDir hostsDir));
     in
-    genAttrs hostNames (hostName: mkHost { inherit hostName; });
+    lib.genAttrs hostNames (hostName: mkHost { inherit hostName; });
 in
 {
-  inherit
-    collectNixFiles
-    mkHost
-    mkHosts
-    bridgeName
-    registry
-    ;
-
-  inherit (guests) deriveMac guest;
-
+  inherit mkHosts;
 }

flake/guests.nix

@@ -5,7 +5,7 @@
   specialArgs,
   bridgeName,
   moduleFiles,
-  registry,
+  registryAssembly,
 }:
 let
   inherit (lib) escapeShellArg mapAttrsToList;
@@ -136,7 +136,7 @@ let
           enable = lib.mkEnableOption "a reverse-proxy route for this guest";
 
           route = lib.mkOption {
-            type = self.lib.registry.definitions.route.type;
+            type = registryAssembly.definitions.route.type;
             description = "Route registry entry published for this guest.";
           };
         };
@@ -351,7 +351,7 @@ let
             imports =
               moduleFiles
               ++ [
-                registry.module
+                registryAssembly.module
                 inputs.sops-nix.nixosModules.sops
                 inputs.stylix.nixosModules.stylix
                 {

guests/actualbudget.nix

@@ -1,7 +1,7 @@
 {
   config,
   lib,
-  my,
+  dotfiles,
   ...
 }:
 let
@@ -10,7 +10,7 @@ let
 in
 {
   imports = [
-    (my.guest {
+    (dotfiles.guest {
       name = "actualbudget";
       interior = {
         modules.services.actualbudget = {

guests/copyparty.nix

@@ -1,7 +1,7 @@
 {
   config,
   lib,
-  my,
+  dotfiles,
   ...
 }:
 let
@@ -35,7 +35,7 @@ let
 in
 {
   imports = [
-    (my.guest {
+    (dotfiles.guest {
       name = "copyparty";
       interior = {
         modules.services.copyparty = {

guests/nesting-sample.nix

@@ -1,7 +1,7 @@
-args@{ my, ... }:
+args@{ dotfiles, ... }:
 # A sample guest whose interior runs an OCI container on Podman.
 # The image is pulled at runtime, so the guest builds with no build-time fetch.
-my.guest {
+dotfiles.guest {
   name = "nesting-sample";
   interior = {
     virtualisation.oci-containers.containers.hello = {

guests/reverse-proxy.nix

@@ -1,7 +1,7 @@
 {
   config,
   lib,
-  my,
+  dotfiles,
   ...
 }:
 let
@@ -9,7 +9,7 @@ let
 in
 {
   imports = [
-    (my.guest {
+    (dotfiles.guest {
       name = "reverse-proxy";
       interior = {
         modules.services.reverse-proxy.enable = true;

guests/sample.nix

@@ -1,5 +1,5 @@
-args@{ my, ... }:
+args@{ dotfiles, ... }:
 # The tracer-bullet guest: the thinnest complete path from discovery to a
 # running nested container. Its interior is just the guest-base — the baseline
 # toolset and SSH access — so it proves the concept without carrying a service.
-my.guest { name = "sample"; } args
+dotfiles.guest { name = "sample"; } args

modules/default.nix

@@ -1,6 +1,7 @@
 {
   config,
   lib,
+  dotfiles,
   pkgs,
   inputs,
   ...
@@ -63,8 +64,7 @@ in
       useGlobalPkgs = true;
       useUserPackages = true;
       extraSpecialArgs = {
-        inherit inputs;
-        my = inputs.self.lib;
+        inherit dotfiles inputs;
       };
       users.${user.name} = {
         home.username = user.name;

modules/network/vlans.nix

@@ -1,14 +1,14 @@
 {
   config,
   lib,
-  my,
+  dotfiles,
   ...
 }:
 # The host networking foundation: per-VLAN bridges over a tagged trunk.
 let
   cfg = config.modules.network.vlans;
 
-  inherit (my) bridgeName;
+  inherit (dotfiles.lib) bridgeName;
 
   vlanName = id: "${cfg.trunk}.${toString id}";
 in