nodmix 2026.5.25

package/docs/web/dashboard.md

@@ -0,0 +1,107 @@
+---
+summary: "Gateway dashboard (Control UI) access and auth"
+read_when:
+  - Changing dashboard authentication or exposure modes
+title: "Dashboard"
+---
+
+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/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/))
+- With `gateway.tls.enabled: true`, use `https://127.0.0.1:18789/` and
+  `wss://127.0.0.1:18789` for the WebSocket endpoint.
+
+Key references:
+
+- [Control UI](/web/control-ui) for usage and UI capabilities.
+- [Tailscale](/gateway/tailscale) for Serve/Funnel automation.
+- [Web surfaces](/web) for bind modes and security notes.
+
+Authentication is enforced at the WebSocket handshake via the configured gateway
+auth path:
+
+- `connect.params.auth.token`
+- `connect.params.auth.password`
+- Tailscale Serve identity headers when `gateway.auth.allowTailscale: true`
+- trusted-proxy identity headers when `gateway.auth.mode: "trusted-proxy"`
+
+See `gateway.auth` in [Gateway configuration](/gateway/configuration).
+
+Security note: the Control UI is an **admin surface** (chat, config, exec approvals).
+Do not expose it publicly. The UI keeps dashboard URL tokens in sessionStorage
+for the current browser tab session and selected gateway URL, and strips them from the URL after load.
+Prefer localhost, Tailscale Serve, or an SSH tunnel.
+
+## Fast path (recommended)
+
+- After onboarding, the CLI auto-opens the dashboard and prints a clean (non-tokenized) link.
+- Re-open anytime: `nodmix dashboard` (copies link, opens browser if possible, shows SSH hint if headless).
+- If clipboard and browser delivery fail, `nodmix dashboard` still prints the
+  clean URL and tells you to use the token from `NODMIX_GATEWAY_TOKEN` or
+  `gateway.auth.token` as the URL fragment key `token`; it does not print token
+  values in logs.
+- If the UI prompts for shared-secret auth, paste the configured token or
+  password into Control UI settings.
+
+## Auth basics (local vs remote)
+
+- **Localhost**: open `http://127.0.0.1:18789/`.
+- **Gateway TLS**: when `gateway.tls.enabled: true`, dashboard/status links use
+  `https://` and Control UI WebSocket links use `wss://`.
+- **Shared-secret token source**: `gateway.auth.token` (or
+  `NODMIX_GATEWAY_TOKEN`); `nodmix dashboard` can pass it via URL fragment
+  for one-time bootstrap, and the Control UI keeps it in sessionStorage for the
+  current browser tab session and selected gateway URL instead of localStorage.
+- If `gateway.auth.token` is SecretRef-managed, `nodmix dashboard`
+  prints/copies/opens a non-tokenized URL by design. This avoids exposing
+  externally managed tokens in shell logs, clipboard history, or browser-launch
+  arguments.
+- If `gateway.auth.token` is configured as a SecretRef and is unresolved in your
+  current shell, `nodmix dashboard` still prints a non-tokenized URL plus
+  actionable auth setup guidance.
+- **Shared-secret password**: use the configured `gateway.auth.password` (or
+  `NODMIX_GATEWAY_PASSWORD`). The dashboard does not persist passwords across
+  reloads.
+- **Identity-bearing modes**: Tailscale Serve can satisfy Control UI/WebSocket
+  auth via identity headers when `gateway.auth.allowTailscale: true`, and a
+  non-loopback identity-aware reverse proxy can satisfy
+  `gateway.auth.mode: "trusted-proxy"`. In those modes the dashboard does not
+  need a pasted shared secret for the WebSocket.
+- **Not localhost**: use Tailscale Serve, a non-loopback shared-secret bind, a
+  non-loopback identity-aware reverse proxy with
+  `gateway.auth.mode: "trusted-proxy"`, or an SSH tunnel. HTTP APIs still use
+  shared-secret auth unless you intentionally run private-ingress
+  `gateway.auth.mode: "none"` or trusted-proxy HTTP auth. See
+  [Web surfaces](/web).
+
+<a id="if-you-see-unauthorized-1008"></a>
+
+## If you see "unauthorized" / 1008
+
+- Ensure the gateway is reachable (local: `nodmix status`; remote: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`).
+- For `AUTH_TOKEN_MISMATCH`, clients may do one trusted retry with a cached device token when the gateway returns retry hints. That cached-token retry reuses the token's cached approved scopes; explicit `deviceToken` / explicit `scopes` callers keep their requested scope set. If auth still fails after that retry, resolve token drift manually.
+- For `AUTH_SCOPE_MISMATCH`, the device token was recognized but does not carry the dashboard's requested scopes; re-pair or approve the requested scope contract instead of rotating the shared gateway token.
+- Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
+- On the async Tailscale Serve Control UI path, failed attempts for the same
+  `{scope, ip}` are serialized before the failed-auth limiter records them, so
+  the second concurrent bad retry can already show `retry later`.
+- For token drift repair steps, follow [Token drift recovery checklist](/cli/devices#token-drift-recovery-checklist).
+- Retrieve or supply the shared secret from the gateway host:
+  - Token: `nodmix config get gateway.auth.token`
+  - Password: resolve the configured `gateway.auth.password` or
+    `NODMIX_GATEWAY_PASSWORD`
+  - SecretRef-managed token: resolve the external secret provider or export
+    `NODMIX_GATEWAY_TOKEN` in this shell, then rerun `nodmix dashboard`
+  - No shared secret configured: `nodmix doctor --generate-gateway-token`
+- In the dashboard settings, paste the token or password into the auth field,
+  then connect.
+- The UI language picker is in **Overview -> Gateway Access -> Language**.
+  It is part of the access card, not the Appearance section.
+
+## Related
+
+- [Control UI](/web/control-ui)
+- [WebChat](/web/webchat)

package/docs/web/index.md

@@ -0,0 +1,133 @@
+---
+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
+title: "Web"
+---
+
+The Gateway serves a small **browser Control UI** (Vite + Lit) from the same port as the Gateway WebSocket:
+
+- default: `http://<host>:18789/`
+- with `gateway.tls.enabled: true`: `https://<host>:18789/`
+- optional prefix: set `gateway.controlUi.basePath` (e.g. `/nodmix`)
+
+Capabilities live in [Control UI](/web/control-ui). The rest of 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 [Gateway configuration](/gateway/configuration) → `hooks` for auth + payloads.
+
+## Admin HTTP RPC
+
+Admin HTTP RPC exposes selected Gateway control-plane methods at `POST /api/v1/admin/rpc`.
+It is off by default and is registered only when the `admin-http-rpc` plugin is enabled.
+See [Admin HTTP RPC](/plugins/admin-http-rpc) for the auth model, allowed methods, and WebSocket comparison.
+
+## 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: "/nodmix" }, // 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
+nodmix gateway
+```
+
+Open:
+
+- `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
+
+### Tailnet bind + token
+
+```json5
+{
+  gateway: {
+    bind: "tailnet",
+    controlUi: { enabled: true },
+    auth: { mode: "token", token: "your-token" },
+  },
+}
+```
+
+Then start the gateway (this non-loopback example uses shared-secret token
+auth):
+
+```bash
+nodmix 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 NODMIX_GATEWAY_PASSWORD
+  },
+}
+```
+
+## Security notes
+
+- Gateway auth is required by default (token, password, trusted-proxy, or Tailscale Serve identity headers when enabled).
+- Non-loopback binds still **require** gateway auth. In practice that means token/password auth or an identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`.
+- The wizard creates shared-secret auth by default and usually generates a
+  gateway token (even on loopback).
+- In shared-secret mode, the UI sends `connect.params.auth.token` or
+  `connect.params.auth.password`.
+- When `gateway.tls.enabled: true`, local dashboard and status helpers render
+  `https://` dashboard URLs and `wss://` WebSocket URLs.
+- In identity-bearing modes such as Tailscale Serve or `trusted-proxy`, the
+  WebSocket auth check is satisfied from request headers instead.
+- For public non-loopback Control UI deployments, set `gateway.controlUi.allowedOrigins`
+  explicitly (full origins). Private same-origin LAN/Tailnet loads are accepted for loopback,
+  RFC1918/link-local, `.local`, `.ts.net`, and Tailscale CGNAT hosts.
+- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` enables
+  Host-header origin fallback mode, but is a dangerous security downgrade.
+- With Serve, Tailscale identity headers can satisfy Control UI/WebSocket auth
+  when `gateway.auth.allowTailscale` is `true` (no token/password required).
+  HTTP API endpoints do not use those Tailscale identity headers; they follow
+  the gateway's normal HTTP auth mode instead. Set
+  `gateway.auth.allowTailscale: false` to require explicit credentials. See
+  [Tailscale](/gateway/tailscale) and [Security](/gateway/security). This
+  tokenless flow assumes the gateway host is trusted.
+- `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
+pnpm ui:build
+```

package/docs/web/tui.md

@@ -0,0 +1,246 @@
+---
+summary: "Terminal UI (TUI): connect to the Gateway or run locally in embedded mode"
+read_when:
+  - You want a beginner-friendly walkthrough of the TUI
+  - You need the complete list of TUI features, commands, and shortcuts
+title: "TUI"
+---
+
+## Quick start
+
+### Gateway mode
+
+1. Start the Gateway.
+
+```bash
+nodmix gateway
+```
+
+2. Open the TUI.
+
+```bash
+nodmix tui
+```
+
+3. Type a message and press Enter.
+
+Remote Gateway:
+
+```bash
+nodmix tui --url ws://<host>:<port> --token <gateway-token>
+```
+
+Use `--password` if your Gateway uses password auth.
+
+### Local mode
+
+Run the TUI without a Gateway:
+
+```bash
+nodmix chat
+# or
+nodmix tui --local
+```
+
+Notes:
+
+- `nodmix chat` and `nodmix terminal` are aliases for `nodmix tui --local`.
+- `--local` cannot be combined with `--url`, `--token`, or `--password`.
+- Local mode uses the embedded agent runtime directly. Most local tools work, but Gateway-only features are unavailable.
+- `nodmix` and `nodmix crestodian` also use this TUI shell, with Crestodian as the local setup and repair chat backend.
+
+## What you see
+
+- Header: connection URL, current agent, current session.
+- Chat log: user messages, assistant replies, system notices, tool cards.
+- Status line: connection/run state (connecting, running, streaming, idle, error).
+- Footer: connection state + agent + session + model + think/fast/verbose/trace/reasoning + token counts + deliver.
+- Input: text editor with autocomplete.
+
+## Mental model: agents + sessions
+
+- Agents are unique slugs (e.g. `main`, `research`). The Gateway exposes the list.
+- Sessions belong to the current agent.
+- Session keys are stored as `agent:<agentId>:<sessionKey>`.
+  - If you type `/session main`, the TUI expands it to `agent:<currentAgent>:main`.
+  - If you type `/session agent:other:main`, you switch to that agent session explicitly.
+- Session scope:
+  - `per-sender` (default): each agent has many sessions.
+  - `global`: the TUI always uses the `global` session (the picker may be empty).
+- The current agent + session are always visible in the footer.
+- When started without `--session`, gateway-mode TUI resumes the last selected session for the same gateway, agent, and session scope if that session still exists. Passing `--session`, `/session`, `/new`, or `/reset` remains explicit.
+
+## Sending + delivery
+
+- Messages are sent to the Gateway; delivery to providers is off by default.
+- The TUI is an internal source surface like WebChat, not a generic outbound channel. Harnesses that require `tools.message` for visible replies can satisfy the active TUI turn with a targetless `message.send`; explicit provider delivery still uses normal configured channels and never falls back to `lastChannel`.
+- Turn delivery on:
+  - `/deliver on`
+  - or the Settings panel
+  - or start with `nodmix tui --deliver`
+
+## Pickers + overlays
+
+- Model picker: list available models and set the session override.
+- Agent picker: choose a different agent.
+- Session picker: shows up to 50 sessions for the current agent updated in the last 7 days. Use `/session <key>` to jump to an older known session.
+- Settings: toggle deliver, tool output expansion, and thinking visibility.
+
+## Keyboard shortcuts
+
+- Enter: send message
+- Esc: abort active run
+- Ctrl+C: clear input (press twice to exit)
+- Ctrl+D: exit
+- Ctrl+L: model picker
+- Ctrl+G: agent picker
+- Ctrl+P: session picker
+- Ctrl+O: toggle tool output expansion
+- Ctrl+T: toggle thinking visibility (reloads history)
+
+## Slash commands
+
+Core:
+
+- `/help`
+- `/status`
+- `/agent <id>` (or `/agents`)
+- `/session <key>` (or `/sessions`)
+- `/model <provider/model>` (or `/models`)
+
+Session controls:
+
+- `/think <off|minimal|low|medium|high>`
+- `/fast <status|on|off>`
+- `/verbose <on|full|off>`
+- `/trace <on|off>`
+- `/reasoning <on|off|stream>`
+- `/usage <off|tokens|full>`
+- `/elevated <on|off|ask|full>` (alias: `/elev`)
+- `/activation <mention|always>`
+- `/deliver <on|off>`
+
+Session lifecycle:
+
+- `/new` or `/reset` (reset the session)
+- `/abort` (abort the active run)
+- `/settings`
+- `/exit`
+
+Local mode only:
+
+- `/auth [provider]` opens the provider auth/login flow inside the TUI.
+
+Other Gateway slash commands (for example, `/context`) are forwarded to the Gateway and shown as system output. See [Slash commands](/tools/slash-commands).
+
+## Local shell commands
+
+- Prefix a line with `!` to run a local shell command on the TUI host.
+- The TUI prompts once per session to allow local execution; declining keeps `!` disabled for the session.
+- Commands run in a fresh, non-interactive shell in the TUI working directory (no persistent `cd`/env).
+- Local shell commands receive `NODMIX_SHELL=tui-local` in their environment.
+- A lone `!` is sent as a normal message; leading spaces do not trigger local exec.
+
+## Repair configs from the local TUI
+
+Use local mode when the current config already validates and you want the
+embedded agent to inspect it on the same machine, compare it against the docs,
+and help repair drift without depending on a running Gateway.
+
+If `nodmix config validate` is already failing, start with `nodmix configure`
+or `nodmix doctor --fix` first. `nodmix chat` does not bypass the invalid-
+config guard.
+
+Typical loop:
+
+1. Start local mode:
+
+```bash
+nodmix chat
+```
+
+2. Ask the agent what you want checked, for example:
+
+```text
+Compare my gateway auth config with the docs and suggest the smallest fix.
+```
+
+3. Use local shell commands for exact evidence and validation:
+
+```text
+!nodmix config file
+!nodmix docs gateway auth token secretref
+!nodmix config validate
+!nodmix doctor
+```
+
+4. Apply narrow changes with `nodmix config set` or `nodmix configure`, then rerun `!nodmix config validate`.
+5. If Doctor recommends an automatic migration or repair, review it and run `!nodmix doctor --fix`.
+
+Tips:
+
+- Prefer `nodmix config set` or `nodmix configure` over hand-editing `nodmix.json`.
+- `nodmix docs "<query>"` searches the live docs index from the same machine.
+- `nodmix config validate --json` is useful when you want structured schema and SecretRef/resolvability errors.
+
+## Tool output
+
+- Tool calls show as cards with args + results.
+- Ctrl+O toggles between collapsed/expanded views.
+- While tools run, partial updates stream into the same card.
+
+## Terminal colors
+
+- The TUI keeps assistant body text in your terminal's default foreground so dark and light terminals both stay readable.
+- If your terminal uses a light background and auto-detection is wrong, set `NODMIX_THEME=light` before launching `nodmix tui`.
+- To force the original dark palette instead, set `NODMIX_THEME=dark`.
+
+## History + streaming
+
+- On connect, the TUI loads the latest history (default 200 messages).
+- Streaming responses update in place until finalized.
+- The TUI also listens to agent tool events for richer tool cards.
+
+## Connection details
+
+- The TUI registers with the Gateway as `mode: "tui"`.
+- Reconnects show a system message; event gaps are surfaced in the log.
+
+## Options
+
+- `--local`: Run against the local embedded agent runtime
+- `--url <url>`: Gateway WebSocket URL (defaults to config or `ws://127.0.0.1:<port>`)
+- `--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
+- `--message <text>`: Send an initial message after connecting
+- `--timeout-ms <ms>`: Agent timeout in ms (defaults to `agents.defaults.timeoutSeconds`)
+- `--history-limit <n>`: History entries to load (default `200`)
+
+<Warning>
+When you set `--url`, the TUI does not fall back to config or environment credentials. Pass `--token` or `--password` explicitly. Missing explicit credentials is an error. In local mode, do not pass `--url`, `--token`, or `--password`.
+</Warning>
+
+## Troubleshooting
+
+No output after sending a message:
+
+- Run `/status` in the TUI to confirm the Gateway is connected and idle/busy.
+- Check the Gateway logs: `nodmix logs --follow`.
+- Confirm the agent can run: `nodmix status` and `nodmix models status`.
+- If you expect messages in a chat channel, enable delivery (`/deliver on` or `--deliver`).
+
+## Connection troubleshooting
+
+- `disconnected`: ensure the Gateway is running and your `--url/--token/--password` are correct.
+- No agents in picker: check `nodmix agents list` and your routing config.
+- Empty session picker: you might be in global scope or have no sessions yet.
+
+## Related
+
+- [Control UI](/web/control-ui) — web-based control interface
+- [Config](/cli/config) — inspect, validate, and edit `nodmix.json`
+- [Doctor](/cli/doctor) — guided repair and migration checks
+- [CLI Reference](/cli) — full CLI command reference

package/docs/web/webchat.md

@@ -0,0 +1,99 @@
+---
+summary: "Loopback WebChat static host and Gateway WS usage for chat UI"
+read_when:
+  - Debugging or configuring WebChat access
+title: "WebChat"
+---
+
+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 channels.
+- Deterministic routing: replies always go back to WebChat.
+
+## Quick start
+
+1. Start the gateway.
+2. Open the WebChat UI (macOS/iOS app) or the Control UI chat tab.
+3. Ensure a valid gateway auth path is configured (shared-secret by default,
+   even on loopback).
+
+## How it works (behavior)
+
+- The UI connects to the Gateway WebSocket and uses `chat.history`, `chat.send`, and `chat.inject`.
+- `chat.history` is bounded for stability: Gateway may truncate long text fields, omit heavy metadata, and replace oversized entries with `[chat.history omitted: message too large]`.
+- `chat.history` follows the active transcript branch for modern append-only session files, so abandoned rewrite branches and superseded prompt copies are not rendered in WebChat.
+- Compaction entries render as an explicit compacted-history divider. The divider explains that earlier turns are preserved in a checkpoint and links to the Sessions checkpoint controls, where operators can branch or restore the pre-compaction view when their permissions allow it.
+- Control UI remembers the backing Gateway `sessionId` returned by `chat.history` and includes it on follow-up `chat.send` calls, so reconnects and page refreshes continue the same stored conversation unless the user starts or resets a session.
+- Control UI coalesces duplicate in-flight submits for the same session, message, and attachments before generating a new `chat.send` run id; the Gateway still dedupes repeated requests that reuse the same idempotency key.
+- Workspace startup files and pending `BOOTSTRAP.md` instructions are supplied through the agent system prompt's Project Context, not copied into the WebChat user message. Bootstrap truncation only adds a concise system-prompt recovery notice; detailed counts and config knobs stay on diagnostic surfaces.
+- `chat.history` is also display-normalized: runtime-only Nodmix context,
+  inbound envelope wrappers, inline delivery directive tags
+  such as `[[reply_to_*]]` and `[[audio_as_voice]]`, plain-text tool-call XML
+  payloads (including `<tool_call>...</tool_call>`,
+  `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
+  `<function_calls>...</function_calls>`, and truncated tool-call blocks), and
+  leaked ASCII/full-width model control tokens are stripped from visible text,
+  and assistant entries whose whole visible text is only the exact silent
+  token `NO_REPLY` / `no_reply` are omitted.
+- Reasoning-flagged reply payloads (`isReasoning: true`) are excluded from WebChat assistant content, transcript replay text, and audio content blocks, so thinking-only payloads do not surface as visible assistant messages or playable audio.
+- `chat.inject` appends an assistant note directly to the transcript and broadcasts it to the UI (no agent run).
+- Aborted runs can keep partial assistant output visible in the UI.
+- Gateway persists aborted partial assistant text into transcript history when buffered output exists, and marks those entries with abort metadata.
+- History is always fetched from the gateway (no local file watching).
+- If the gateway is unreachable, WebChat is read-only.
+
+### Transcript and delivery model
+
+WebChat has two separate data paths:
+
+- The session JSONL file is the durable model/runtime transcript. For normal agent runs, Pi persists model-visible `user`, `assistant`, and `toolResult` messages through its session manager. WebChat does not write arbitrary delivery, status, or helper text into that transcript.
+- Gateway `ReplyPayload` events are the live delivery projection. They can be normalized for WebChat/channel display, block streaming, directive tags, media embedding, TTS/audio flags, and UI fallback behavior. They are not themselves the canonical session log.
+- Harnesses that require visible replies through `tools.message` still use WebChat as a current-run internal source reply sink. A targetless `message.send` from that active WebChat run is projected into the same chat and mirrored to the session transcript; WebChat does not become a reusable outbound channel and never inherits `lastChannel`.
+- WebChat injects assistant transcript entries only when the Gateway owns a displayed message outside a normal Pi assistant turn: `chat.inject`, non-agent command replies, aborted partial output, and WebChat-managed media transcript supplements.
+- `chat.history` reads the stored session transcript and applies WebChat display projection. If live assistant text appears during a run but disappears after history reload, first check whether the raw JSONL contains the assistant text, then whether `chat.history` projection stripped it, then whether the Control UI optimistic-tail merge replaced local delivery state with the persisted snapshot.
+
+Normal agent-run final answers should be durable because Pi writes the assistant `message_end`. Any fallback that mirrors a delivered final payload into the transcript must first avoid duplicating an assistant turn that Pi already wrote.
+
+## Control UI agents tools panel
+
+- The Control UI `/agents` Tools panel has two separate views:
+  - **Available Right Now** uses `tools.effective(sessionKey=...)` and shows what the current
+    session can actually use at runtime, including core, plugin, and channel-owned tools.
+  - **Tool Configuration** uses `tools.catalog` and stays focused on profiles, overrides, and
+    catalog semantics.
+- Runtime availability is session-scoped. Switching sessions on the same agent can change the
+  **Available Right Now** list.
+- The config editor does not imply runtime availability; effective access still follows policy
+  precedence (`allow`/`deny`, per-agent and provider/channel overrides).
+
+## 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](/gateway/configuration)
+
+WebChat options:
+
+- `gateway.webchat.chatHistoryMaxChars`: maximum character count for text fields in `chat.history` responses. When a transcript entry exceeds this limit, Gateway truncates long text fields and may replace oversized messages with a placeholder. Per-request `maxChars` can also be sent by the client to override this default for a single `chat.history` call.
+
+Related global options:
+
+- `gateway.port`, `gateway.bind`: WebSocket host/port.
+- `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`:
+  shared-secret WebSocket auth.
+- `gateway.auth.allowTailscale`: browser Control UI chat tab can use Tailscale
+  Serve identity headers when enabled.
+- `gateway.auth.mode: "trusted-proxy"`: reverse-proxy auth for browser clients behind an identity-aware **non-loopback** proxy source (see [Trusted Proxy Auth](/gateway/trusted-proxy-auth)).
+- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: remote gateway target.
+- `session.*`: session storage and main key defaults.
+
+## Related
+
+- [Control UI](/web/control-ui)
+- [Dashboard](/web/dashboard)