docs: explain how consumers override public module defaults

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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

modules/home.nix

@@ -71,7 +71,7 @@ let
   '';
 in
 {
-  imports = [ ./gpg.nix ./media.nix ];
+  imports = [ ./gpg.nix ./media.nix ./texlive.nix ];
 
   # Put ~/.local/bin (the XDG user-bin dir) on PATH so hand-dropped scripts run
   # by name without wiring each through nix.
@@ -185,6 +185,14 @@ in
 
   programs.home-manager.enable = true;
 
+  # Document converter (md/html/docx/…). PDF output shells out to a LaTeX engine
+  # (texlive.nix): default it to xelatex, which is Unicode-native — pdflatex
+  # (pandoc's own default) fails on combining marks, e.g. U+0308 in decomposed ä.
+  programs.pandoc = {
+    enable = true;
+    defaults.pdf-engine = "xelatex";
+  };
+
   programs.git = {
     enable = true;
     settings = {

modules/texlive.nix

@@ -0,0 +1,32 @@
+# TeX Live for pandoc PDF output: pandoc shells out to a LaTeX engine, so PDF
+# conversion needs a TeX distribution (other formats — html, docx, md — do not).
+# The package set is an option so a consumer can swap the scheme without editing
+# this module: scheme-medium covers pandoc's default LaTeX template; override
+# for a larger set (missing .sty files) or a smaller one.
+#
+# TeX Live's font cache and config trees default to ~/.texlive<year> and ~/texmf
+# (written on the first PDF build). The TEXMF* vars route them to XDG dirs.
+
+{ config, lib, pkgs, ... }:
+
+{
+  options.local.texlive.package = lib.mkOption {
+    type = lib.types.package;
+    default = pkgs.texlive.withPackages (ps: [ ps.scheme-medium ]);
+    defaultText = lib.literalExpression
+      "pkgs.texlive.withPackages (ps: [ ps.scheme-medium ])";
+    description = "TeX Live package set. Override for a larger/smaller scheme.";
+  };
+
+  config = {
+    home.packages = [ config.local.texlive.package ];
+
+    # texmf-var is regenerable font/format cache → cacheHome; the other two hold
+    # user config/data trees.
+    home.sessionVariables = {
+      TEXMFHOME   = "${config.xdg.dataHome}/texmf";
+      TEXMFVAR    = "${config.xdg.cacheHome}/texlive/texmf-var";
+      TEXMFCONFIG = "${config.xdg.configHome}/texlive/texmf-config";
+    };
+  };
+}