The machine now carries its own manual for AI hands

Claude-Session: https://claude.ai/code/session_01Ms2FbjQy31TVf3CEvQhGM8

skills/panama-sudo/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: panama-sudo
+description: Use whenever a command needs root on a Panama machine — any sudo, pkexec, or privileged system change. Panama routes privilege through a wrapper that shows the user your reason beside the password prompt.
+---
+
+# panama-sudo
+
+Never run bare `sudo` or `pkexec` on a Panama machine. Use:
+
+```sh
+panama-sudo --reason "why this needs root" -- command args…
+```
+
+`--reason` must be the first argument; the `--` separator is optional. The reason is displayed on
+the desktop's own polkit prompt **beside** — never instead of — polkitd's description of the
+action, because anything can claim any reason. That is the trust model, and it shapes how you
+write the reason: state what the command does, not an assurance that it is safe.
+
+- Good: `--reason "Install the fwupd package so firmware updates can be checked"`
+- Bad: `--reason "Safe maintenance task"`
+
+With no `--reason`, no running shell, or no `qs` on PATH, it degrades to plain `pkexec` — so it
+is always the right call, even in a TTY or a broken session.
+
+One reason per privileged action. Do not batch unrelated root commands behind a single vague
+reason; the user approves what the prompt says, and the prompt should say everything.
+
+House precedent: `bin/panama-migrate` documents the rule — root work goes through
+`panama-sudo --reason "..."`, never bare sudo — and every shipped migration follows it.