feat: add gateway TUI

docs/tui.md

@@ -0,0 +1,54 @@
+---
+summary: "Terminal UI (TUI) for Clawdis via the Gateway"
+read_when:
+  - You want a terminal UI that connects to the Gateway from any machine
+  - You are debugging the TUI client or Gateway chat stream
+---
+# TUI (Gateway chat client)
+
+Updated: 2026-01-03
+
+## What it is
+- A terminal UI that connects to the Gateway WebSocket and speaks the same chat APIs as WebChat.
+- Works locally (loopback) or remotely (Tailscale/SSH tunnel) without running a separate agent process.
+
+## Run
+```bash
+clawdis tui
+```
+
+### Remote
+```bash
+clawdis tui --url ws://127.0.0.1:18789 --token <gateway-token>
+```
+Use SSH tunneling or Tailscale to reach the Gateway WS.
+
+## Options
+- `--url <url>`: Gateway WebSocket URL (defaults to config `gateway.remote.url` or `ws://127.0.0.1:18789`).
+- `--token <token>`: Gateway token (if required).
+- `--password <password>`: Gateway password (if required).
+- `--session <key>`: Session key (default: `session.mainKey` or `main`).
+- `--deliver`: Deliver assistant replies to the provider.
+- `--thinking <level>`: Override thinking level for sends.
+- `--timeout-ms <ms>`: Agent timeout in ms (default 30000).
+- `--history-limit <n>`: History entries to load (default 200).
+
+## Controls
+- Enter: send message
+- Esc: abort active run
+- Ctrl+C: exit
+
+## Slash commands
+- `/help`
+- `/session <key>`
+- `/abort`
+- `/exit`
+
+## Notes
+- The TUI shows Gateway chat deltas (`event: chat`) and final responses.
+- It registers as a Gateway client with `mode: "tui"` for presence and debugging.
+
+## Files
+- CLI: `src/cli/tui-cli.ts`
+- Runner: `src/tui/tui.ts`
+- Gateway client: `src/tui/gateway-chat.ts`