docs: reorganize documentation structure

2026-01-07 00:41:31 +01:00
parent b8db8502aa
commit db4d0b8e75
126 changed files with 881 additions and 270 deletions
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -0,0 +1,91 @@
+---
+summary: "Browser-based control UI for the Gateway (chat, nodes, config)"
+read_when:
+  - You want to operate the Gateway from a browser
+  - You want Tailnet access without SSH tunnels
+---
+# Control UI (browser)
+
+The Control UI is a small **Vite + Lit** single-page app served by the Gateway:
+
+- default: `http://<host>:18789/`
+- optional prefix: set `gateway.controlUi.basePath` (e.g. `/clawdbot`)
+
+It speaks **directly to the Gateway WebSocket** on the same port.
+
+## Quick open (local)
+
+If the Gateway is running on the same computer, open:
+
+- http://127.0.0.1:18789/ (or http://localhost:18789/)
+
+If the page fails to load, start the Gateway first: `clawdbot gateway`.
+
+Auth is supplied during the WebSocket handshake via:
+- `connect.params.auth.token`
+- `connect.params.auth.password`
+The dashboard settings panel lets you store a token; passwords are not persisted.
+
+## What it can do (today)
+- Chat with the model via Gateway WS (`chat.history`, `chat.send`, `chat.abort`)
+- Stream tool calls + live tool output cards in Chat (agent events)
+- Connections: WhatsApp/Telegram status + QR login + Telegram config (`providers.status`, `web.login.*`, `config.set`)
+- Instances: presence list + refresh (`system-presence`)
+- Sessions: list + per-session thinking/verbose overrides (`sessions.list`, `sessions.patch`)
+- Cron jobs: list/add/run/enable/disable + run history (`cron.*`)
+- Skills: status, enable/disable, install, API key updates (`skills.*`)
+- Nodes: list + caps (`node.list`)
+- Config: view/edit `~/.clawdbot/clawdbot.json` (`config.get`, `config.set`)
+- Config schema + form rendering (`config.schema`); Raw JSON editor remains available
+- Debug: status/health/models snapshots + event log + manual RPC calls (`status`, `health`, `models.list`)
+
+## Tailnet access (recommended)
+
+### Integrated Tailscale Serve (preferred)
+
+Keep the Gateway on loopback and let Tailscale Serve proxy it with HTTPS:
+
+```bash
+clawdbot gateway --tailscale serve
+```
+
+Open:
+- `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
+
+By default, the gateway trusts Tailscale identity headers in serve mode. You can still set
+`CLAWDBOT_GATEWAY_TOKEN` or `gateway.auth` if you want a shared secret instead.
+
+### Bind to tailnet + token (legacy)
+
+```bash
+clawdbot gateway --bind tailnet --token "$(openssl rand -hex 32)"
+```
+
+Then open:
+- `http://<tailscale-ip>:18789/` (or your configured `gateway.controlUi.basePath`)
+
+Paste the token into the UI settings (sent as `connect.params.auth.token`).
+
+## Building the UI
+
+The Gateway serves static files from `dist/control-ui`. Build them with:
+
+```bash
+bun run ui:install
+bun run ui:build
+```
+
+Optional absolute base (when you want fixed asset URLs):
+
+```bash
+CLAWDBOT_CONTROL_UI_BASE_PATH=/clawdbot/ bun run ui:build
+```
+
+For local development (separate dev server):
+
+```bash
+bun run ui:install
+bun run ui:dev
+```
+
+Then point the UI at your Gateway WS URL (e.g. `ws://127.0.0.1:18789`).
--- a/docs/web/dashboard.md
+++ b/docs/web/dashboard.md
@@ -0,0 +1,20 @@
+---
+summary: "Gateway dashboard (Control UI) access and auth"
+read_when:
+  - Changing dashboard authentication or exposure modes
+---
+# Dashboard (Control UI)
+
+The Gateway dashboard is the browser Control UI served at `/` by default
+(override with `gateway.controlUi.basePath`).
+
+Quick open (local Gateway):
+- http://127.0.0.1:18789/ (or http://localhost:18789/)
+
+Key references:
+- [`docs/control-ui.md`](https://docs.clawd.bot/web/control-ui) for usage and UI capabilities.
+- [`docs/tailscale.md`](https://docs.clawd.bot/gateway/tailscale) for Serve/Funnel automation.
+- [`docs/web.md`](https://docs.clawd.bot/web) for bind modes and security notes.
+
+Authentication is enforced at the WebSocket handshake via `connect.params.auth`
+(token or password). See `gateway.auth` in [`docs/configuration.md`](https://docs.clawd.bot/gateway/configuration).
--- a/docs/web/index.md
+++ b/docs/web/index.md
@@ -0,0 +1,106 @@
+---
+summary: "Gateway web surfaces: Control UI, bind modes, and security"
+read_when:
+  - You want to access the Gateway over Tailscale
+  - You want the browser Control UI and config editing
+---
+# Web (Gateway)
+
+The Gateway serves a small **browser Control UI** (Vite + Lit) from the same port as the Gateway WebSocket:
+
+- default: `http://<host>:18789/`
+- optional prefix: set `gateway.controlUi.basePath` (e.g. `/clawdbot`)
+
+Capabilities live in [`docs/control-ui.md`](https://docs.clawd.bot/web/control-ui).
+This page focuses on bind modes, security, and web-facing surfaces.
+
+## Webhooks
+
+When `hooks.enabled=true`, the Gateway also exposes a small webhook endpoint on the same HTTP server.
+See [`docs/configuration.md`](https://docs.clawd.bot/gateway/configuration) → `hooks` for auth + payloads.
+
+## Config (default-on)
+
+The Control UI is **enabled by default** when assets are present (`dist/control-ui`).
+You can control it via config:
+
+```json5
+{
+  gateway: {
+    controlUi: { enabled: true, basePath: "/clawdbot" } // basePath optional
+  }
+}
+```
+
+## Tailscale access
+
+### Integrated Serve (recommended)
+
+Keep the Gateway on loopback and let Tailscale Serve proxy it:
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "serve" }
+  }
+}
+```
+
+Then start the gateway:
+
+```bash
+clawdbot gateway
+```
+
+Open:
+- `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
+
+### Tailnet bind + token (legacy)
+
+```json5
+{
+  gateway: {
+    bind: "tailnet",
+    controlUi: { enabled: true }
+  }
+}
+```
+
+Then start the gateway (token required for non-loopback binds):
+
+```bash
+export CLAWDBOT_GATEWAY_TOKEN="…your token…"
+clawdbot gateway
+```
+
+Open:
+- `http://<tailscale-ip>:18789/` (or your configured `gateway.controlUi.basePath`)
+
+### Public internet (Funnel)
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "funnel" },
+    auth: { mode: "password" } // or CLAWDBOT_GATEWAY_PASSWORD
+  }
+}
+```
+
+## Security notes
+
+- Binding the Gateway to a non-loopback address **requires** auth (`CLAWDBOT_GATEWAY_TOKEN` or `gateway.auth`).
+- The UI sends `connect.params.auth.token` or `connect.params.auth.password`.
+- Use `gateway.auth.allowTailscale: false` to require explicit credentials even in Serve mode.
+- `gateway.tailscale.mode: "funnel"` requires `gateway.auth.mode: "password"` (shared password).
+
+## Building the UI
+
+The Gateway serves static files from `dist/control-ui`. Build them with:
+
+```bash
+bun run ui:install
+bun run ui:build
+```
--- a/docs/web/tui.md
+++ b/docs/web/tui.md
@@ -0,0 +1,71 @@
+---
+summary: "Terminal UI (TUI) for Clawdbot 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.
+- Uses Gateway agent events for tool cards while streaming responses.
+- Works locally (loopback) or remotely (Tailscale/SSH tunnel) without running a separate agent process.
+
+## Run
+```bash
+clawdbot tui
+```
+
+### Remote
+```bash
+clawdbot 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: `main`, or `global` when scope is global).
+- `--deliver`: Deliver assistant replies to the provider (default off).
+- `--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: clear input (press twice to exit)
+- Ctrl+D: exit
+- Ctrl+L: model picker
+- Ctrl+P: session picker
+- Ctrl+O: toggle tool output expansion
+- Ctrl+T: toggle thinking visibility
+
+## Slash commands
+- `/help`
+- `/status`
+- `/session <key>` (or `/sessions`)
+- `/model <provider/model>` (or `/model list`, `/models`)
+- `/think <off|minimal|low|medium|high>`
+- `/verbose <on|off>`
+- `/elevated <on|off>`
+- `/elev <on|off>`
+- `/activation <mention|always>`
+- `/deliver <on|off>`
+- `/new` or `/reset`
+- `/compact [instructions]`
+- `/abort`
+- `/settings`
+- `/exit`
+
+## Notes
+- The TUI shows Gateway chat deltas (`event: chat`) and agent tool events.
+- It registers as a Gateway client with `mode: "tui"` for presence and debugging.
+
+## Files
+- CLI: [`src/cli/tui-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/tui-cli.ts)
+- Runner: [`src/tui/tui.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/tui/tui.ts)
+- Gateway client: [`src/tui/gateway-chat.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/tui/gateway-chat.ts)
--- a/docs/web/webchat.md
+++ b/docs/web/webchat.md
@@ -0,0 +1,36 @@
+---
+summary: "Loopback WebChat static host and Gateway WS usage for chat UI"
+read_when:
+  - Debugging or configuring WebChat access
+---
+# WebChat (Gateway WebSocket UI)
+
+Updated: 2026-01-06
+
+Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket.
+
+## What it is
+- A native chat UI for the gateway (no embedded browser and no local static server).
+- Uses the same sessions and routing rules as other providers.
+- Deterministic routing: replies always go back to WebChat.
+
+## How it works (behavior)
+- The UI connects to the Gateway WebSocket and uses `chat.history` + `chat.send`.
+- History is always fetched from the gateway (no local file watching).
+- If the gateway is unreachable, WebChat is read-only.
+
+## Remote use
+- Remote mode tunnels the gateway WebSocket over SSH/Tailscale.
+- You do not need to run a separate WebChat server.
+
+## Configuration reference (WebChat)
+Full configuration: [Configuration](/configuration)
+
+Provider options:
+- No dedicated `webchat.*` block. WebChat uses the gateway endpoint + auth settings below.
+
+Related global options:
+- `gateway.port`, `gateway.bind`: WebSocket host/port.
+- `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`: WebSocket auth.
+- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: remote gateway target.
+- `session.*`: session storage and main key defaults.