# 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.
- **`-show drun` ignores `-kb-custom-*`**, so drun cannot be refiltered from
  a button and relaunched; only dmenu and script modes exit on them. That is
  why the launcher has no category tabs: typing a category filters instead.
- **A script mode's tab label is its `-modi` name**; `-display-<name>` is
  ignored for it, so the glyph goes in the name (`"󰉋  Folders:udt-folders"`).

## 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` (derived from adi1090x/rofi, GPL-3.0 like
  upstream).
- `origin` is the personal git server (cgit section "Linux").
- Work directly on master.