From 3f24669f78c40587d4d088f454fb6a13a6e9edf1 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Fri, 28 Aug 2026 11:01:39 -0400
Subject: [PATCH] docs(nix): define assembly file ownership

---
 docs/nix.md | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/docs/nix.md b/docs/nix.md
index d27b792..a2f6149 100644
--- a/docs/nix.md
+++ b/docs/nix.md
@@ -11,7 +11,7 @@ Read this document with `docs/dictionary.md`.
 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.
+Use `dotfiles.mk<Name>` for assembly functions passed through module arguments.
 
 Avoid:
 
@@ -39,13 +39,13 @@ This keeps data-only functions separate from functions that carry flake context.
 Avoid:
 
 ```nix
-dotfiles.lib.mkHost { hostName = "neogaia"; }
+dotfiles.lib.mkGuest { name = "sample"; }
 ```
 
 Use:
 
 ```nix
-dotfiles.mkHost { hostName = "neogaia"; }
+dotfiles.mkGuest { name = "sample"; }
 ```
 
 ## File Placement
@@ -54,7 +54,7 @@ dotfiles.mkHost { hostName = "neogaia"; }
 
 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 library files under `lib/`.
 Put modules under `modules/`.
 Put host configurations under `hosts/<name>/`.
 Put host-side guest wiring under `guests/`.
@@ -101,7 +101,30 @@ Use:
 
 ```text
 flake/default.nix  # imports ./hosts.nix
-flake/hosts.nix    # defines mkHost
+flake/hosts.nix    # defines mkHosts
+```
+
+### Keep assembly files focused on one concept
+
+Give each assembly file under `flake/` one top-level concept.
+Keep helper functions private to that file when no other file needs them.
+Export the constructor for the concept when the concept has one.
+Name that constructor `mk<Concept>`.
+
+Avoid:
+
+```nix
+{
+  inherit collectNixFiles mkHost mkHosts;
+}
+```
+
+Use:
+
+```nix
+{
+  inherit mkHosts;
+}
 ```
 
 ## Function Arguments