docs: document command parsing rules for users who use shell features in check/context commands

The cookbook had a context example using pipes and redirections
(2>&1 | tail -20) which silently fails because commands are run via
subprocess.run without shell=True. Fixed the example and added:
- Command parsing section in primitives reference
- Troubleshooting entry for the common gotcha
- Cross-links between all three pages

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

docs/cookbook.md

@@ -155,14 +155,17 @@ Do not modify tests unless they are incorrect.
 
 ```markdown
 ---
-command: uv run pytest --tb=line -q 2>&1 | tail -20
+command: uv run pytest --tb=line -q
 timeout: 60
 enabled: true
 ---
 ## Current test status
 ```
 
-This context gives the agent a snapshot of which tests are failing before it starts, so it can pick the most important one without running the full suite first.
+This context gives the agent a snapshot of which tests are failing before it starts, so it can pick the most important one without running the full suite first. Ralphify automatically truncates output to 5,000 characters, so you don't need to limit it yourself.
+
+!!! note "Need pipes or redirections?"
+    Commands are parsed with `shlex` and run directly — not through a shell. If you need pipes (`|`), redirections (`2>&1`), or other shell features, use a [`run.sh` script](primitives.md#using-a-script-instead-of-a-command) instead.
 
 ### Setup commands
 

docs/primitives.md

@@ -47,10 +47,20 @@ The body text below the frontmatter is the **failure instruction** — it gets i
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `command` | string | — | Shell command to run |
+| `command` | string | — | Command to run (see [command parsing](#command-parsing) below) |
 | `timeout` | int | `60` | Max seconds before the check is killed |
 | `enabled` | bool | `true` | Set to `false` to skip without deleting |
 
+### Command parsing
+
+Commands are split with Python's `shlex.split()` and executed **directly** — not through a shell. This means:
+
+- Simple commands work as expected: `uv run pytest -x`, `npm test`, `ruff check .`
+- Shell features like **pipes** (`|`), **redirections** (`2>&1`, `>`), **chaining** (`&&`, `||`), and **variable expansion** (`$VAR`) do **not** work
+- Arguments with spaces need quoting: `pytest "tests/my dir/"` works correctly
+
+If you need shell features, use a [script](#using-a-script-instead-of-a-command) instead.
+
 ### Using a script instead of a command
 
 Instead of a `command` in frontmatter, you can place an executable script named `run.*` (e.g. `run.sh`, `run.py`) in the check directory:
@@ -142,7 +152,7 @@ A context can also be purely static (no command) — just omit the `command` fie
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `command` | string | — | Shell command whose stdout is captured |
+| `command` | string | — | Command whose stdout is captured (see [command parsing](#command-parsing)) |
 | `timeout` | int | `30` | Max seconds before the command is killed |
 | `enabled` | bool | `true` | Set to `false` to skip without deleting |
 

docs/troubleshooting.md

@@ -108,6 +108,30 @@ This is different from `PROMPT.md`, which **is** re-read every iteration. See [W
 
 ## Check issues
 
+### Command with pipes or redirections not working
+
+Commands in frontmatter are parsed with `shlex` and run **directly** — not through a shell. Shell features like pipes (`|`), redirections (`2>&1`), chaining (`&&`), and variable expansion (`$VAR`) silently fail or produce unexpected results.
+
+**Won't work:**
+
+```yaml
+command: pytest --tb=line -q 2>&1 | tail -20
+```
+
+**Fix:** Use a `run.sh` script instead:
+
+```bash
+#!/bin/bash
+# .ralph/checks/my-check/run.sh
+pytest --tb=line -q 2>&1 | tail -20
+```
+
+```bash
+chmod +x .ralph/checks/my-check/run.sh
+```
+
+See [command parsing](primitives.md#command-parsing) for details.
+
 ### Checks always failing
 
 Run the check command manually to see if it works: