docs: document environment variables in README

README.md

@@ -89,6 +89,28 @@ Options:
   -h, --help       display help for command
 ```
 
+## Environment Variables
+
+### Set automatically
+
+| Variable | Value |
+|---|---|
+| `HOME` | Path to the temp directory created for the test |
+| `SHOUT_DIR` | Same as `HOME` — the temp directory for the test |
+| `PORT` | Auto-assigned when `--port-from <n>` is used (increments per file). Not set if `PORT` is already defined via `@env` or `@setup`. |
+
+### Inherited
+
+By default, the test shell inherits all environment variables from the parent process. Use `--clean-env` to start with an empty environment instead.
+
+### Modified
+
+`PATH` is prepended with any directories passed via `--path <path>`.
+
+### User-defined
+
+Use `@env KEY=VALUE` directives to set arbitrary variables. See [Directives](#directives).
+
 Print an example `.shout` file:
 
 ```