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

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