clawdbot 2026.1.4

package/docs/templates/TOOLS.md

@@ -0,0 +1,41 @@
+---
+summary: "Workspace template for TOOLS.md"
+read_when:
+  - Bootstrapping a workspace manually
+---
+# TOOLS.md - Local Notes
+
+Skills define *how* tools work. This file is for *your* specifics — the stuff that's unique to your setup.
+
+## What Goes Here
+
+Things like:
+- Camera names and locations
+- SSH hosts and aliases  
+- Preferred voices for TTS
+- Speaker/room names
+- Device nicknames
+- Anything environment-specific
+
+## Examples
+
+```markdown
+### Cameras
+- living-room → Main area, 180° wide angle
+- front-door → Entrance, motion-triggered
+
+### SSH
+- home-server → 192.168.1.100, user: admin
+
+### TTS
+- Preferred voice: "Nova" (warm, slightly British)
+- Default speaker: Kitchen HomePod
+```
+
+## Why Separate?
+
+Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.
+
+---
+
+Add whatever helps you do your job. This is your cheat sheet.

package/docs/templates/USER.md

@@ -0,0 +1,22 @@
+---
+summary: "User profile record"
+read_when:
+  - Bootstrapping a workspace manually
+---
+# USER.md - About Your Human
+
+*Learn about the person you're helping. Update this as you go.*
+
+- **Name:** 
+- **What to call them:** 
+- **Pronouns:** *(optional)*
+- **Timezone:** 
+- **Notes:** 
+
+## Context
+
+*(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)*
+
+---
+
+The more you know, the better you can help. But remember — you're learning about a person, not building a dossier. Respect the difference.

package/docs/test.md

@@ -0,0 +1,35 @@
+---
+summary: "How to run tests locally (vitest) and when to use force/coverage modes"
+read_when:
+  - Running or fixing tests
+---
+# Tests
+
+- `pnpm test:force`: Kills any lingering gateway process holding the default control port, then runs the full Vitest suite with an isolated gateway port so server tests don’t collide with a running instance. Use this when a prior gateway run left port 18789 occupied.
+- `pnpm test:coverage`: Runs Vitest with V8 coverage. Global thresholds are 70% lines/branches/functions/statements. Coverage excludes integration-heavy entrypoints (CLI wiring, gateway/telegram bridges, webchat static server) to keep the target focused on unit-testable logic.
+- `pnpm test:e2e`: Runs gateway end-to-end smoke tests (multi-instance WS/HTTP/node pairing).
+
+## Model latency bench (local keys)
+
+Script: `scripts/bench-model.ts`
+
+Usage:
+- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
+- Optional env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
+- Default prompt: “Reply with a single word: ok. No punctuation or extra text.”
+
+Last run (2025-12-31, 20 runs):
+- minimax median 1279ms (min 1114, max 2431)
+- opus median 2454ms (min 1224, max 3170)
+
+## Onboarding E2E (Docker)
+
+Docker is optional; this is only needed for containerized onboarding smoke tests.
+
+Full cold-start flow in a clean Linux container:
+
+```bash
+scripts/e2e/onboard-docker.sh
+```
+
+This script drives the interactive wizard via a pseudo-tty, verifies config/workspace/session files, then starts the gateway and runs `clawdbot health`.

package/docs/thinking.md

