From 4b630a76a8251cd2f3dd9b3b41aeb5966f3beffa Mon Sep 17 00:00:00 2001
From: Levi Neely <lkn@darkstar.example.net>
Date: Sat, 18 Apr 2026 11:43:01 +0200
Subject: [PATCH] doc: document optimize script and AI pipeline composition

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md         |  2 +-
 scripts/README.md | 31 +++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 64d4719..a7295d3 100644
--- a/README.md
+++ b/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
 
diff --git a/scripts/README.md b/scripts/README.md
index 70849d0..c392834 100644
--- a/scripts/README.md
+++ b/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.