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 |