1 files changed, 63 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4b44a10
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,63 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## What this is
+
+`rofi-scripts`: the shell scripts that open rofi menus on a Hyprland desktop.
+Plain bash or POSIX sh, one file per menu under `bin/`, no build step. Runtime
+deps are rofi 2.0 plus whatever each menu drives (pass, grimblast, notifyctl,
+sd-server, firefox).
+
+`./install.sh` symlinks every file in `bin/` into `~/bin/`, so edits are live
+on the next launch. The names are the ones hypr-theme's keybindings call
+(`udt-powermenu.sh`, `qar-scrotmenu.sh`, `blackpearl-sshmenu.sh`, ...), so a
+rename here must be matched there.
+
+## The themes live elsewhere
+
+Every script points rofi at a layout under `~/.config/rofi/udt/`, which the
+sibling `unified-desktop-theme` repo installs. This repo holds no `.rasi`.
+A layout change (header, card grid, banner) belongs there; here only the
+per-menu bits passed on the command line: `-p` title, `-mesg`,
+`-theme-str` overrides, keybindings.
+
+Menus on the searchable layouts (`list.rasi`, `grid.rasi`, `ssh.rasi`) show a
+wallpaper banner with the `-p` text as a title plate above the search bar.
+The house style for that title is a Nerd Font glyph, two spaces, a word and a
+colon: `'󰌋  Pass:'`. Pick glyphs from the `U+F0xxx` range; `ClearlyU` claims
+much of the older Private Use Area and draws a blank instead.
+`fc-match ":charset=f030b" family` says which font wins.
+
+## Gotchas
+
+- **One quoted string per `-theme-str`.** rofi 2.0's lexer reads from the
+  first `"` to the last, so `textbox { font: "A"; } entry { placeholder: "B"; }`
+  in one argument silently swallows the second block. Pass two `-theme-str`.
+- **Glyph-only elements need `children: [ element-text ]`** in their layout,
+  or the hidden icon slot pushes the glyph off centre.
+- Do not judge a menu by exit code: rofi exits non-zero on Escape.
+
+## Conventions
+
+- New menu: one file in `bin/`, license header, then `./install.sh`.
+- Placeholders only in code, docs and commits: no hostnames, account names or
+  home paths. A gitleaks hook enforces it.
+
+## Testing
+
+No test suite. `bash -n bin/<script>` (or `sh -n`) for syntax. For anything
+visual, open the menu in the session, screenshot and look:
+
+    grim -o DP-1 /tmp/shot.png
+
+`wtype -k Escape` closes it from a script.
+
+## Repo facts
+
+- License: GPLv2 only (`LICENSE`, header in each source file), except
+  `bin/rofipass` (derived from MIT-licensed upstream, notice kept in the file)
+  and `bin/udt-powermenu.sh`, `bin/udt-launcher.sh` (derived from adi1090x/rofi,
+  GPL-3.0 like upstream).
+- `origin` is the personal git server (cgit section "Linux").
+- Work directly on master.