@@ -0,0 +1,46 @@
+---
+summary: "Directive syntax for /think + /verbose and how they affect model reasoning"
+read_when:
+  - Adjusting thinking or verbose directive parsing or defaults
+---
+# Thinking Levels (/think directives)
+
+## What it does
+- Inline directive in any inbound body: `/t <level>`, `/think:<level>`, or `/thinking <level>`.
+- Levels (aliases): `off | minimal | low | medium | high`
+  - minimal → “think”
+  - low → “think hard”
+  - medium → “think harder”
+  - high → “ultrathink” (max budget)
+  - `highest`, `max` map to `high`.
+
+## Resolution order
+1. Inline directive on the message (applies only to that message).
+2. Session override (set by sending a directive-only message).
+3. Global default (`agent.thinkingDefault` in config).
+4. Fallback: low for reasoning-capable models; off otherwise.
+
+## Setting a session default
+- Send a message that is **only** the directive (whitespace allowed), e.g. `/think:medium` or `/t high`.
+- That sticks for the current session (per-sender by default); cleared by `/think:off` or session idle reset.
+- Confirmation reply is sent (`Thinking level set to high.` / `Thinking disabled.`). If the level is invalid (e.g. `/thinking big`), the command is rejected with a hint and the session state is left unchanged.
+
+## Application by agent
+- **Embedded Pi**: the resolved level is passed to the in-process Pi agent runtime.
+
+## Verbose directives (/verbose or /v)
+- Levels: `on|full` or `off` (default).
+- Directive-only message toggles session verbose and replies `Verbose logging enabled.` / `Verbose logging disabled.`; invalid levels return a hint without changing state.
+- Inline directive affects only that message; session/global defaults apply otherwise.
+- When verbose is on, agents that emit structured tool results (Pi, other JSON agents) send each tool result back as its own metadata-only message, prefixed with `<emoji> <tool-name>: <arg>` when available (path/command); the tool output itself is not forwarded. These tool summaries are sent as soon as each tool finishes (separate bubbles), not as streaming deltas. If you toggle `/verbose on|off` while a run is in-flight, subsequent tool bubbles honor the new setting.
+
+## Related
+- Elevated mode docs live in `docs/elevated.md`.
+
+## Heartbeats
+- Heartbeat probe body is `HEARTBEAT`. Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).
+
+## Web chat UI
+- The web chat thinking selector mirrors the session's stored level from the inbound session store/config when the page loads.
+- Picking another level applies only to the next message (`thinkingOnce`); after sending, the selector snaps back to the stored session level.
+- To change the session default, send a `/think:<level>` directive (as before); the selector will reflect it after the next reload.

package/docs/tools.md

