From 11ab6915777427ec4ffde0d5e77873219fe0766a Mon Sep 17 00:00:00 2001
From: Chris Wanstrath <chris@ozmm.org>
Date: Tue, 10 Mar 2026 16:41:50 -0700
Subject: [PATCH] Add directives section to README

---
 README.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/README.md b/README.md
index 93dc3d3..1a2b39b 100644
--- a/README.md
+++ b/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...]