From fc834168aa552693a7aeee4d0b732c4e24504267 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Fri, 28 Aug 2026 10:54:25 -0400
Subject: [PATCH] docs(nix): define default file placement

---
 docs/nix.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/nix.md b/docs/nix.md
index 8e2fdf0..d27b792 100644
--- a/docs/nix.md
+++ b/docs/nix.md
@@ -66,6 +66,44 @@ 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.
 
+### Use `default.nix` for module directories with support files
+
+Use `default.nix` as the primary module when a module directory owns support files.
+Keep sibling files for data or code read by that primary module.
+
+Avoid:
+
+```text
+modules/shell/fish/fish.nix
+modules/shell/fish/config.fish
+```
+
+Use:
+
+```text
+modules/shell/fish/default.nix
+modules/shell/fish/config.fish
+```
+
+### Use non-module `default.nix` files only for directory assembly
+
+Outside `modules/`, use `default.nix` to connect files in its directory.
+Do not define primary assembly functions in `default.nix`.
+Put primary assembly functions in named files.
+
+Avoid:
+
+```text
+flake/default.nix  # defines mkHost
+```
+
+Use:
+
+```text
+flake/default.nix  # imports ./hosts.nix
+flake/hosts.nix    # defines mkHost
+```
+
 ## Function Arguments
 
 ### Use closed interfaces for assembly files and library files