@@ -0,0 +1,248 @@
+---
+summary: "Agent tool surface for Clawdbot (browser, canvas, nodes, cron) replacing clawdbot-* skills"
+read_when:
+  - Adding or modifying agent tools
+  - Retiring or changing clawdbot-* skills
+---
+
+# Tools (Clawdbot)
+
+Clawdbot exposes **first-class agent tools** for browser, canvas, nodes, and cron.
+These replace the old `clawdbot-*` skills: the tools are typed, no shelling,
+and the agent should rely on them directly.
+
+## Tool inventory
+
+### `bash`
+Run shell commands in the workspace.
+
+Core parameters:
+- `command` (required)
+- `yieldMs` (auto-background after timeout, default 10000)
+- `background` (immediate background)
+- `timeout` (seconds; kills the process if exceeded, default 1800)
+- `elevated` (bool; run on host if elevated mode is enabled/allowed)
+- Need a real TTY? Use the tmux skill.
+
+Notes:
+- Returns `status: "running"` with a `sessionId` when backgrounded.
+- Use `process` to poll/log/write/kill/clear background sessions.
+
+### `process`
+Manage background bash sessions.
+
+Core actions:
+- `list`, `poll`, `log`, `write`, `kill`, `clear`, `remove`
+
+Notes:
+- `poll` returns new output and exit status when complete.
+- `log` supports line-based `offset`/`limit` (omit `offset` to grab the last N lines).
+
+### `browser`
+Control the dedicated clawd browser.
+
+Core actions:
+- `status`, `start`, `stop`, `tabs`, `open`, `focus`, `close`
+- `snapshot` (aria/ai)
+- `screenshot` (returns image block + `MEDIA:<path>`)
+- `act` (UI actions: click/type/press/hover/drag/select/fill/resize/wait/evaluate)
+- `navigate`, `console`, `pdf`, `upload`, `dialog`
+
+Profile management:
+- `profiles` — list all browser profiles with status
+- `create-profile` — create new profile with auto-allocated port (or `cdpUrl`)
+- `delete-profile` — stop browser, delete user data, remove from config (local only)
+- `reset-profile` — kill orphan process on profile's port (local only)
+
+Common parameters:
+- `controlUrl` (defaults from config)
+- `profile` (optional; defaults to `browser.defaultProfile`)
+Notes:
+- Requires `browser.enabled=true` in `~/.clawdbot/clawdbot.json`.
+- Uses `browser.controlUrl` unless `controlUrl` is passed explicitly.
+- All actions accept optional `profile` parameter for multi-instance support.
+- When `profile` is omitted, uses `browser.defaultProfile` (defaults to "clawd").
+- Profile names: lowercase alphanumeric + hyphens only (max 64 chars).
+- Port range: 18800-18899 (~100 profiles max).
+- Remote profiles are attach-only (no start/stop/reset).
+- `snapshot` defaults to `ai`; use `aria` for the accessibility tree.
+- `act` requires `ref` from `snapshot --format ai`; use `evaluate` for rare CSS selector needs.
+- Avoid `act` → `wait` by default; use it only in exceptional cases (no reliable UI state to wait on).
+- `upload` can optionally pass a `ref` to auto-click after arming.
+- `upload` also supports `inputRef` (aria ref) or `element` (CSS selector) to set `<input type="file">` directly.
+
+### `canvas`
+Drive the node Canvas (present, eval, snapshot, A2UI).
+
+Core actions:
+- `present`, `hide`, `navigate`, `eval`
+- `snapshot` (returns image block + `MEDIA:<path>`)
+- `a2ui_push`, `a2ui_reset`
+
+Notes:
+- Uses gateway `node.invoke` under the hood.
+- If no `node` is provided, the tool picks a default (single connected node or local mac node).
+- A2UI is v0.8 only (no `createSurface`); the CLI rejects v0.9 JSONL with line errors.
+- Quick smoke: `clawdbot canvas a2ui push --text "Hello from A2UI"`.
+
+### `nodes`
+Discover and target paired nodes; send notifications; capture camera/screen.
+
+Core actions:
+- `status`, `describe`
+- `pending`, `approve`, `reject` (pairing)
+- `notify` (macOS `system.notify`)
+- `camera_snap`, `camera_clip`, `screen_record`
+- `location_get`
+
+Notes:
+- Camera/screen commands require the node app to be foregrounded.
+- Images return image blocks + `MEDIA:<path>`.
+- Videos return `FILE:<path>` (mp4).
+- Location returns a JSON payload (lat/lon/accuracy/timestamp).
+
+### `image`
+Analyze an image with the configured image model.
+
+Core parameters:
+- `image` (required path or URL)
+- `prompt` (optional; defaults to "Describe the image.")
+- `model` (optional override)
+- `maxBytesMb` (optional size cap)
+
+Notes:
+- Only available when `agent.imageModel` or `agent.imageModelFallbacks` is set.
+- Uses the image model directly (independent of the main chat model).
+
+### `cron`
+Manage Gateway cron jobs and wakeups.
+
+Core actions:
+- `status`, `list`
+- `add`, `update`, `remove`, `run`, `runs`
+- `wake` (enqueue system event + optional immediate heartbeat)
+
+Notes:
+- `add` expects a full cron job object (same schema as `cron.add` RPC).
+- `update` uses `{ jobId, patch }`.
+
+### `gateway`
+Restart the running Gateway process (in-place).
+
+Core actions:
+- `restart` (sends `SIGUSR1` to the current process; `clawdbot gateway`/`gateway-daemon` restart in-place)
+
+Notes:
+- Use `delayMs` (defaults to 2000) to avoid interrupting an in-flight reply.
+
+### `sessions_list` / `sessions_history` / `sessions_send`
+List sessions, inspect transcript history, or send to another session.
+
+Core parameters:
+- `sessions_list`: `kinds?`, `limit?`, `activeMinutes?`, `messageLimit?` (0 = none)
+- `sessions_history`: `sessionKey`, `limit?`, `includeTools?`
+- `sessions_send`: `sessionKey`, `message`, `timeoutSeconds?` (0 = fire-and-forget)
+
+Notes:
+- `main` is the canonical direct-chat key; global/unknown are hidden.
+- `messageLimit > 0` fetches last N messages per session (tool messages filtered).
+- `sessions_send` waits for final completion when `timeoutSeconds > 0`.
+- `sessions_send` runs a reply‑back ping‑pong (reply `REPLY_SKIP` to stop; max turns via `session.agentToAgent.maxPingPongTurns`, 0–5).
+- After the ping‑pong, the target agent runs an **announce step**; reply `ANNOUNCE_SKIP` to suppress the announcement.
+
+### `discord`
+Send Discord reactions, stickers, or polls.
+
+Core actions:
+- `react` (`channelId`, `messageId`, `emoji`)
+- `reactions` (`channelId`, `messageId`, optional `limit`)
+- `sticker` (`to`, `stickerIds`, optional `content`)
+- `poll` (`to`, `question`, `answers`, optional `allowMultiselect`, `durationHours`, `content`)
+- `permissions` (`channelId`)
+- `readMessages` (`channelId`, optional `limit`/`before`/`after`/`around`)
+- `sendMessage` (`to`, `content`, optional `mediaUrl`, `replyTo`)
+- `editMessage` (`channelId`, `messageId`, `content`)
+- `deleteMessage` (`channelId`, `messageId`)
+- `threadCreate` (`channelId`, `name`, optional `messageId`, `autoArchiveMinutes`)
+- `threadList` (`guildId`, optional `channelId`, `includeArchived`, `before`, `limit`)
+- `threadReply` (`channelId`, `content`, optional `mediaUrl`, `replyTo`)
+- `pinMessage`/`unpinMessage` (`channelId`, `messageId`)
+- `listPins` (`channelId`)
+- `searchMessages` (`guildId`, `content`, optional `channelId`/`channelIds`, `authorId`/`authorIds`, `limit`)
+- `memberInfo` (`guildId`, `userId`)
+- `roleInfo` (`guildId`)
+- `emojiList` (`guildId`)
+- `roleAdd`/`roleRemove` (`guildId`, `userId`, `roleId`)
+- `channelInfo` (`channelId`)
+- `channelList` (`guildId`)
+- `voiceStatus` (`guildId`, `userId`)
+- `eventList` (`guildId`)
+- `eventCreate` (`guildId`, `name`, `startTime`, optional `endTime`, `description`, `channelId`, `entityType`, `location`)
+- `timeout` (`guildId`, `userId`, optional `durationMinutes`, `until`, `reason`)
+- `kick` (`guildId`, `userId`, optional `reason`)
+- `ban` (`guildId`, `userId`, optional `reason`, `deleteMessageDays`)
+
+Notes:
+- `to` accepts `channel:<id>` or `user:<id>`.
+- Polls require 2–10 answers and default to 24 hours.
+- `reactions` returns per-emoji user lists (limited to 100 per reaction).
+- `discord.actions.*` gates Discord tool actions; `roles` + `moderation` default to `false`.
+- `searchMessages` follows the Discord preview spec (limit max 25, channel/author filters accept arrays).
+- The tool is only exposed when the current surface is Discord.
+
+## Parameters (common)
+
+Gateway-backed tools (`canvas`, `nodes`, `cron`):
+- `gatewayUrl` (default `ws://127.0.0.1:18789`)
+- `gatewayToken` (if auth enabled)
+- `timeoutMs`
+
+Browser tool:
+- `controlUrl` (defaults from config)
+
+## Recommended agent flows
+
+Browser automation:
+1) `browser` → `status` / `start`
+2) `snapshot` (ai or aria)
+3) `act` (click/type/press)
+4) `screenshot` if you need visual confirmation
+
+Canvas render:
+1) `canvas` → `present`
+2) `a2ui_push` (optional)
+3) `snapshot`
+
+Node targeting:
+1) `nodes` → `status`
+2) `describe` on the chosen node
+3) `notify` / `camera_snap` / `screen_record`
+
+## Safety
+
+- Avoid `system.run` (not exposed as a tool).
+- Respect user consent for camera/screen capture.
+- Use `status/describe` to ensure permissions before invoking media commands.
+
+## How the model sees tools (pi-mono internals)
+
+Tools are exposed to the model in **two parallel channels**:
+
+1) **System prompt text**: a human-readable list + guidelines.
+2) **Provider tool schema**: the actual function/tool declarations sent to the model API.
+
+In pi-mono:
+- System prompt builder: `packages/coding-agent/src/core/system-prompt.ts`
+  - Builds the `Available tools:` list from `toolDescriptions`.
+  - Appends skills and project context.
+- Tool schemas passed to providers:
+  - OpenAI: `packages/ai/src/providers/openai-responses.ts` (`convertTools`)
+  - Anthropic: `packages/ai/src/providers/anthropic.ts` (`convertTools`)
+  - Gemini: `packages/ai/src/providers/google-shared.ts` (`convertTools`)
+- Tool execution loop:
+  - Agent loop: `packages/ai/src/agent/agent-loop.ts`
+  - Validates tool arguments and executes tools, then appends `toolResult` messages.
+
+In Clawdbot:
+- System prompt append: `src/agents/system-prompt.ts`
+- Tool list injected via `createClawdbotCodingTools()` in `src/agents/pi-tools.ts`

