Add assets/themes/README.md — theme architecture + hard-won gotchas

Documents layout, wiring, apply/reload, backup/restore, and the
debugging traps hit this session (Adwaita fallback, machine-generated
settings.ini, GTK4 separate config, @border collision, gtk-menu-images
scope, Whisker #id-not-.class, .gitignore inline comments).

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

assets/themes/README.md

@@ -0,0 +1,80 @@
+# NexusOS desktop theme
+
+XFCE/GTK desktop theme (distinct from the web UI in `interface/web/`).
+Lime-green + purple, dark, with tightened menus.
+
+## Layout
+
+| Path | What |
+|---|---|
+| `NexusOS/` | GTK2/3 + xfwm4 theme. **GTK3 CSS in `NexusOS/gtk-3.0/` is hand-maintained** (no build step). |
+| `NexusOS/gtk-3.0/colors.css` | All color tokens. Edit colors here, not in the widget files. |
+| `NexusOS-icons/` | Icon theme (inherits `Papirus-Dark`). |
+| `../../management/Mint-Y-Nexus/` | XFCE app-icon set. |
+| `_palette.py` + `*-src/build.py` | Regenerate gtk2 / icons / xfwm4 — **NOT gtk-3.0**. |
+| `install-theme.sh` | Idempotent restore of all the *wiring* (see below). |
+| `gtk3-user-overrides.css` | Symlinked to `~/.config/gtk-3.0/gtk.css`. |
+
+## How it's wired (the part backups miss)
+
+The files above are just *source*. What makes the desktop use them lives
+outside this folder and is recreated by `install-theme.sh`:
+
+- Symlinks: `~/.themes/NexusOS`, `~/.icons/NexusOS`, `~/.icons/Mint-Y-Nexus`,
+  `~/.config/gtk-3.0/gtk.css`.
+- xfconf: `xsettings` (`/Net/ThemeName`, `/Net/IconThemeName`,
+  `/Gtk/CursorThemeName`, `/Gtk/FontName`) and `xfwm4 /general/theme`.
+- `~/.config/gtk-3.0/settings.ini` **and** `~/.config/gtk-4.0/settings.ini`.
+
+Canonical values: theme `NexusOS`, icons `NexusOS`, cursor `DMZ-White`,
+font `Ubuntu 10`. Keep these in sync with `NexusOS/index.theme` and
+`install-theme.sh`.
+
+## Apply / reload after editing
+
+```bash
+xfconf-query -c xsettings -p /Net/ThemeName -s Adwaita
+xfconf-query -c xsettings -p /Net/ThemeName -s NexusOS
+xfdesktop --reload & xfce4-panel -r
+```
+
+Some apps cache the theme at startup and need a full restart.
+
+## Backup / restore
+
+- `bin/backup.sh` (run at home): snapshots live wiring into
+  `restore-snapshot/`, then lftp-mirrors the repo to the router.
+- `bin/restore.sh` / `bin/restore-full.sh`: pull back, rebuild
+  venv/frontend, then auto-run `install-theme.sh`.
+- The repo is git-tracked; **`backup.sh` mirrors `.git` too**, so if a
+  bulk `git add` is ever interrupted run `git gc --prune=now` before
+  backing up (a killed `git add -A` once left 4 GB of loose objects).
+
+## Gotchas (each cost real debugging time)
+
+1. **Theme silently falls back to Adwaita** if `gtk-theme-name` in
+   `settings.ini` and xfconf `xsettings/Net/ThemeName` disagree, or
+   point at a non-existent theme. Edits then have zero visible effect.
+2. **`settings.ini` is machine-generated** by xfsettingsd from
+   `xsettings.xml` — don't symlink it into the repo. **GTK4 has its own
+   `~/.config/gtk-4.0/settings.ini`** that xsettings does *not* override;
+   it must be reconciled separately (easy to forget).
+3. **`@border` == `@overlay_bg` (`#2e3236`)** in `colors.css`, so a
+   separator drawn in `@border` on an overlay surface is invisible. Use
+   `@border_strong` / `@menu_border`. Root collision is unfixed; patched
+   per-spot.
+4. **`gtk-menu-images`** toggles icons in classic GtkMenus only. It does
+   **not** affect the Whisker menu (separate widget tree).
+5. **Whisker menu**: the popup's identifier is set via
+   `gtk_widget_set_name()`, so CSS must target **`#whiskermenu-window`
+   (an #id), not `.whiskermenu-window` (a class)** — a class selector
+   matches nothing. The base `window.background` rule also outranks a
+   bare class; `#id` wins on both counts. Whisker version: 2.9.x.
+   Its app/category lists are `treeview`/`iconview`; restart
+   `xfce4-panel` to reload its CSS.
+6. **Menu surfaces** use `@menu_bg` (`#2a1d33`) / `@menu_border`
+   (`#4d3461`) — dark purple. Tooltips/menubars/cards stay on the gray
+   surface palette deliberately.
+7. **`.gitignore` does not support trailing/inline comments.** A
+   `Dir/ # note` line matches nothing — comments must be on their own
+   line. (This once let a `git add` start ingesting the 28 GB venv.)