feat(theme): opt-in cross-pack icon overrides, no default bloat

theme.nix now resolves nomarchy.theme.iconThemePackage from a small
icon-pack registry (Papirus/Tela/Qogir/Reversal/Numix, matched by name
prefix). Default themes name Papirus-*, so the resolved package is the
plain papirus-icon-theme derivation — byte-identical closure, zero added
MB. Only when a theme's `icons` names a set from another pack is that
pack (and only it) symlinkJoined alongside papirus. stylix.nix consumes
it via mkDefault. Adding a pack is one iconPacks row.

Deliberately NOT shipping more packs by default: papirus alone is already
~1 GiB and each extra pack adds ~hundreds of MB, so variety is opt-in per
install (set `icons` in theme-state.json), not a default closure cost.
Documented in templates/downstream/home.nix + ROADMAP § Icon themes.

Verification: V1 (HM activationPackage builds). Eval proofs — default
resolves to plain papirus (zero delta); icons="Tela-dark" ->
nomarchy-icon-themes symlinkJoin (papirus+tela) with the name flowing,
without building tela; all 5 pack attrs exist in the pinned nixpkgs;
template-sot + option-docs + flake check green. No default visual change
(same papirus), so no screenshot; the opt-in render is downstream.

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

agent/BACKLOG.md

@@ -56,7 +56,6 @@ notify in a real session. Steps queued in HARDWARE-QUEUE. Close #76 on PASS.
   impermanence, BIOS/legacy boot.
 - **Boot-from-snapshot**: a systemd-boot equivalent of grub-btrfs.
 - **Night-light geo mode**: lat/long auto sunset/sunrise (means wlsunset).
-- **Per-theme icon overrides** / more icon packs (ROADMAP § Icon themes).
 - **MIPI/IPU software-ISP camera** support (no-UVC machines).
 - **VPN exit-node richer display** (country/city) (optional).
 - **NixOS release bump → v2** `[human]`: deliberate, hand-edited, never

agent/JOURNAL.md

@@ -17,6 +17,27 @@ Template:
 
 ---
 
+## 2026-07-10 — Icon themes: opt-in cross-pack overrides (no default bloat)
+- **Task:** LATER "per-theme icon overrides / more icon packs". Recon found
+  papirus is already ~1 GiB and ships only Papirus/Dark/Light (no free
+  variety); real variety needs extra packs at ~hundreds of MB each. Bernardo
+  chose the **opt-in, no-default-bloat** shape (over shipping packs).
+- **Did:** `theme.nix` resolves `nomarchy.theme.iconThemePackage` from a
+  small `iconPacks` registry (papirus·tela·qogir·reversal·numix, by name
+  prefix). Default themes name `Papirus-*` → resolves to the *plain* papirus
+  derivation (no symlinkJoin, identical closure); only a theme naming another
+  pack's set symlinkJoins that one pack in. `stylix.nix` uses it
+  (mkDefault). Opt-in note in `templates/downstream/home.nix`; ROADMAP §
+  Icon themes updated (incl. the deliberate no-default-packs decision).
+- **Verified:** **V1** — HM activationPackage builds (exit 0). Eval proofs:
+  default `iconThemePackage` = plain `papirus-icon-theme-*` (zero delta);
+  with `icons="Tela-dark"` → `nomarchy-icon-themes` symlinkJoin (papirus+tela)
+  and name flows, **without building tela**. All 5 pack attrs exist in the
+  pinned nixpkgs. `template-sot` + `option-docs` + `flake check` green.
+- **Pending:** none. No default visual change (identical papirus), so no
+  screenshot needed; the opt-in render is the downstream user's to see.
+- **Next suggestion:** NEXT still #76 `[blocked:hw]`; LATER/QA-sweep next.
+
 ## 2026-07-10 — #76 slice 3: hibernate VM test (V2 PASS) → #76 agent-complete
 - **Task:** BACKLOG #76 slice 3 — the mandatory V2 hibernate test + V3 queue.
 - **Did:** Added `checks.hibernate` (flake.nix), modeled on nixpkgs'

docs/ROADMAP.md

