feat(palette): generate every themed config from one scheme

Colours were written down five times: rofi's palette.rasi, the waybar theme,
the kitty theme, the conky and dunst templates, and a MACCHIATO dict inside
udt-accent. Changing scheme meant finding all five, and they had already
drifted: the active waybar theme was Macchiato while theme.css next to it was
Mocha, and nothing imported the latter.

Now a scheme is two files. palette/<scheme>.conf holds the colours under the
scheme's own names, and palette/roles-<scheme>.conf says what each is for.
palette/roles.conf is one `scheme =` line selecting the pair. bin/udt-palette
renders that into each consumer's syntax and install.sh runs it first.

The role map is per-scheme rather than shared because the palettes are
genuinely different shapes: Nord has no `base`, Dracula no `surface0`, and
forcing Catppuccin's names onto them would have meant either renaming their
colours or inventing values. A role names a palette colour with two optional
modifiers, `name/75` for alpha and `name*50` for brightness. The second exists
because GTK's shade() has no palette name to point at.

Ships macchiato, tokyo-night, nord and dracula. --selftest resolves every role
in every scheme and asserts they define the same set, so a scheme that cannot
satisfy a consumer fails at install rather than when someone switches to it.

Verified against the live configs: all 46 waybar colours resolve identically to
the previously active theme including its alpha() and shade() derivations, the
kitty theme is colour-for-colour identical, and the rofi palette has the same
26 values. Generated files are gitignored; switching scheme and switching back
reproduces the originals.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015gbjA2bmswN8jyPDKzrvqe

1 files changed, 32 insertions, 1 deletions

diff --git a/AGENTS.md b/AGENTS.md
index cf9f914..fd40b57 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,6 +13,35 @@ the working config cannot drift from what is committed. Everything outside
 `~/.config/rofi/udt/` and `~/bin/` was edited in place; `docs/MIGRATION.md` is
 the record of what changed and where the backups are.
 
+## One palette, many consumers
+
+Colours are written down once. `palette/<scheme>.conf` holds them under the
+scheme's own names, `palette/roles-<scheme>.conf` says what each is for, and
+`palette/roles.conf` is a single `scheme = ` line selecting the pair.
+`bin/udt-palette` renders that into every consumer's own syntax; `install.sh`
+runs it first, before anything is linked.
+
+Four schemes ship: `macchiato`, `tokyo-night`, `nord`, `dracula`. Switching is
+one line plus `./install.sh`.
+
+Generated files are gitignored, because tracking them would turn every scheme
+switch into a diff. Editing one is pointless: the next install overwrites it.
+The generated set is `rofi/udt/palette.rasi`, `templates/dunstrc`,
+`templates/conky.conf`, `templates/waybar/theme.css`,
+`templates/terminal/kitty-theme.conf` and `bin/udt_colors.py`. The last is
+imported by `udt-accent`, which is why its accent table follows the scheme.
+
+Roles are a flat namespace, so a name collides across sections: conky's outline
+is `body_outline` because waybar already has `outline`. A role value is a
+palette name with two optional modifiers, `name/75` for 75% alpha and
+`name*50` for half brightness. The second exists only because GTK's
+`shade(@main-bg, 0.5)` has no palette name to point at: half-brightness crust
+is darker than the darkest colour any of these schemes ships.
+
+**Adding a scheme means adding two files, never editing a consumer.** Every
+scheme must define the same role set; `udt-palette --selftest` fails if one
+drifts, which is what stops a switch from breaking a config nobody looked at.
+
 ## The accent
 
 One colour moves: `@accent`. `bin/udt-accent` reads the current wallpaper,
@@ -111,7 +140,9 @@ them by exit code: rofi exits non-zero for ordinary reasons such as Escape.
 - **Themes that reference an image cannot be committed with a real path.**
   `launcher.rasi` carries an `@WPAPER@` placeholder that `install.sh` rewrites.
   rofi does not expand `~` inside a `url()`.
-- After editing anything under `rofi/udt/`, run `./install.sh`.
+- After editing anything under `rofi/udt/` or `palette/`, run `./install.sh`.
+- `bin/udt-palette --selftest` resolves every role in every scheme. Run it
+  after touching a palette, a role map, or the generator.
 - `bin/udt-accent --selftest` covers the snapping logic. Run it after touching
   the colour maths.