diff --git a/doc/USAGE.md b/doc/USAGE.md
index 69eb34e..f4fc913 100644
--- a/doc/USAGE.md
+++ b/doc/USAGE.md
@@ -99,12 +99,22 @@ Valid spec keys: `name` (auto-generated if omitted), `cwd` (required), `agent`,
 
 ## AI pipelines
 
-`b/job` and `b/q` write to stdout, so they compose naturally with Unix pipes:
+`b/q` reads its prompt from args or stdin — not both. When args are present, stdin is
+ignored. This shapes how pipelines compose:
 
 ```sh
-echo "write a haiku about filesystems" | $OLLIE/b/q | wc -w
-cat error.log | $OLLIE/b/q "what is causing this?" | $OLLIE/b/q "suggest a fix"
-$OLLIE/b/q "list 5 blog post ideas" | grep -v "^$" | head -3 | $OLLIE/b/q "expand the best one"
+# prompt from stdin: works
+echo "write a haiku about filesystems" | $OLLIE/b/q
+
+# pipe b/q output through shell tools, then into another b/q via stdin
+$OLLIE/b/q "list 5 blog post ideas" | grep -v "^$" | head -3 | $OLLIE/b/q
+
+# capture output, build next prompt explicitly
+ideas=$($OLLIE/b/q "list 5 blog post ideas" | grep -v "^$" | head -3)
+$OLLIE/b/q "expand the best of these ideas: $ideas"
+
+# pipe file content as the prompt
+cat error.log | $OLLIE/b/q
 ```
 
 `u/optimize` is a worked example — it generates N candidate prompts in parallel via
@@ -114,11 +124,11 @@ $OLLIE/b/q "list 5 blog post ideas" | grep -v "^$" | head -3 | $OLLIE/b/q "expan
 $OLLIE/u/optimize -n 3 -cm qwen/qwen3-8b -jm anthropic/claude-opus-4-6 "explain recursion"
 ```
 
-Progress goes to stderr; the winning prompt goes to stdout, making it pipeable:
+Progress goes to stderr; capture the output to use in a subsequent call:
 
 ```sh
 prompt=$($OLLIE/u/optimize "translate this to Spanish" 2>/dev/null)
-cat document.txt | $OLLIE/b/q "$prompt"
+{ echo "$prompt"; cat document.txt; } | $OLLIE/b/q
 ```
 
 ## Alternative front-ends