docs(nix): record local conventions

docs/nix.md

@@ -0,0 +1,35 @@
+# Nix Conventions
+
+This document records local Nix style and design conventions.
+Prefer these conventions when changing this flake.
+
+## Names
+
+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.
+
+## Imports
+
+Prefer explicit import arguments.
+Use exact function argument patterns without `...` when the imported file has a closed interface.
+Use `...` only when the file intentionally accepts extra arguments.
+
+## `let` bindings
+
+Minimize `let` bindings.
+Use a `let` binding when it names an important intermediate value or avoids repeated complex expressions.
+Do not use a `let` binding only to shorten a standard library call.
+
+## Standard library calls
+
+Prefer 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.
+
+## Flake assembly
+
+Keep flake assembly code under `flake/`.
+Do not expose assembly helpers as public flake outputs unless an external consumer needs them.
+Keep `flake.nix` focused on inputs and public outputs.