docs: document script execution environment so users know what env vars and working directory their scripts get

The RALPH_NAME environment variable and script execution context (working
directory, env inheritance) were implemented in v0.1.8 but only mentioned
in the changelog. Users writing check/context scripts now have a reference
section in the primitives page explaining what environment their scripts
run in.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

docs/primitives.md

@@ -225,6 +225,32 @@ When you run `ralph run docs`:
 
 ## Behavior notes
 
+### Script execution environment
+
+When a check or context command (or `run.*` script) runs, ralphify sets up the following environment:
+
+**Working directory:** Always the **project root** (where `ralph.toml` lives), regardless of where the primitive directory is located.
+
+**Environment variables:** Scripts inherit the full parent process environment (`PATH`, `HOME`, etc.). When running a named ralph, ralphify also sets:
+
+| Variable | Value | When set |
+|---|---|---|
+| `RALPH_NAME` | Name of the current ralph (e.g. `docs`) | Only when running a named ralph via `ralph run docs` |
+
+This lets a single script adapt its behavior based on which ralph is running:
+
+```bash
+#!/bin/bash
+# .ralphify/checks/tests/run.sh
+if [ "$RALPH_NAME" = "docs" ]; then
+    uv run pytest tests/test_docs.py -x
+else
+    uv run pytest -x
+fi
+```
+
+`RALPH_NAME` is not set when running the root `RALPH.md` directly (i.e. `ralph run` without a named ralph).
+
 ### Execution order
 
 Primitives run in **alphabetical order by directory name**. To control order, use number prefixes: `01-lint/`, `02-typecheck/`, `03-tests/`. All checks run regardless of whether earlier checks pass or fail.