From 651864017cedb8a12d3872deb11d29d01d0a7548 Mon Sep 17 00:00:00 2001
From: Guillaume ARM <trapcodien@gmail.com>
Date: Tue, 9 Jun 2026 03:28:54 +0200
Subject: [PATCH] docs(opencode): document TUI control endpoints

---
 docs/opencode_api.md | 42 +++++++++++++++++++++++++++++++++---------
 1 file changed, 33 insertions(+), 9 deletions(-)

diff --git a/docs/opencode_api.md b/docs/opencode_api.md
index ea9ab0d..1581eb2 100644
--- a/docs/opencode_api.md
+++ b/docs/opencode_api.md
@@ -133,16 +133,40 @@ opencode attach http://127.0.0.1:4096
 opencode attach http://127.0.0.1:4096 --session ses_abc123
 ```
 
-To send messages to the session currently open in the TUI, set `opencc.session_id` in CC to the session ID shown in the TUI, then run `ai-helloworld`.
+To send messages to the session currently open in the TUI, set `opencc.session_id` in CC to the session ID shown in the TUI, then run `ai-helloworld`:
 
-## TUI control (bonus)
+```sh
+set opencc.session_id ses_abc123
+```
 
-When a TUI is attached, these endpoints drive it programmatically:
+## TUI control
 
-| Method | Path | Effect |
-|---|---|---|
-| `POST` | `/tui/append-prompt` | Append text to the input field |
-| `POST` | `/tui/submit-prompt` | Submit the current input |
-| `POST` | `/tui/show-toast` | Show a notification |
+When a TUI is attached, these endpoints drive that TUI programmatically. They operate on the attached TUI prompt/dialog state, not on a specific `/session/:id`.
 
-Body for append/submit: `{ "text": "..." }`.
+| Method | Path | Effect | Body |
+|---|---|---|---|
+| `POST` | `/tui/append-prompt` | Append text to the prompt | `{ "text": "..." }` |
+| `POST` | `/tui/submit-prompt` | Submit the current prompt | none |
+| `POST` | `/tui/clear-prompt` | Clear the prompt | none |
+| `POST` | `/tui/open-help` | Open the help dialog | none |
+| `POST` | `/tui/open-sessions` | Open the session selector | none |
+| `POST` | `/tui/open-themes` | Open the theme selector | none |
+| `POST` | `/tui/open-models` | Open the model selector | none |
+| `POST` | `/tui/execute-command` | Execute a TUI command | `{ "command": "prompt.submit" }` |
+| `POST` | `/tui/show-toast` | Show a notification | `{ "message": "...", "variant": "info" }` |
+| `GET` | `/tui/control/next` | Wait for the next TUI control request | none |
+| `POST` | `/tui/control/response` | Respond to a TUI control request | response body |
+
+`/tui/show-toast` also accepts optional `title` and `duration` fields. `variant` is one of `info`, `success`, `warning`, or `error`.
+
+Example: prefill and submit the attached TUI prompt:
+
+```bash
+curl -X POST http://127.0.0.1:4096/tui/append-prompt \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"reply with exactly: pong"}'
+
+curl -X POST http://127.0.0.1:4096/tui/submit-prompt
+```
+
+`POST /tui/publish` also exists as a lower-level endpoint for publishing TUI events such as `tui.prompt.append`, `tui.command.execute`, and `tui.toast.show`. Prefer the specific endpoints above unless you need that raw event surface.