docs(nix): refine function terminology

docs/dictionary.md

@@ -50,6 +50,10 @@ Use the simplest accurate word when a term is not listed.
 | 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`. |
+| assembly file | Nix | A Nix file under `flake/` that constructs flake outputs or module-system inputs. |
+| 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 Nix module or flake output. |
+| library function | Nix | A pure project function exposed under `dotfiles.lib`. |
 | Nix module | Nix | A Nix language unit that declares or sets options through the Nix module system. |
 | 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

@@ -2,21 +2,22 @@
 
 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 helper functions.
-Use `dotfiles.lib` for pure project helpers passed through module arguments.
-Use `dotfiles.<name>` for project assembly helpers passed through module arguments.
+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 = dotfilesHelpers;
+  lib = dotfilesFunctions;
 }
 ```
 
@@ -25,18 +26,36 @@ Use:
 ```nix
 {
   lib = nixpkgs.lib;
-  dotfiles.lib = dotfilesHelpers;
+  dotfiles.lib = dotfilesFunctions;
 }
 ```
 
-## Imports
+### Name project function namespaces by role
 
-### Use closed interfaces for helper imports
+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.
 
-Use exact function argument patterns for helper imports with closed interfaces.
-A helper import has a closed interface when the caller owns the argument set.
+Avoid:
+
+```nix
+dotfiles.lib.guest { name = "sample"; }
+```
+
+Use:
+
+```nix
+dotfiles.guest { name = "sample"; }
+```
+
+## 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.
-It rejects stale or accidental extra attributes.
+The imported file rejects stale or accidental extra attributes.
 
 Avoid:
 
@@ -59,11 +78,11 @@ Use:
 }:
 ```
 
-### Pass import arguments explicitly
+### Pass function arguments explicitly
 
-Pass only the values an imported helper file needs.
+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` for values that keep the same name.
+Use `inherit` only for values that keep the same name.
 
 Avoid:
 
@@ -83,7 +102,7 @@ import ./flake {
 ### Keep NixOS module interfaces open
 
 NixOS modules accept extra arguments because the module system owns their argument shape.
-Name the arguments the module uses.
+Name each argument the module uses.
 Keep `...` so the module accepts standard module arguments and special arguments.
 
 Avoid:
@@ -112,7 +131,7 @@ Use:
 ### Use `@` for forwarding wrappers
 
 Use `@` when a wrapper passes the complete argument set to another module function.
-Name the arguments the wrapper uses before `...`.
+Name each argument the wrapper uses before `...`.
 Forward the bound argument set unchanged.
 
 Avoid:
@@ -131,7 +150,7 @@ dotfiles.guest { name = "sample"; } args
 
 ## `let` Bindings
 
-### Use `let` for important intermediate values
+### Use `let` for named intermediate values
 
 Use a `let` binding when it names an important intermediate value.
 Use a `let` binding when it avoids repeated complex expressions.
@@ -152,13 +171,40 @@ Use:
 lib.mapAttrs f attrs
 ```
 
+### Keep `let` scopes local
+
+Place a `let` binding near the expression that needs it.
+Do not lift a value to a larger scope only for convenience.
+A larger scope makes the dependency look more important than it is.
+
+Avoid:
+
+```nix
+let
+  hostNames = lib.attrNames hosts;
+in
+{
+  names = hostNames;
+  count = lib.length hostNames;
+}
+```
+
+Use:
+
+```nix
+{
+  names = lib.attrNames hosts;
+  count = lib.length (lib.attrNames hosts);
+}
+```
+
 ## Standard Library Calls
 
 ### Qualify standard library calls in flake assembly
 
 Use qualified standard library calls inside flake assembly code.
 Use `lib.mapAttrs` instead of inheriting `mapAttrs` from `lib`.
-This keeps the source of helper functions visible.
+This keeps the source of each function visible.
 
 Avoid:
 
@@ -183,7 +229,7 @@ Keep flake assembly code under `flake/`.
 Keep `flake.nix` focused on inputs and public outputs.
 The `outputs` function returns each public output as an attribute.
 An external flake reads public outputs through `inputs.<name>.<output>`.
-`nix flake show` also displays public outputs.
+`nix flake show` displays public outputs.
 
 Avoid:
 
@@ -215,8 +261,8 @@ in
 ### Expose only supported flake outputs
 
 Use public outputs for the supported interface of this flake.
-Do not expose assembly helpers as public outputs unless an external consumer needs them.
-Keep internal helpers in `flake/` or `dotfiles` special arguments.
+Do not expose assembly functions as public outputs unless an external consumer needs them.
+Keep internal functions in assembly files or `dotfiles` special arguments.
 
 Avoid: