agent: global AGENTS.md with agent-root root-access rules

agent/AGENTS.md

@@ -0,0 +1,15 @@
+# Global agent instructions
+
+## Root access
+
+When a command needs root, don't use `sudo` and don't ask me to run it. Run it with `agent-root "<why>" <command>` (`~/.local/bin/agent-root`, from [jankeesvw/agent-root](https://github.com/jankeesvw/agent-root)): I get a polkit dialog showing the command and a notification with your reason, and approve it there.
+
+- Keep the reason under 50 characters and make it understandable without reading the chat. Say in the chat that a dialog is coming.
+- It blocks until I answer: give the bash call a long `timeout` (e.g. 600). If the call is killed, agent-root exits 128+signal (143) and the dialog closes.
+- Run one program with its arguments, never `sh -c`, `bash script.sh`, `env`, `xargs`, or a script you wrote; I can't see what those do. agent-root refuses programs under user-writable paths (`$HOME`, `/tmp`); never set `AGENT_ROOT_ALLOW_USER_PATHS` to get around that.
+- Batch: ask for as much as one command can do, e.g. all packages in one `pacman -S` call, so I approve as few dialogs as possible.
+- pkexec starts in `/root` with a minimal environment: pass files as absolute paths; don't rely on my env vars.
+- No terminal for prompts: use non-interactive flags (`pacman --noconfirm`, `systemctl --no-ask-password`).
+- Exit codes: the command's own on run; `126` = I declined — don't retry, ask me what to do; `127` = auth failed, no polkit agent, or command missing; `64` = agent-root refused (usage error or user-writable program).
+- AUR: `AGENT_ROOT_REASON="<why>" yay --sudo agent-root -S --noconfirm <package>` (same with `paru`). Set `AGENT_ROOT_REASON` only inline on that command, never export it, and never run yay/paru itself as root.
+- Only works inside my desktop session (needs the polkit agent). Over SSH, in a container, or with exit 127 "No authentication agent found", stop and give me the command to run instead.