docs(roadmap): close out Pillar 8 / Component 7 + correct templates row

Component 7 (Theme engine + palettes) closeout entry summarises the
three inline fixes (theme-set early-exit on missing dir; bg-set
state.json persistence + path validation; palette dead-surface
cleanup) plus the script-comment correction.

Updated the existing `themes/templates/*.tpl` Later row: the original
claim "no script in the tree consumes them" was wrong —
nomarchy-theme-set-templates does. Replaced with a concrete
categorisation: (a) functionally dead (alacritty/btop/chromium/swayosd
write to paths nothing reads), (b) superseded by Nix-side generators
(kitty/ghostty after 8d3ce2d), (c) still relevant
(hyprland/hyprlock/obsidian/keyboard.rgb plus the now-orphan
share-picker tpl to verify).

docs/ROADMAP.md

@@ -42,7 +42,7 @@ Guardrails (apply when adding anything):
 - **Surface support module** via the relevant `nixos-hardware` profile + Surface kernel patches behind a `nomarchy.hardware.isSurface` toggle.
 - **Consolidate palette imports in `flake.nix` via `nomarchyLib`.** `flake.nix:79-80` re-imports `./themes/palettes` and recomputes `themeNames` even though `lib/default.nix` already exports both. Two computations, same result today — drift risk tomorrow. Import `nomarchyLib = import ./lib { inherit lib; }` once and use `nomarchyLib.{palettes,themeNames}` to make `lib/default.nix` the single source of truth for the theme list.
 - **Decide what to do about `features/apps/chromium/Default/Preferences`.** The module deploys a static 204-byte `Default/Preferences` (setting `extensions.theme.use_system = false`, `browser.theme.color_scheme = 2`) into chromium's mutable profile directory via Home Manager symlink. Chromium expects to write that file at runtime, so either the symlink is silently replaced on first save (losing the static defaults) or the write fails silently. The real chromium theming work happens via managed policies in `core/system/browser.nix`. Probably the user-profile deployment should be removed; needs someone with chromium-internals knowledge to confirm before deletion.
