docs(overrides): user guide for opt-in icon packs

The only doc for the icon-pack override was a comment in the downstream
template. Add an "Icon pack" subsection to docs/OVERRIDES.md § Appearance
(the user-facing appearance-customization doc): the
`nomarchy-theme-sync set icons "<name>"` command, why only Papirus ships
by default (~1 GiB; extra packs opt-in), a known-packs table, and that
the choice is sticky across `apply` (presets carry no icon field).

Example names verified by building all four packs and listing their real
theme directories — corrected Qogir to its capitalized Qogir-Dark/Light
(a lowercase name silently falls back to hicolor). Hibernation needs no
new doc (README swapfile note + MIGRATION.md runbook + Power-menu row).

Verification: V0 (docs-only); command + variant names checked live.

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

agent/JOURNAL.md

@@ -17,6 +17,21 @@ Template:
 
 ---
 
+## 2026-07-10 — Icon overrides: user-facing docs (OVERRIDES.md)
+- **Task:** Bernardo asked whether the session's features need user docs.
+- **Did:** Hibernation already covered (README swapfile line, MIGRATION.md
+  runbook, discoverable Power-menu row) — no gap. Icons had one: the only
+  doc was the template comment. Added an "Icon pack" subsection to
+  `docs/OVERRIDES.md` § Appearance — `nomarchy-theme-sync set icons "<name>"`,
+  the known-packs table, the ~1 GiB/opt-in rationale, and that the choice is
+  sticky across `apply` (presets carry no icon field; verified `deep_merge`).
+- **Verified:** command path confirmed (`cmd_set` writes any dotted key;
+  `icons` is a schema key). **Built all 4 packs and listed real theme dirs**
+  to fix the examples — caught Qogir using capital `Qogir-Dark`/`Light`
+  (lowercase would silently fall back to hicolor). Docs-only (V0).
+- **Pending:** none.
+- **Next suggestion:** NEXT #76 `[blocked:hw]`; LATER/QA-sweep next.
+
 ## 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

docs/OVERRIDES.md

@@ -21,6 +21,32 @@ nomarchy-theme-sync set fonts.mono "FiraCode Nerd Font"
 nomarchy-theme-sync apply gruvbox          # whole palette
 ```
 
+### Icon pack
+
+Icons follow the active theme's light/dark mode using **Papirus** — the only
+icon pack shipped by default (Papirus alone is ~1 GiB, so extra packs are
+opt-in rather than a cost every install pays). To switch to another pack:
+
+```sh
+nomarchy-theme-sync set icons "Tela-dark"  # or "" to return to Papirus-by-mode
+```
+
+Only the pack you name is pulled into your system (the first switch downloads
+it). Known packs and an example theme name from each:
+
+| Set `icons` to… | Pack |
+|---|---|
+| `Papirus`, `Papirus-Dark`, `Papirus-Light` | Papirus (default; `""` auto-picks Dark/Light by mode) |
+| `Tela`, `Tela-dark`, `Tela-<color>[-dark]` | Tela (colors: blue, green, red, purple, nord, dracula, …) |
+| `Qogir`, `Qogir-Dark`, `Qogir-Light` | Qogir (note the capital D/L) |
+| `Reversal`, `Reversal-dark` | Reversal |
+| `Numix-Circle`, `Numix-Circle-Light` | Numix Circle |
+
+The choice is a **sticky global override** — it survives `apply <palette>`
+switches (presets don't carry an icon field). To add a pack that isn't listed,
+append a row to `iconPacks` in `modules/home/theme.nix`. Set `icons` to `""`
+any time to drop back to Papirus with automatic Dark/Light.
+
 These values are deliberately kept at normal priority in the modules, so they
 stay owned by the theme system. If you *insist* on pinning one in `home.nix`
 regardless of the active theme, use `lib.mkForce` (see §4) — but then the CLI