Docs: Explain contract capability gates

bin/panama

@@ -10,7 +10,7 @@
 #   edit       Open the Panama repo in Neovim
 #   doctor     Report what is actually running on this machine
 #   diagnose   Hand this machine's health and recent errors to your agent
-#   test       Run contract manifest entries under tests/ (--safe is hermetic only)
+#   test       Run contracts classified by tests/contracts.manifest
 #   contracts  Name the contracts that mention a given file
 #   upgrade    Re-run the installer from anywhere, interview included
 #   migrate    Apply repairs this machine has not had yet
@@ -85,10 +85,12 @@ ${BOLD}Commands:${RESET}
   ${GREEN}diagnose${RESET}    Hand the health summary, the recent journal errors and
               whatever you say is wrong to your coding agent, in a terminal.
               Needs an agent chosen on Settings › System › Agents.
-  ${GREEN}test${RESET}        Run every contract under tests/. Give it a pattern to run
-              a subset: 'panama test dock' runs the ones matching 'dock'.
-              --safe runs hermetic contracts only. External capabilities need
-              explicit --allow grants when automation invokes them.
+  ${GREEN}test${RESET}        Run contracts classified by tests/contracts.manifest. Give it a
+              pattern to run a subset. --safe selects hermetic contracts only.
+              Plain terminal runs prompt before non-hermetic work. Automation
+              must grant each required capability with a repeatable --allow.
+              Failures print captured stdout/stderr; the default outer timeout
+              is 180 seconds.
   ${GREEN}contracts${RESET}   Name the contracts that mention a given file, each labeled
               with manifest capabilities. A heuristic over the text of tests/, so it
               answers "what should I run" rather than "what covers this".
@@ -121,6 +123,9 @@ ${BOLD}Examples:${RESET}
   $PROGRAM diagnose the bar disappears after unplugging the monitor
   $PROGRAM test dock
   $PROGRAM test --safe
+  $PROGRAM test --allow live-host updates
+  $PROGRAM test --allow live-compositor keybinds
+  PANAMA_TEST_TIMEOUT_SECONDS=300 $PROGRAM test --safe
   $PROGRAM contracts config/dot/quickshell/services/Displays.qml
   $PROGRAM upgrade
   $PROGRAM apps
@@ -474,20 +479,19 @@ is_contract_capability() {
 # Command: test
 # ----------------------------------------------------------------------------
 #
-# The contracts are the main safety net in this repository and had no entry
-# point: 121 executables with no runner and no mention in the README, which is
-# most of the way to not having them.
+# The contracts are the main safety net in this repository. The manifest is the
+# single list of what the runner executes and which external boundaries each
+# contract reaches.
 #
 # Each runs in its own process and a failure does not stop the rest, because the
 # useful output is the whole list of what is broken rather than the first thing
 # that broke. The exit code is what a caller can act on.
 #
-# --safe exists because a fair number of these contracts ARE the desktop: they
-# open overlays, restart the shell, move your windows. Running the suite while
-# sitting in front of the machine used to mean losing the session for a few
-# minutes, so the honest options were "run everything" or "run nothing". --safe
-# is the third: run only contracts the manifest classifies as hermetic, and say
-# which external capability coverage it skipped.
+# --safe runs only contracts the manifest classifies as hermetic and reports
+# each external capability it skipped. A plain terminal run asks before any
+# selected non-hermetic work. Automation must grant every required capability
+# with repeatable --allow flags. Each contract gets an outer timeout, 180
+# seconds by default, and failures include the captured stdout and stderr.
 cmd_test() {
   local timeout_seconds="${PANAMA_TEST_TIMEOUT_SECONDS:-180}"
   [[ "$timeout_seconds" =~ ^[1-9][0-9]*$ ]] || {
@@ -658,10 +662,8 @@ cmd_test_impl() (
 # Command: contracts
 # ----------------------------------------------------------------------------
 #
-# "I changed this file -- what should I run?" There are 177 contracts and no
-# index, so the honest answers were "all of them" (minutes, and half of them
-# take the desktop away) or "the ones whose name sounds related" (which is how
-# a covering contract gets skipped).
+# "I changed this file -- what should I run?" The suite is large enough that
+# running all of it or guessing from contract names are both poor answers.
 #
 # This is a grep, and says so. A contract that names the file, or a
 # parent-trimmed suffix of it, or just its basename, is a contract worth