@@ -275,8 +275,17 @@ Design/decision records and a running log of shipped work (items marked
 - **Icon themes:** ✓ ships `papirus-icon-theme`; the resolved name lives on
   `nomarchy.theme.iconTheme` (the JSON's optional `icons` field, else
   Papirus-Dark/Light by `mode`) and feeds both Stylix's `gtk.iconTheme`
-  (Thunar/GTK apps) and rofi's `show-icons`. Remaining (optional): per-theme
+  (Thunar/GTK apps) and rofi's `show-icons`.
-  `icons` overrides for the presets, or shipping more icon packs.
+  ✓ **Opt-in cross-pack overrides (no default bloat):** `theme.nix` now
+  resolves `nomarchy.theme.iconThemePackage` from a small pack registry
+  (`iconPacks`: Papirus·Tela·Qogir·Reversal·Numix). Default themes name
+  `Papirus-*`, so the resolved package is the *plain* `papirus-icon-theme`
+  derivation — byte-identical closure, zero added MB. Only when a theme's
+  `icons` names a set from another pack is that pack (and only it)
+  symlinkJoined alongside papirus. Adding a pack = one `iconPacks` row.
+  **Deliberately NOT shipping more packs by default** (Bernardo 2026-07-10):
+  papirus alone is already ~1 GiB and each extra pack adds ~hundreds of MB,
+  so variety is opt-in per install, not a default closure cost.
 - **Nicer shell out of the box:** ✓ zsh is the default login shell, with a
   starship prompt themed from the JSON, autosuggestions + syntax
   highlighting, and modern-CLI ergonomics — `cat`→bat (theme "ansi", so it

modules/home/stylix.nix

@@ -60,10 +60,12 @@ in
       # GTK/file-manager/rofi icon theme, resolved from the JSON in
       # theme.nix (per-theme `icons`, else Papirus-Dark/Light by mode).
       # Stylix sets gtk.iconTheme from this; both dark/light point at the
-      # already-mode-resolved name.
+      # already-mode-resolved name. The package is papirus by default and
+      # only unions in another pack when a theme's `icons` names one
+      # (theme.nix — opt-in, no default closure bloat).
       icons = {
         enable = true;
-        package = lib.mkDefault pkgs.papirus-icon-theme;
+        package = lib.mkDefault t.iconThemePackage;
         dark = t.iconTheme;
         light = t.iconTheme;
       };

modules/home/theme.nix

@@ -164,10 +164,43 @@ let
     if parsed.icons != "" then parsed.icons
     else if parsed.mode == "light" then "Papirus-Light"
     else "Papirus-Dark";
+
+  # Icon-pack resolution — opt-in, no default bloat. Papirus is the shipped
+  # default and the ONLY icon pack in the closure unless a theme's `icons`
+  # names a set from another pack; then that pack (and only it) is
+  # union-joined alongside papirus. Because the default themes name
+  # `Papirus-*`, the resolved package below is byte-identical to
+  # papirus-icon-theme (no symlinkJoin, no added MB). To offer another set:
+  # add one row to `iconPacks` and set `icons = "<Name>"` in a theme JSON
+  # (see templates/downstream/home.nix). Referencing `pkgs.*` here is
+  # eval-only — a pack enters the closure solely when it is the matched one.
+  papirusPkg = pkgs.papirus-icon-theme;
+  iconPacks = [
+    # pkg + the theme-name prefixes it provides (packs ship many named
+    # variants under one prefix, e.g. Tela / Tela-dark / Tela-blue).
+    { pkg = papirusPkg;                   prefixes = [ "Papirus" "breeze" ]; }
+    { pkg = pkgs.tela-icon-theme;         prefixes = [ "Tela" ]; }
+    { pkg = pkgs.qogir-icon-theme;        prefixes = [ "Qogir" ]; }
+    { pkg = pkgs.reversal-icon-theme;     prefixes = [ "Reversal" ]; }
+    { pkg = pkgs.numix-icon-theme-circle; prefixes = [ "Numix" ]; }
+  ];
+  # The pack whose prefix matches the resolved name (null = unknown name →
+  # GTK falls back gracefully; papirus is still present).
+  matchedPack =
+    let m = lib.findFirst
+      (p: lib.any (pre: lib.hasPrefix pre iconTheme) p.prefixes) null iconPacks;
+    in if m == null then null else m.pkg;
+  iconThemePackage =
+    if matchedPack == null || matchedPack == papirusPkg
+    then papirusPkg   # single pack → identical store path, zero closure delta
+    else pkgs.symlinkJoin {
+      name = "nomarchy-icon-themes";
+      paths = [ papirusPkg matchedPack ];
+    };
 in
 {
   config = {
-    nomarchy.theme = checked // { inherit iconTheme border; };
+    nomarchy.theme = checked // { inherit iconTheme border iconThemePackage; };
 
     # Feature toggles the menu writes (settings.nightlight.enable, …), exposed
     # alongside the appearance state. Feature modules mkDefault-read from here

templates/downstream/home.nix

@@ -17,6 +17,13 @@
   # nomarchy.terminal = "kitty";        # swap the default terminal
   # nomarchy.waybar.enable = false;     # bring your own bar
   # nomarchy.stylix.enable = false;     # opt out of GTK/Qt theming
+  #
+  # Icon pack: Papirus ships by default (auto Dark/Light by theme mode) and
+  # is the ONLY icon pack in your closure. To use another, set the `icons`
+  # field in your theme-state.json to a theme name from a known pack — only
+  # that pack is then added (no bloat otherwise). Known packs: Papirus,
+  # Tela, Qogir, Reversal, Numix (see modules/home/theme.nix `iconPacks`).
+  # e.g. theme-state.json:  "icons": "Tela-dark"
 
   # ── Opt-in features — uncomment and tweak to enable ─────────────────
   # nomarchy.nightlight = {             # scheduled blue-light filter (hyprsunset)