docs: add AGENTS.md with the project's non-obvious constraintsHEADmaster

Records what cost real time to discover: that rofi's -dump-theme normalises
values and cannot tell you what renders, that measuring screenshot pixels beats
reasoning about the box model, that GTK3's theme comes from gsettings rather
than settings.ini on Wayland, that ClearlyU shadows Private Use Area glyphs in
fontconfig fallback, and why accent extraction must not go through wal -i.

CLAUDE.md is a thin pointer at it, matching the user's global convention.

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

1 files changed, 111 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..cbb4c14
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,111 @@
+# AGENTS.md
+
+Guidance for agents working in this repository.
+
+## What this is
+
+One visual identity for a Hyprland desktop: Catppuccin Macchiato, Noto Sans for
+UI text, Inconsolata Nerd Font Mono for monospace. It covers rofi, dunst,
+Hyprland window borders, conky, Qt5/Qt6, GTK3/GTK4, waybar, kitty and neovim.
+
+The repo holds the canonical copies. `./install.sh` symlinks them into place, so
+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.
+
+## The accent
+
+One colour moves: `@accent`. `bin/udt-accent` reads the current wallpaper,
+extracts its signature colour, and snaps it to the nearest of ten Catppuccin
+accents by perceptual hue in CIELAB. `wallp` calls it on every wallpaper change.
+
+It writes three things: `~/.cache/wal/udt-accent.rasi` (rofi),
+`~/.cache/wal/udt-border.lua` (Hyprland), and the accent substitution in
+`~/.cache/wal/dunstrc`.
+
+**Extraction is deliberately isolated from the pywal cache.** It calls
+`pywal.backends.colorz.get()` directly, which returns a list and writes nothing.
+Running `wal -i` instead would rewrite all of `~/.cache/wal`, including the
+terminal's ANSI colours, and that is the exact failure this design exists to
+avoid. If you change that function, verify `~/.cache/wal/colors.json` is
+byte-identical afterwards.
+
+Not everything tracks the wallpaper. rofi, dunst and Hyprland borders do; conky,
+Qt, GTK and waybar sit on fixed lavender, which is also the fallback when a
+wallpaper is too grey to snap. Qt and GTK apps only reread a theme on restart,
+so a moving accent there would leave running apps disagreeing with new ones.
+
+## Verifying visual changes
+
+`rofi -no-config -theme <absolute-path> -dump-theme >/dev/null` catches syntax
+errors without a display. It does **not** tell you what renders: it normalises
+values, prints `(null)` for every image, and collapses multi-value margins.
+
+For anything visual, screenshot and measure:
+
+    grim -o DP-1 /tmp/shot.png
+
+Reasoning about rofi's box model was wrong repeatedly during this project;
+measuring pixels was right every time. When a widget looks wrong, measure its
+bounding box before theorising about why.
+
+Rofi needs a display, so these steps run in the user's session. Do not judge
+them by exit code: rofi exits non-zero for ordinary reasons such as Escape.
+
+## Things that are not where they look
+
+- **rofi is 2.0.0**, not the 1.7.3 its config header claims. `rofi -v` is the
+  authority. `-width` is gone; width lives in the theme.
+- **`userimage` in `powermenu.rasi` only honours its margin.** A `width` with
+  `expand: false` collapses it to a line, and a percentage margin resolves
+  against the whole window rather than the padded column. Its 230px margin is
+  tied to the 680px column in `mainbox`; both move together.
+- **A layout that hardcodes `children` silently drops `-mesg`.** That is why
+  `list.rasi` lists the message widget even though most callers pass nothing.
+- **`ClearlyU` is installed and claims large parts of the Private Use Area**, so
+  it can win fontconfig's fallback and draw a blank where another font has the
+  glyph. `fc-match ":charset=XXXX" family` says who actually wins. The `U+F0xxx`
+  Nerd Font ranges avoid the problem.
+- **GTK3's theme comes from gsettings on Wayland**, not `settings.ini`. It was
+  pinned to `Breeze`, silently overriding the file, for who knows how long.
+- **GTK4 ignores `gtk-theme-name`.** Its stylesheet is symlinked into
+  `~/.config/gtk-4.0/theme` and imported by `gtk.css`.
+- **Hyprland's Lua parser refuses `hyprctl keyword`** ("keyword can't work with
+  non-legacy parsers") and has no source directive. The border colours are a Lua
+  table read with `dofile()`.
+- **`wallp` starts `swaybg` in the background**, which inherits the shell's
+  stdout, so a pipe or command substitution appears to hang after `wallp` has
+  already finished. Redirect its output when calling it from a script.
+- **waybar's own CLAUDE.md documents a stale CSS load order.** The
+  `modules-*.css` and `states.css` files it names are not imported by anything;
+  `style.css` pulls in `styles/main.css`. One of the dead files holds a
+  `font-family` that looks authoritative but does nothing.
+
+## Editing rules
+
+- **conky**: change colours in the `conky.config` block only. `conky.text` is
+  laid out with absolute `${goto}` pixel offsets tuned to label widths, so
+  editing text means re-tuning every goto on that line. See
+  `~/.config/conky/CLAUDE.md`. Conky does not hot-reload.
+- **Committed files carry no home paths.** A gitleaks hook blocks them, and it
+  has been right every time. Where a live config mixes theme keys with personal
+  data (`qt6ct.conf` has an `ignored_applications` list), track only the
+  theme-relevant keys.
+- **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`.
+- `bin/udt-accent --selftest` covers the snapping logic. Run it after touching
+  the colour maths.
+
+## Reloading
+
+| | How |
+| --- | --- |
+| rofi | nothing; the theme is read per launch |
+| dunst | `udt-accent` restarts it |
+| Hyprland | `hyprctl reload` |
+| waybar | `killall -SIGUSR2 waybar` |
+| kitty | `pkill -USR1 -x kitty` |
+| conky | restart it; no hot-reload |
+| Qt / GTK apps | restart the app |