docs(gtk): record GTK as a generated consumer

AGENTS.md listed GTK3/GTK4 among the covered consumers, but nothing generated
or installed a theme for it: the claim had been aspirational since the repo
started. It now describes what the code does, and says plainly that the old
state was a gap rather than a drift.

templates/qt-gtk/ documented both Qt and GTK as installed from upstream. Qt
still derives from catppuccin/Kvantum and GTK from catppuccin/gtk, but both
are generated here now, so the table and the gsettings line say 'udt'. Its
tracked gtk3-settings.ini carried the old theme name too, which made the
record disagree with the live config it mirrors.

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

1 files changed, 66 insertions, 0 deletions

diff --git a/templates/gtk/README.md b/templates/gtk/README.md
new file mode 100644
index 0000000..adfc092
--- /dev/null
+++ b/templates/gtk/README.md
@@ -0,0 +1,66 @@
+# GTK3 and GTK4
+
+Generated from the palette, installed as `~/.themes/udt`. One fixed name for
+every scheme, like Kvantum: the name is referenced by gsettings and by the
+GTK4 symlink, so a per-scheme name would mean rewriting both on every switch
+and leaving stale themes behind.
+
+Derived from `catppuccin/gtk` v1.0.3, which is **archived upstream**. Forking
+it is deliberate: it is the theme this desktop already ran, and it will not
+track future GTK4/libadwaita changes. Replacing it means replacing these
+templates, not editing a consumer.
+
+## What is substituted
+
+Colours appear in two forms and both are replaced: the hex (`#b7bdf8`) and the
+bare decimal triple GTK writes inside `rgba()` (`183, 189, 248`). Substitution
+is whole-file, not confined to the `@define-color` block at the tail, because
+the 8400 lines above it hardcode palette colours too. That was measured, not
+assumed: 338 occurrences in GTK3 and 328 in GTK4 sit outside the block.
+
+`#eff1f5` is upstream's foreground, which is Latte `text`, a near-white it
+pairs with a Macchiato background. It maps to the `fg` role so GTK text matches
+rofi, kitty and waybar rather than being brighter than all of them.
+
+The generator replaces `@ROLE_RGB@` before `@ROLE@`, because `@FG@` is a prefix
+of `@FG_RGB@` and the other order would eat the start of the triple placeholder
+and leave a literal `_RGB@` in the CSS.
+
+## What is left alone
+
+Neutral greys and upstream's derived tints: `#3e4152`, `#2e3143`, the
+`rgba(0, 0, 0, ...)` shadows, `#ffffff`, and the `*_500`/`*_700`/`*_900`
+Material swatch constants, which ship with every build and are not theme
+colour. Same rule as the Kvantum SVG: shading is not palette.
+
+Two derived values are mapped anyway, because they are semantic rather than
+shading: `17, 17, 27` (Latte crust, used as text on the accent) becomes
+`bg_deep`, and `182, 106, 119` (a darkened red on the close button) becomes
+`critical`.
+
+## Assets
+
+67 SVGs, carrying only three palette colours: `bg`, `bg_alt` and the accent,
+the last in 36 of them. The upstream `gtk-3.0/assets` and `gtk-4.0/assets`
+directories are byte-identical, so one templated set is rendered and copied
+into both.
+
+They are discovered from disk by the generator rather than listed, because
+they arrive as a set from upstream and a hand-written list would silently miss
+one added by a future refresh.
+
+## Gotchas
+
+- **GTK3 takes its theme name from gsettings on Wayland**, not `settings.ini`.
+  The file is written too, but gsettings wins; it was once pinned to `Breeze`,
+  silently overriding the file for who knows how long.
+- **GTK4 ignores `gtk-theme-name` entirely.** Its stylesheet is imported by
+  `~/.config/gtk-4.0/gtk.css` through the `theme` symlink.
+- **`gtk-dark.css` must exist** alongside `gtk.css`. Apps request one or the
+  other depending on the prefer-dark setting; upstream ships them identical.
+- **GTK apps only reread a theme at startup**, like Qt. A running app keeps the
+  old colours, which is why the accent here is the fixed fallback rather than
+  the wallpaper-tracking one.
+- **A placeholder with no matching role renders literally** and GTK drops the
+  declaration with no error. `udt-palette --selftest` asserts every placeholder
+  in these templates maps to a role, because 8500 lines is too much to eyeball.