From 590dbb5b4a8d90b3641a407d7df6c6f29d4309f8 Mon Sep 17 00:00:00 2001
From: lkn <lkn@lneely.de>
Date: Tue, 21 Jul 2026 14:04:24 +0200
Subject: [PATCH] prompts: rewrite 9P operational model with complete file tree
 and request-response examples

---
 prompts/session_9p.md | 51 ++++++++++++++++++++++---------------------
 1 file changed, 26 insertions(+), 25 deletions(-)

diff --git a/prompts/session_9p.md b/prompts/session_9p.md
index bd1d1a4..73e37a9 100644
--- a/prompts/session_9p.md
+++ b/prompts/session_9p.md
@@ -2,42 +2,43 @@
 
 Your world model is a 9P filesystem mounted at ${OLLIE}. Your session ID is `${OLLIE_SESSION_ID}`.
 
-## Root Namespace
+## Root Namespace (`${OLLIE}/`)
 
-| Path | Mode | Contents |
+| File | Mode | Purpose |
 |---|---|---|
-| `${OLLIE}/agents`    | read   | Available agent names, one per line |
-| `${OLLIE}/backends`  | read   | Available backend names, one per line |
-| `${OLLIE}/models`    | read   | Available models (backend\tmodel per line) |
-| `${OLLIE}/help`      | read   | Help text |
-| `${OLLIE}/ctl`       | write  | Server control (e.g. `invalidate`) |
-| `${OLLIE}/s/`        | dir    | Sessions |
-| `${OLLIE}/complete`  | r/w    | Code completion (dns-style, see below) |
-| `${OLLIE}/generate`  | r/w    | One-shot generation (dns-style) |
-| `${OLLIE}/route`     | r/w    | Task routing/classification (dns-style) |
-| `${OLLIE}/tools`     | r/w    | Tool prompt lookup (dns-style) |
+| `agents`    | read   | Available agent names, one per line |
+| `backends`  | read   | Available backend names, one per line |
+| `models`    | read   | Available models (backend\tmodel per line) |
+| `help`      | read   | Help text |
+| `ctl`       | write  | Server control commands (e.g. `invalidate` to refresh model cache) |
+| `s/`        | dir    | Sessions (see below) |
+| `complete`  | r/w    | Write: JSON `{"file","prefix","suffix"}`. Read: code completion result. |
+| `generate`  | r/w    | Write: JSON `{"prompt"}` or plain text. Read: one-shot LLM generation result. |
+| `route`     | r/w    | Write: task description. Read: `backend=X model=Y` recommendation. |
+| `tools`     | r/w    | Write: tool name. Read: tool's full prompt/documentation. |
 
-## DNS-Style Endpoints
-
-`complete`, `generate`, `route`, and `tools` use the Plan 9 `/net/dns` pattern: open the file r/w, write a request, then read the response from the same fd. Each open fd maintains independent state.
+`complete`, `generate`, `route`, and `tools` are request-response files. Open one r/w, write a query, then read the response from the same fd:
 
 ```bash
-# Look up a tool's prompt
-echo 'file_edit' | 9p rdwr ollie/tools
-
-# Or with shell fd:
+# Get a tool's documentation
 exec 3<>$OLLIE/tools; echo 'file_edit' >&3; cat <&3; exec 3>&-
+# → returns file_edit's usage, args, and examples
 
-# Route a task
-echo 'implement login page' | 9p rdwr ollie/route
+# Pick a backend+model for a task
+exec 3<>$OLLIE/route; echo 'implement login page' >&3; cat <&3; exec 3>&-
+# → returns "backend=anthropic model=claude-sonnet-4-20250514"
 
-# One-shot generation
-echo '{"prompt":"summarize this"}' | 9p rdwr ollie/generate
+# Generate text (one-shot, no session)
+exec 3<>$OLLIE/generate; echo '{"prompt":"summarize X"}' >&3; cat <&3; exec 3>&-
+# → returns the generated text
 
-# Code completion
-echo '{"file":"main.go","prefix":"func main"}' | 9p rdwr ollie/complete
+# Get a code completion
+exec 3<>$OLLIE/complete; echo '{"file":"main.go","prefix":"func "}' >&3; cat <&3; exec 3>&-
+# → returns completion candidates
 ```
 
+Shorthand: `echo 'file_edit' | 9p rdwr ollie/tools`
+
 ## Peer Agent Discovery
 
 Sessions sharing your `cwd` are your peer agents. Read `${OLLIE}/s/idx` to discover other sessions available for cooperation: