doc: document optimize script and AI pipeline composition

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

README.md

@@ -13,7 +13,7 @@ What happens if agent primitives are exposed as an ordinary filesystem? How much
 - `tui/`:
 - `9p/`:
 - `el/`:
-- `scripts/`: shell scripts installed to `~/.config/ollie/scripts/` and exposed via `s/` (`sh`, `job`, `q`, `sched`, `ls`, `kill`)
+- `scripts/`: shell scripts installed to `~/.config/ollie/scripts/` and exposed via `s/` (`sh`, `job`, `q`, `sched`, `ls`, `kill`, `optimize`)
 
 ## Getting Started
 

scripts/README.md

@@ -96,3 +96,34 @@ oq -backend ollama -model qwen3:8b "Explain this function" < main.go
 ```
 
 With `-parallel N` and N > 1, results are separated by `=== {id} ===` headers.
+
+---
+
+## optimize
+
+Generates N candidate optimized prompts, judges them, and returns the best one to stdout. Debugging output (progress messages) goes to stderr.
+
+```
+optimize [flags] [prompt...]
+echo "prompt" | optimize [flags]
+```
+
+**Flags**
+
+| Flag | Description |
+|---|---|
+| `-n N` | Number of candidates to generate (default: 3) |
+| `-cb B` | Candidate generation backend |
+| `-cm M` | Candidate generation model |
+| `-jb B` | Judge backend |
+| `-jm M` | Judge model |
+
+**Examples**
+
+```sh
+optimize "Summarize this document"
+optimize -n 5 -cm qwen/qwen3-8b -jm anthropic/claude-opus-4.6 "Write a haiku"
+optimize "generate a hello world program. use c++." 2>/dev/null | s/q
+```
+
+Outputs to stdout, making it composable with other pipeline stages.