Docs: Explain contract capability gates

README.md

@@ -198,14 +198,25 @@ docs/           Settings reference, and the design specs behind the work
 
 ## Tests
 
-186 of them, under `tests/`. Run the lot, or a subset by pattern:
+186 of them, under `tests/`. `tests/contracts.manifest` classifies every
+contract by the capabilities it needs. Run the hermetic set, or grant a
+specific external capability when automation needs it:
 
 ```sh
-panama test           # everything
-panama test dock      # just the ones matching "dock"
+panama test --safe
+panama test --allow live-host updates
+panama test --allow live-compositor keybinds
+PANAMA_TEST_TIMEOUT_SECONDS=300 panama test --safe
 tests/setup/interview-contract   # or one directly; they are plain executables
 ```
 
+`--safe` means hermetic contracts only. A plain full run prompts in a terminal
+before it starts any non-hermetic contract. Automation cannot answer that
+prompt, so it must grant every required capability with a repeatable `--allow`.
+Each contract has a 180-second outer timeout by default. Set
+`PANAMA_TEST_TIMEOUT_SECONDS` to a positive integer to override it. When a
+contract fails, the runner prints its captured stdout and stderr.
+
 They are called contracts rather than unit tests because that is what they are:
 each one pins a decision that was expensive to get right and is cheap to undo by
 accident. Most read or measure the real thing — launching a shell to measure a
@@ -243,8 +254,9 @@ panama sync       # review, commit and push your changes to this repo
 panama edit       # open it in Neovim
 panama doctor     # what is actually running, not what was installed
 panama diagnose   # hand the health summary and recent errors to your agent
-panama test       # every contract, or a subset by pattern
-panama test --safe        # the same, minus the ones that take over the desktop
+panama test       # every contract, prompting before non-hermetic work
+panama test --safe        # hermetic contracts only
+panama test --allow live-host updates  # grant one capability to automation
 panama contracts <file>   # which contracts mention a file, and can they be run
 panama migrate    # apply repairs this machine has not had yet
 panama upgrade    # re-run ./install from anywhere, interview and all