Add directives section to README

README.md

@@ -44,6 +44,32 @@ $ shout test
 
 Each line in a `.shout` file is run sequentially, unless `--parallel` is passed.
 
+## Directives
+
+Directives go at the top of a `.shout` file, before any commands.
+
+### `@env`
+
+Set environment variables for the test:
+
+```
+@env GREETING=hello
+@env TARGET=world
+
+$ echo "$GREETING $TARGET"
+hello world
+```
+
+### `@setup`
+
+Prepend commands (and `@env` directives) from another `.shout` file:
+
+```
+@setup setup-shared.shout
+```
+
+Setup commands run first and their failures abort the test. Setup files cannot themselves contain `@setup` — no nesting. If both the setup file and the user file define the same `@env`, the user file wins.
+
 ```
 Usage: shout test [options] [files...]