docs: explain how consumers override public module defaults

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-10 09:00:50 +02:00
parent b907a39c41
commit 3e093b02d1
1 changed files with 14 additions and 0 deletions
@@ -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