# 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.