Let the password prompt say why

panama-sudo is pkexec with a stated reason: the reason travels to the
shell over the existing polkit IPC target, and the prompt renders it
labeled "Stated reason (unverified)" beside polkitd's real action
message -- beside, never instead of, because any process can claim any
reason and the action text is the trust anchor. Reasons are single-shot
and expire in ten seconds, so a stale one cannot dress up an unrelated
prompt; without a reason, a running shell, or qs the wrapper is exactly
pkexec. Built for agents, so the person typing their password learns
what for. Verified live end to end -- reason shown, consumed once,
expired when stale, cleared on dismissal -- and pinned by the polkit
reason contract.

README.md

@@ -113,7 +113,7 @@ docs/           Settings reference, and the design specs behind the work
 
 ## Tests
 
-132 of them, under `tests/`. Run the lot, or a subset by pattern:
+133 of them, under `tests/`. Run the lot, or a subset by pattern:
 
 ```sh
 panama test           # everything
@@ -171,6 +171,12 @@ package, a `flatpak:` line is a Flathub id, `| Name` gives the menu something
 readable, and an indented line belongs to the entry above it — which is how OBS
 carries its sixteen plugin extensions as one thing to tick.
 
+`panama-sudo` is pkexec with a stated reason: `panama-sudo --reason "why" --
+command` shows the reason on Panama's password prompt, clearly labeled as an
+unverified claim beside polkitd's own action text — meant for agents and
+scripts, so the person typing the password learns why before they do. Without
+a reason, a running shell, or `qs` it behaves exactly like pkexec.
+
 `panama app` is deliberately not part of `./install`. Everything else Panama
 installs comes from dnf or Flathub; these are built from source because no
 packaged form exists, and a source build is slow, wants the network throughout,