agent-root: install as file external (desktop roles), document

.chezmoiexternals/agent-root.toml

@@ -0,0 +1,8 @@
+# agent-root: lets coding agents run one command as root through a pkexec
+# dialog with a notify-send reason. Single upstream script; desktop/laptop
+# roles only (needs the session's polkit agent), gated in .chezmoiignore.tmpl.
+[".local/bin/agent-root"]
+    type = "file"
+    url = "https://raw.githubusercontent.com/jankeesvw/agent-root/main/agent-root"
+    executable = true
+    refreshPeriod = "168h"

.chezmoiignore.tmpl

@@ -43,6 +43,7 @@ dist
 .config/uwsm/**
 .config/noctalia
 .config/noctalia/**
+.local/bin/agent-root
 .config/vicinae
 .config/vicinae/**
 .config/niri-dynamic-workspaces

AGENTS.md

@@ -42,6 +42,7 @@ Fresh clone: `git submodule update --init`.
 | `~/.config/omarchy` | prdlk/omarchy | `.chezmoiexternals/omarchy.toml` (git themes/plugins live in its `extras.txt`, not this repo) |
 | `~/.config/noctalia` | prdlk/noctalia | `.chezmoiexternals/noctalia.toml` (desktop/laptop roles only; `plugins/` gitignored, holds tokens) |
 | `~/.omp` | prdlk/omp | `.chezmoiexternals/omp.toml` |
+| `~/.local/bin/agent-root` | jankeesvw/agent-root (one `file` external, not a checkout; no edits, upstream script) | `.chezmoiexternals/agent-root.toml` (desktop/laptop roles only) |
 | `~/.config/nvim` | prdlk/nvim | `.chezmoiexternal.toml` (no refresh; local checkout wins) |
 | `~/.config/tmux/plugins/tpm` | tmux-plugins/tpm | `.chezmoiexternal.toml` |
 | `~/.config/bat/syntaxes/sublime-purescript-syntax` | tellnobody1/… | `.chezmoiexternal.toml` |

docs/chezmoi/externals-and-ignore.mdx

@@ -41,7 +41,7 @@ To update explicitly, run `chezmoi apply --refresh-externals` (`-R`), which pull
 
 ## .chezmoiexternals/ [#app-externals]
 
-Per-app config repos, one file each in `.chezmoiexternals/<app>.toml`. Each is a `git-repo` external with `refreshPeriod = "168h"` and `pull.args = ["--ff-only"]`, so `chezmoi apply` fast-forwards them at most once a week. The repos hold plain config files (no chezmoi prefixes) and are not part of `chezmoi managed` contents.
+Per-app config repos, one file each in `.chezmoiexternals/<app>.toml`. Each is a `git-repo` external with `refreshPeriod = "168h"` and `pull.args = ["--ff-only"]`, so `chezmoi apply` fast-forwards them at most once a week. The repos hold plain config files (no chezmoi prefixes) and are not part of `chezmoi managed` contents. The exception is [`agent-root.toml`](#agent-root), a single downloaded script.
 
 ```toml .chezmoiexternals/tmux.toml
 [".config/tmux"]
@@ -65,6 +65,18 @@ Per-app config repos, one file each in `.chezmoiexternals/<app>.toml`. Each is a
 
 Edit these in place under `~/.config/<app>`, then commit and push from that checkout.
 
+### agent-root [#agent-root]
+
+`agent-root.toml` is the one `file` external: chezmoi downloads [jankeesvw/agent-root](https://github.com/jankeesvw/agent-root)'s single bash script to `~/.local/bin/agent-root` (mode `0755`) and re-fetches it at most once a week (`refreshPeriod = "168h"`). Coding agents run `agent-root "<why>" <command>` instead of `sudo`; it wraps `pkexec` (`polkit`) so the session's polkit agent (Noctalia, or polkit-gnome under niri) shows the command, and `notify-send` (`libnotify`) shows the reason. Exit 126 means the dialog was dismissed. The usage rules agents follow live in the global omp instructions, `~/.omp/agent/AGENTS.md` ([prdlk/omp](https://github.com/prdlk/omp)). Linux desktop/laptop roles only ([role gate](#chezmoiignore)), since there is no polkit agent elsewhere.
+
+```toml .chezmoiexternals/agent-root.toml
+[".local/bin/agent-root"]
+    type = "file"
+    url = "https://raw.githubusercontent.com/jankeesvw/agent-root/main/agent-root"
+    executable = true
+    refreshPeriod = "168h"
+```
+
 ## Submodules [#submodules]
 
 Three source directories are git submodules, listed in `.gitmodules`. They keep chezmoi source naming and are applied in symlink mode like the rest of the tree. `chezmoi init` clones them.
@@ -137,6 +149,7 @@ mise tool versions stay local to each machine and are not managed.
 .config/uwsm/**
 .config/noctalia
 .config/noctalia/**
+.local/bin/agent-root
 .config/vicinae
 .config/vicinae/**
 .config/niri-dynamic-workspaces