package/docs/troubleshooting.md

@@ -0,0 +1,227 @@
+---
+summary: "Quick troubleshooting guide for common Clawdbot failures"
+read_when:
+  - Investigating runtime issues or failures
+---
+# Troubleshooting 🔧
+
+When your CLAWDBOT misbehaves, here's how to fix it.
+
+## Common Issues
+
+### "Agent was aborted"
+
+The agent was interrupted mid-response.
+
+**Causes:**
+- User sent `stop`, `abort`, `esc`, or `exit`
+- Timeout exceeded
+- Process crashed
+
+**Fix:** Just send another message. The session continues.
+
+### Messages Not Triggering
+
+**Check 1:** Is the sender in `whatsapp.allowFrom`?
+```bash
+cat ~/.clawdbot/clawdbot.json | jq '.whatsapp.allowFrom'
+```
+
+**Check 2:** For group chats, is mention required?
+```bash
+# The message must match mentionPatterns or explicit mentions; defaults live in whatsapp.groups
+cat ~/.clawdbot/clawdbot.json | jq '.routing.groupChat, .whatsapp.groups'
+```
+
+**Check 3:** Check the logs
+```bash
+tail -f "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"
+```
+
+### Image + Mention Not Working
+
+Known issue: When you send an image with ONLY a mention (no other text), WhatsApp sometimes doesn't include the mention metadata.
+
+**Workaround:** Add some text with the mention:
+- ❌ `@clawd` + image
+- ✅ `@clawd check this` + image
+
+### Session Not Resuming
+
+**Check 1:** Is the session file there?
+```bash
+ls -la ~/.clawdbot/sessions/
+```
+
+**Check 2:** Is `idleMinutes` too short?
+```json
+{
+  "session": {
+    "idleMinutes": 10080  // 7 days
+  }
+}
+```
+
+**Check 3:** Did someone send `/new`, `/reset`, or a reset trigger?
+
+### Agent Timing Out
+
+Default timeout is 30 minutes. For long tasks:
+
+```json
+{
+  "reply": {
+    "timeoutSeconds": 3600  // 1 hour
+  }
+}
+```
+
+Or use the `process` tool to background long commands.
+
+### WhatsApp Disconnected
+
+```bash
+# Check local status (creds, sessions, queued events)
+clawdbot status
+# Probe the running gateway + providers (WA connect + Telegram + Discord APIs)
+clawdbot status --deep
+
+# View recent connection events
+tail -100 /tmp/clawdbot/clawdbot-*.log | grep "connection\\|disconnect\\|logout"
+```
+
+**Fix:** Usually reconnects automatically once the Gateway is running. If you’re stuck, restart the Gateway process (however you supervise it), or run it manually with verbose output:
+
+```bash
+clawdbot gateway --verbose
+```
+
+If you’re logged out / unlinked:
+
+```bash
+clawdbot logout
+rm -rf ~/.clawdbot/credentials # if logout can't cleanly remove everything
+clawdbot login --verbose       # re-scan QR
+```
+
+### Media Send Failing
+
+**Check 1:** Is the file path valid?
+```bash
+ls -la /path/to/your/image.jpg
+```
+
+**Check 2:** Is it too large?
+- Images: max 6MB
+- Audio/Video: max 16MB  
+- Documents: max 100MB
+
+**Check 3:** Check media logs
+```bash
+grep "media\\|fetch\\|download" "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)" | tail -20
+```
+
+### High Memory Usage
+
+CLAWDBOT keeps conversation history in memory.
+
+**Fix:** Restart periodically or set session limits:
+```json
+{
+  "session": {
+    "historyLimit": 100  // Max messages to keep
+  }
+}
+```
+
+## macOS Specific Issues
+
+### App Crashes when Granting Permissions (Speech/Mic)
+
+If the app disappears or shows "Abort trap 6" when you click "Allow" on a privacy prompt:
+
+**Fix 1: Reset TCC Cache**
+```bash
+tccutil reset All com.clawdbot.mac.debug
+```
+
+**Fix 2: Force New Bundle ID**
+If resetting doesn't work, change the `BUNDLE_ID` in `scripts/package-mac-app.sh` (e.g., add a `.test` suffix) and rebuild. This forces macOS to treat it as a new app.
+
+### Gateway stuck on "Starting..."
+
+The app connects to a local gateway on port `18789`. If it stays stuck:
+
+**Fix 1: Kill Zombie Processes**
+Another process might be holding the port.
+```bash
+lsof -nP -i :18789
+# Kill any matching PIDs
+kill -9 <PID>
+```
+
+**Fix 2: Check embedded gateway**
+Ensure the gateway relay was properly bundled. Run `./scripts/package-mac-app.sh` and ensure `bun` is installed.
+
+## Debug Mode
+
+Get verbose logging:
+
+```bash
+# Turn on trace logging in config:
+#   ~/.clawdbot/clawdbot.json -> { logging: { level: "trace" } }
+#
+# Then run verbose commands to mirror debug output to stdout:
+clawdbot gateway --verbose
+clawdbot login --verbose
+```
+
+## Log Locations
+
+| Log | Location |
+|-----|----------|
+| Main logs (default) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` |
+| Session files | `~/.clawdbot/sessions/` |
+| Media cache | `~/.clawdbot/media/` |
+| Credentials | `~/.clawdbot/credentials/` |
+
+## Health Check
+
+```bash
+# Is the gateway reachable?
+clawdbot health --json
+
+# Is something listening on the default port?
+lsof -nP -iTCP:18789 -sTCP:LISTEN
+
+# Recent activity
+tail -20 /tmp/clawdbot/clawdbot-*.log
+```
+
+## Reset Everything
+
+Nuclear option:
+
+```bash
+rm -rf ~/.clawdbot
+clawdbot login         # re-pair WhatsApp
+clawdbot gateway        # start the Gateway again
+```
+
+⚠️ This loses all sessions and requires re-pairing WhatsApp.
+
+## Getting Help
+
+1. Check logs first: `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`, or your configured `logging.file`)
+2. Search existing issues on GitHub
+3. Open a new issue with:
+   - CLAWDBOT version
+   - Relevant log snippets
+   - Steps to reproduce
+   - Your config (redact secrets!)
+
+---
+
+*"Have you tried turning it off and on again?"* — Every IT person ever
+
+🦞🔧

package/docs/tui.md

@@ -0,0 +1,69 @@
+---
+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 `/models`)
+- `/think <off|minimal|low|medium|high>`
+- `/verbose <on|off>`
+- `/elevated <on|off>`
+- `/activation <mention|always>`
+- `/deliver <on|off>`
+- `/new` or `/reset`
+- `/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`
+- Runner: `src/tui/tui.ts`
+- Gateway client: `src/tui/gateway-chat.ts`