-- **`themes/templates/*.tpl` — decide what these are for.** Eleven mustache-style templates (`alacritty.toml.tpl`, `btop.theme.tpl`, `kitty.conf.tpl`, etc.) are deployed to `~/.local/share/nomarchy/templates/` via `themes/engine/files.nix`, but no script in the tree consumes them. Likely vestigial from a pre-stylix templating system. Either delete the directory + the `xdg.dataFile` deployment, or document them as user-reference assets and explain how to use them.
+- **`themes/templates/*.tpl` — prune the truly dead, document the rest.** Eleven mustache-style templates deployed to `~/.local/share/nomarchy/templates/` via `themes/engine/files.nix`. Originally flagged as "no script consumes them" — that was wrong: `themes/engine/scripts/nomarchy-theme-set-templates` (called at the end of `nomarchy-theme-set`) reads them, substitutes palette colors, and writes the output to `~/.config/nomarchy/current/theme/<file>` only when no file is already there. Now categorise: **(a) functionally dead** — `alacritty.toml.tpl`, `btop.theme.tpl`, `chromium.theme.tpl`, `swayosd.css.tpl` all produce files at paths nothing reads (alacritty + swayosd are Stylix/Nix-themed; btop reads from `~/.config/btop/themes/nomarchy.theme` not from the theme symlink; chromium.theme references were deleted in `9b06b6c`). **(b) superseded** — `kitty.conf.tpl` and `ghostty.conf.tpl` are now generated by `themes/engine/files.nix` (commit `8d3ce2d`); the template path skips harmlessly via the "if not exists" check. **(c) still relevant** — `hyprland.conf.tpl`, `hyprlock.conf.tpl`, `obsidian.css.tpl`, `keyboard.rgb.tpl`, `hyprland-preview-share-picker.css.tpl` (this last one was orphaned when the share-picker dir was deleted in `20de3d4` — verify before keeping). Delete (a) + (b) + the orphan share-picker tpl; document the rest in `docs/creating-themes.md` as the layered override surface they actually are.
 - **Move `programs.uwsm` Hyprland session out of `core/system/virtualization.nix`.** Session-manager config is wired in the virtualization module by historical accident — it's loaded unconditionally on every install and has nothing to do with libvirt/docker. Move to a dedicated `core/system/session.nix` (or fold into the Hyprland feature module) so the location matches the responsibility.
 - **Route installer keymap into Hyprland's Wayland session.** `core/home/config/nomarchy/default/hypr/input.conf:3` hardcodes `kb_layout = us`. The installer writes `services.xserver.xkb.layout = "$KEYMAP_LAYOUT"` (and `console.keyMap`), but Hyprland reads its own input config on native Wayland, so a non-US user's chosen layout works in XWayland apps and the TTY console but not in native Wayland apps — surprising and inconsistent. Fix paths: (a) template `input.conf` from a new `nomarchy.keymap.{layout,variant}` home option that the installer writes alongside `formFactor`, or (b) propagate `XKB_DEFAULT_LAYOUT` via session env so Hyprland's fallback kicks in. Option (a) is the durable fix; needs the installer's heredoc to add the option write.
 - **Make `nomarchy.toggles.waybar` a Nix-level gate, or document it as runtime-only.** Today the toggle is exported as `NOMARCHY_TOGGLE_WAYBAR` env, consumed only by `nomarchy-toggle-waybar` (which pkill/exec's at runtime). The Nix module always sets `programs.waybar.enable = lib.mkDefault true`, so waybar comes back on every rebuild/reboot regardless of the toggle. Inconsistent with `toggles.idle`, which correctly gates `services.hypridle.enable`. Either gate `programs.waybar.enable` on the toggle (persistent) or rename the option to make its session-only nature obvious.
@@ -159,6 +159,7 @@ Pillar is **done** when every component has a closed `wave/qa-<component>` PR an
 
 (Move items here when they land — keep them brief, link the commit/PR.)
 
+- _2026-05-21_ — **Pillar 8 / Component 7 (Theme engine + palettes): closeout.** Code-review-shaped sweep across `themes/engine/{stylix,stylix-compat,loader,files,scripts}.nix`, the 23 theme-engine scripts, and the 21 palettes' file completeness. Three real fixes inline + targeted dead-surface cleanup: **(1)** `nomarchy-theme-set` printed a warning when the named theme directory didn't exist but continued executing — wrote the bad name into `state.json` and ran `nomarchy-env-update` on a broken state. Now `exit 1` after the warning. **(2)** `nomarchy-theme-bg-set` (called by the walker background-selector menu and by the `nomarchy-wallpaper` CLI) updated the live `~/.config/nomarchy/current/background` symlink + restarted swaybg but never wrote `state.json` — so every wallpaper picked via either path silently reverted to the theme default on the next `home-manager switch` (`themes/engine/files.nix` re-resolves `nomarchy.wallpaper` at every rebuild). Now writes the chosen path into `state.json.wallpaper`, mirroring `nomarchy-theme-bg-next`. Added a file-exists check so a bogus path fails loudly instead of leaving a dangling symlink + a crashed swaybg. **(3)** Palette tree dead-surface cleanup: deleted `themes/palettes/{flexoki-light,lumon,retro-82,rose-pine}/apps/chromium.theme` (9-byte RGB strings nothing reads — chromium is themed via managed policies in `core/system/browser.nix`, not per-palette files) and `themes/palettes/summer-day/apps/kitty/{kitty.conf,everforest-light.conf}` (a 76KB stray kitty config at the wrong nested path, superseded by the `kitty.conf` generator added in `8d3ce2d`). Total: 6 files / 2210 lines. Updated the misleading comment in `nomarchy-themes-prebuild` ("the installer wires this up") to reflect reality (the installer only tips the user to run it). Updated the `themes/templates/*.tpl` Later row with a fact-check + concrete categorisation — the templates ARE consumed by `nomarchy-theme-set-templates`, but most write to paths nothing reads or are now superseded by Nix-side generators. Palette completeness matrix: all 21 palettes have `colors.toml`, `backgrounds/`, `icons.theme`, and `apps/`; 5 carry the `light.mode` marker (catppuccin-latte, flexoki-light, rose-pine, summer-day, white); only tokyo-night ships `keyboard.rgb` for the ASUS ROG path, and the keyboard-set chain isn't wired into `nomarchy-theme-set` so it stays manual — niche enough to leave. Runtime verification (switch through all 22 palettes and eyeball SDDM + Plymouth + GTK + Qt + terminals + browsers + waybar + walker rendering) remains on the user.
 - _2026-05-21_ — **Pillar 8 / Component 6 (Apps): closeout.** Code-review-shaped sweep over `features/apps/{alacritty,btop,chromium,elephant,ghostty,kitty,lazygit,opencode,swayosd,tmux,vscode,walker}`. Three real theming bugs fixed inline: **(1)** `features/apps/kitty/config/kitty.conf:1` and `features/apps/ghostty/config/config:2` referenced palette-specific include files (`~/.config/nomarchy/current/theme/{kitty,ghostty}.conf`) that didn't exist for any of the 22 palettes — kitty include failed silently, ghostty's was optional (`?`-prefix), and both terminals rendered with their built-in defaults regardless of the active Nomarchy palette. Stylix's `kitty.enable = true` was a no-op because the module uses `xdg.configFile` instead of `programs.kitty`; ghostty has no Stylix target. Added theme-engine generators in `themes/engine/files.nix` mirroring the existing `waybar.css` pattern, mapping `palette.base*` to kitty/ghostty color directives. **(2)** `features/apps/btop/config/btop.conf:5` set `color_theme = "current"` but `themes/engine/loader.nix:72` deploys the active palette's btop theme to `~/.config/btop/themes/nomarchy.theme` — name mismatch, btop fell back to its built-in Default theme on every palette. Renamed to `"nomarchy"`. **(3)** `programs.vscode.profiles.default.userSettings.workbench.colorTheme` was set unconditionally from `themes/palettes/<theme>/apps/vscode.json`, but the matching theme extensions were bundled with `devExtensions` (default `false`) — so VSCode silently fell back to its built-in theme out of the box on every palette. Split `themeExtensions` (always-on, covers the 6 palettes whose theme extension is in nixpkgs) from `devExtensions` (opt-in). The remaining 15 palettes — including the default `summer-night` (`sainnhe.everforest`) — still break because their theme extensions aren't packaged in nixpkgs; logged as a new Later row. Chromium static `Default/Preferences` symlink already had an open Later row; verified the file's contents are duplicate of the managed-policy intent in `core/system/browser.nix`, so the existing entry's hypothesis is correct — left for the user to greenlight deletion. alacritty (Stylix-themed via `programs.alacritty.settings`), elephant (no UI), swayosd (base16 inline), walker (covered in Component 5), lazygit + tmux (terminal ANSI inheritance, transitively fixed by the kitty/ghostty changes), and opencode (minimal opt-in config) are healthy. Runtime verification (launch each app on each palette and eyeball the theming) remains the user's responsibility.
 - _2026-05-21_ — **Pillar 8 / Component 5 (Desktop stack): closeout.** Code-review-shaped sweep over Hyprland, waybar, walker, hypridle, hyprsunset, mako, KEYBINDINGS.md (the runtime-rendering subset — waybar across panel positions × form factors × all 22 palettes, walker launcher modes, hypridle timeout feel — stays on the user). Five real bugs fixed inline: **(1)** 9 of 17 `~/.config/nomarchy/default/hypr/apps/*.conf` window-rule files were deployed but never sourced, including `system.conf` (the `tag +floating-window` rules every TUI helper class relies on + `class:org.nomarchy.screensaver` fullscreen rule that hypridle's 150s on-timeout depends on) and `pip.conf` (the PiP pin/size rules). `apps.conf` now sources all 17. **(2)** Two `$NNOMARCHY_TOGGLE_*` typos (double-N) in `nomarchy-menu:330` and `nomarchy-launch-screensaver:16` made `toggles.suspend` and `toggles.screensaver` vacuous — Suspend always showed in the system menu and the screensaver always launched at idle regardless of the documented option. **(3)** 4 broken per-palette waybar `style.css` overrides (`catppuccin`, `lumon`, `nord`, `retro-82`) fully replaced the default style with 2–14 lines of only `@define-color` declarations — picking those palettes produced a waybar with zero structural styling. Default style already imports per-palette colors via `themes/engine/files.nix`-generated `theme/waybar.css`, so deletion restores correct rendering; `summer-day`/`summer-night` kept as legitimate 100+-line redesigns. **(4)** `core/home/config/nomarchy/default/hypr/{bindings,plain-bindings}.conf` were explicitly-labeled deprecated files sourced by nothing (plain-bindings.conf referenced undefined `$terminal`/`$browser`/etc. Hyprland vars) — deleted; `docs/SCRIPTS.md` regenerated to drop stale callers and incidentally corrected 4 Origin columns whose scripts moved from `core/system/scripts/` to `features/scripts/utils/`. **(5)** Mako post-fix (commit `2a301a0`) verified: deployment + the 4 referenced scripts (`nomarchy-notification-dismiss`, `nomarchy-launch-wifi`, `nomarchy-launch-floating-terminal-with-presentation`, `nomarchy-menu-keybindings`) all resolve. Two structural inconsistencies logged to Later: keymap routing (already in 72f7e7b) and the new hyprsunset toggle-vs-systemd reconcile. `KEYBINDINGS.md` regenerated with zero diff — generator already covers both binding source locations. Runtime verification (boot live ISO, eyeball waybar/walker/screensaver flows across panel positions and palettes) remains the user's responsibility before declaring Component 5 fully closed.
 - _2026-05-18_ — Hardware DB correctness pass + ROG Ally support + CI lint. Audited every `nomarchy-hardware-db` entry against `inputs.nixos-hardware.nixosModules` and found **21 of 43 entries (49%) referenced modules that don't exist** — `microsoft-surface-pro-8`, `lenovo-thinkpad-x1-carbon-gen11`, `framework-13-11th-gen-intel`, etc. were all eval-time failures waiting for a real user. Rewrote the DB to use only valid module names: Framework gens dropped the "13-" prefix in nixos-hardware (`framework-11th-gen-intel`, not `framework-13-11th-gen-intel`); ThinkPad X1 modules are `x1-Nth-gen`, not `x1-carbon-genN`; Surface Pro 6/7/8/10 all share `microsoft-surface-pro-intel`; Surface Book / Intel Surface Laptop have no module (rows dropped, generic detection still emits sensible `common-pc-laptop` + cpu/gpu). Added matchers for **ROG Ally** (RC71L / RC72LA / "ROG Ally" via `asus-ally-rc71l`). Documented Steam Deck and Snapdragon X as nixos-hardware-unsupported in a footer comment (Steam Deck → Jovian-NixOS; Snapdragon X → installer is x86_64 only). Added a CI step (`.forgejo/workflows/check.yml`) that fails on any DB entry whose module name isn't in `nixos-hardware.nixosModules` — closes this regression class.

themes/engine/scripts/nomarchy-theme-bg-set

@@ -1,7 +1,12 @@
 #!/bin/bash
 set -e
 
-# Sets the specified image as the current background
+# Sets the specified image as the current background.
+# Updates state.json so the choice survives the next rebuild — without
+# that write, themes/engine/files.nix re-resolves the wallpaper from
+# `nomarchy.wallpaper` on the next home-manager switch and silently
+# falls back to the active theme's default background, undoing the
+# user's pick.
 
 if [[ -z $1 ]]; then
   echo "Usage: nomarchy-theme-bg-set <path-to-image>" >&2
@@ -9,7 +14,22 @@ if [[ -z $1 ]]; then
 fi
 
 BACKGROUND="$1"
-CURRENT_BACKGROUND_LINK="$HOME/.config/nomarchy/current/background"
+
+if [[ ! -f "$BACKGROUND" ]]; then
+  echo "Background image not found: $BACKGROUND" >&2
+  exit 1
+fi
+
+STATE_DIR="$HOME/.config/nomarchy"
+STATE_FILE="$STATE_DIR/state.json"
+CURRENT_BACKGROUND_LINK="$STATE_DIR/current/background"
+
+mkdir -p "$STATE_DIR"
+[[ ! -f $STATE_FILE ]] && echo "{}" > "$STATE_FILE"
+
+# Persist the choice for the next rebuild.
+TMP_JSON=$(mktemp)
+jq --arg wp "$BACKGROUND" '.wallpaper = $wp' "$STATE_FILE" > "$TMP_JSON" && mv "$TMP_JSON" "$STATE_FILE"
 
 # Create symlink to the new background
 ln -nsf "$BACKGROUND" "$CURRENT_BACKGROUND_LINK"

themes/engine/scripts/nomarchy-theme-set

@@ -30,7 +30,8 @@ mkdir -p "$STATE_DIR"
 [[ ! -f $STATE_FILE ]] && echo "{}" > "$STATE_FILE"
 
 if [ ! -d "$THEMES_DIR/$THEME_NAME" ]; then
-  echo "Theme '$THEME_NAME' not found in $THEMES_DIR"
+  echo "Theme '$THEME_NAME' not found in $THEMES_DIR" >&2
+  exit 1
 fi
 
 TMP_JSON=$(mktemp)

themes/engine/scripts/nomarchy-themes-prebuild

@@ -2,8 +2,8 @@
 
 # Pre-realise every theme's Home Manager generation into the Nix store so
 # future `nomarchy-theme-set` swaps are cache hits — no Stylix rebuild, no
-# downloads. Run once after install (the installer wires this up) and again
+# downloads. Run once after install (the installer's final message prompts
-# after adding or updating palettes.
+# you to do so) and again after adding or updating palettes.
 
 set -e
 

themes/palettes/flexoki-light/apps/chromium.theme

@@ -1 +0,0 @@
-242,240,229

themes/palettes/lumon/apps/chromium.theme

@@ -1 +0,0 @@
-14,31,41

themes/palettes/retro-82/apps/chromium.theme

@@ -1 +0,0 @@
-0,23,46

themes/palettes/rose-pine/apps/chromium.theme

@@ -1 +0,0 @@
-210,196,219

themes/palettes/summer-day/apps/kitty/everforest-light.conf

@@ -1,44 +0,0 @@
-# A port of forest night by sainnhe
-# https://github.com/sainnhe/forest-night
-
-font_family JetBrainsMono Nerd Font
-font_size 12.0
-
-foreground            #323d43
-background            #fdf6e3
-selection_foreground  #e4e1cd
-selection_background  #d3dbc8
-url_color             #415c6d
-cursor                #7fbbb3
-
-# black
-color0   #4a555b
-color8   #525c62
-
-# red
-color1   #e68183
-color9   #e68183
-
-# green
-color2   #a7c080
-color10  #a7c080
-
-# yellow
-color3   #dbbc7f
-color11  #dbbc7f
-
-# blue
-color4  #7fbbb3
-color12 #7fbbb3
-
-# magenta
-color5   #d699b6
-color13  #d699b6
-
-# cyan
-color6   #83c092
-color14  #83c092
-
-# white
-color7   #f3efda
-color15  #f3efda