fengming 0.3.9 → 0.3.11

package/docs/web/dashboard.md

@@ -1,107 +0,0 @@
----
-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: `fengming dashboard` (copies link, opens browser if possible, shows SSH hint if headless).
-- If clipboard and browser delivery fail, `fengming dashboard` still prints the
-  clean URL and tells you to use the token from `FENGMING_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
-  `FENGMING_GATEWAY_TOKEN`); `fengming 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, `fengming 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, `fengming dashboard` still prints a non-tokenized URL plus
-  actionable auth setup guidance.
-- **Shared-secret password**: use the configured `gateway.auth.password` (or
-  `FENGMING_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: `fengming 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: `fengming config get gateway.auth.token`
-  - Password: resolve the configured `gateway.auth.password` or
-    `FENGMING_GATEWAY_PASSWORD`
-  - SecretRef-managed token: resolve the external secret provider or export
-    `FENGMING_GATEWAY_TOKEN` in this shell, then rerun `fengming dashboard`
-  - No shared secret configured: `fengming 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

@@ -1,133 +0,0 @@
----
-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. `/fengming`)
-
-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: "/fengming" }, // 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
-fengming 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
-fengming 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 FENGMING_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

@@ -1,250 +0,0 @@
----
-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
-fengming gateway
-```
-
-2. Open the TUI.
-
-```bash
-fengming tui
-```
-
-3. Type a message and press Enter.
-
-Remote Gateway:
-
-```bash
-fengming 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
-fengming chat
-# or
-fengming tui --local
-```
-
-Notes:
-
-- `fengming chat` and `fengming terminal` are aliases for `fengming 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.
-- After a config file has authored settings, `fengming` and `fengming 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 + goal state + 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.
-- If the session has a [goal](/tools/goal), the footer shows its compact state
-  such as `Pursuing goal`, `Goal paused (/goal resume)`, or
-  `Goal achieved`.
-- 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 `fengming 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>`
-- `/goal [status] | /goal start <objective> | /goal pause|resume|complete|block|clear`
-- `/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 `FENGMING_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 `fengming config validate` is already failing, start with `fengming configure`
-or `fengming doctor --fix` first. `fengming chat` does not bypass the invalid-
-config guard.
-
-Typical loop:
-
-1. Start local mode:
-
-```bash
-fengming 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
-!fengming config file
-!fengming docs gateway auth token secretref
-!fengming config validate
-!fengming doctor
-```
-
-4. Apply narrow changes with `fengming config set` or `fengming configure`, then rerun `!fengming config validate`.
-5. If Doctor recommends an automatic migration or repair, review it and run `!fengming doctor --fix`.
-
-Tips:
-
-- Prefer `fengming config set` or `fengming configure` over hand-editing `fengming.json`.
-- `fengming docs "<query>"` searches the live docs index from the same machine.
-- `fengming 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 `FENGMING_THEME=light` before launching `fengming tui`.
-- To force the original dark palette instead, set `FENGMING_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: `fengming logs --follow`.
-- Confirm the agent can run: `fengming status` and `fengming 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 `fengming 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 `fengming.json`
-- [Doctor](/cli/doctor) — guided repair and migration checks
-- [CLI Reference](/cli) — full CLI command reference

package/docs/web/webchat.md

@@ -1,102 +0,0 @@
----
-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 the compacted transcript is preserved as a checkpoint and links to the Sessions checkpoint controls, where operators can branch or restore from that compacted 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 FengMing 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, the embedded FengMing runtime 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 embedded agent 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 the embedded runtime writes the assistant `message_end`. Any fallback that mirrors a delivered final payload into the transcript must first avoid duplicating an assistant turn that the embedded runtime 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 a server-derived
-    read-only projection of the current session inventory, including core, plugin, channel-owned,
-    and already-discovered MCP server 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. If configured MCP servers have not been connected or were changed
-  since the last discovery, the panel shows a notice instead of silently starting MCP transports
-  from the read path.
-- 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)