From 3e093b02d1ce98a902fa28ac40750696febeaf1b Mon Sep 17 00:00:00 2001 From: Daniel Fainberg Date: Fri, 10 Jul 2026 09:00:50 +0200 Subject: [PATCH] docs: explain how consumers override public module defaults Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 15f45ad..079d730 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,6 +15,20 @@ one as a flake input. Deploy happens from the private repo, not here. - secrets (keys, tokens, passwords) → **neither** repo; runtime files or a secrets manager decrypting to a path. See the SSH section. +## Overrides = options (the consumer contract) + +Private imports these modules **read-only** (flake input) — it can't patch a package list +or a hard-coded value in place. So anything a consumer might reasonably want to change is +exposed as an **option with a default**, never baked into config. That is what makes this +repo a *baseline others extend* rather than a fork-and-patch. + +Pattern (see `modules/texlive.nix`): option-bearing config lives in its own sub-module +under the `local.*` namespace, `imports`-ed by `home.nix`. A module that declares `options` +must use the split `{ options = …; config = …; }` form, so isolating it per file keeps +`home.nix` bare. Override is then one line, e.g. +`local.texlive.package = pkgs.texlive.withPackages (ps: [ ps.scheme-full ]);`. A plain value +with nothing to vary goes straight in the bare package list — no option, don't over-abstract. + ## Maxim: keep $HOME clean (XDG) Standing principle for every addition: minimise dotfiles/dirs in `$HOME`. Route a tool's