diff --git a/CLAUDE.md b/CLAUDE.md
index d5c14a9..53e0b9c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,7 +6,15 @@ Transcript-based shell integration test runner. Bun + TypeScript.
 
 - `bun test` — run unit tests
 - `bunx tsc --noEmit` — type check
-- `bun run src/cli/index.ts [files...]` — run shout CLI (`--port-from <n>` auto-assigns `$PORT`)
+- `bun run src/cli/index.ts test [files...]` — run shout CLI
+  - `-u, --update` — rewrite `.shout` files with actual output
+  - `-k, --keep` — keep temp directories after run
+  - `--clean-env` — start with empty environment
+  - `--path <path>` — prepend to `$PATH` (repeatable)
+  - `--timeout <dur>` — per-command timeout (default `10s`)
+  - `-v, --verbose` — print each command as it runs
+  - `--port-from <n>` — auto-assign `$PORT` starting from n
+  - `--parallel` — run files in parallel
 
 ## Architecture
 
@@ -18,6 +26,7 @@ Transcript-based shell integration test runner. Bun + TypeScript.
 - `src/duration.ts` — parses duration strings (`10s`, `500ms`, `1m`)
 - `src/cli/index.ts` — CLI entry point via `commander`
 - `src/index.ts` — barrel exports
+- `web/index.html` — web documentation page
 
 ## .shout file format
 
@@ -30,7 +39,12 @@ Transcript-based shell integration test runner. Bun + TypeScript.
 - `#` after a command = comment (stripped); `#` in expected output is literal
 - `@env KEY=VALUE` before first command = set environment variable
 - `@setup path.shout` before first command = prepend commands (and `@env`) from another file
+  - Setup files cannot themselves contain `@setup` (no nesting)
+  - User file `@env` overrides setup file `@env`
+  - Setup command failures abort the test with an error
 - Each file runs in a fresh temp dir with a single `/bin/sh` session
+- `$HOME` and `$SHOUT_DIR` are set to the temp dir automatically
+- stdout and stderr are merged (`exec 2>&1`)
 
 ## Style