From 8493f128292a72bc9d223b15bc041857e0feefc2 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Fri, 28 Aug 2026 10:12:56 -0400
Subject: [PATCH] docs(nix): clarify let binding rules

---
 docs/nix.md | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/docs/nix.md b/docs/nix.md
index cc7ccee..67b6408 100644
--- a/docs/nix.md
+++ b/docs/nix.md
@@ -131,30 +131,33 @@ Use:
 
 ## `let` Bindings
 
-### Use `let` for named intermediate values
+### Use `let` to name concepts
 
-Use a `let` binding when it names an important intermediate value.
-Use a `let` binding when it avoids repeated complex expressions.
-Do not use a `let` binding only to shorten a standard library call.
+Use a `let` binding when the name explains the value's role.
+Use a `let` binding when multiple expressions share one important value.
+Do not use a `let` binding only to shorten a function call.
 
 Avoid:
 
 ```nix
 let
-  inherit (lib) mapAttrs;
+  names = lib.attrNames hosts;
 in
-mapAttrs f attrs
+lib.genAttrs names mkHost
 ```
 
 Use:
 
 ```nix
-lib.mapAttrs f attrs
+let
+  hostNames = lib.attrNames hosts;
+in
+lib.genAttrs hostNames mkHost
 ```
 
-### Keep `let` scopes local
+### Keep `let` bindings near their use
 
-Place a `let` binding near the expression that needs it.
+Place a `let` binding in the smallest 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.
 
@@ -165,8 +168,8 @@ let
   hostNames = lib.attrNames hosts;
 in
 {
-  names = hostNames;
-  count = lib.length hostNames;
+  hostCount = lib.length hostNames;
+  nixosConfigurations = flakeAssembly.mkHosts (self + "/hosts");
 }
 ```
 
@@ -174,8 +177,8 @@ Use:
 
 ```nix
 {
-  names = lib.attrNames hosts;
-  count = lib.length (lib.attrNames hosts);
+  hostCount = lib.length (lib.attrNames hosts);
+  nixosConfigurations = flakeAssembly.mkHosts (self + "/hosts");
 }
 ```