fengming 0.3.10 → 0.3.12

package/docs/vps.md

@@ -1,139 +0,0 @@
----
-summary: "Run FengMing on a Linux server or cloud VPS — provider picker, architecture, and tuning"
-read_when:
-  - You want to run the Gateway on a Linux server or cloud VPS
-  - You need a quick map of hosting guides
-  - You want generic Linux server tuning for FengMing
-title: "Linux server"
-sidebarTitle: "Linux Server"
----
-
-Run the FengMing Gateway on any Linux server or cloud VPS. This page helps you
-pick a provider, explains how cloud deployments work, and covers generic Linux
-tuning that applies everywhere.
-
-## Pick a provider
-
-<CardGroup cols={2}>
-  <Card title="Railway" href="/install/railway">One-click, browser setup</Card>
-  <Card title="Northflank" href="/install/northflank">One-click, browser setup</Card>
-  <Card title="DigitalOcean" href="/install/digitalocean">Simple paid VPS</Card>
-  <Card title="Oracle Cloud" href="/install/oracle">Always Free ARM tier</Card>
-  <Card title="Fly.io" href="/install/fly">Fly Machines</Card>
-  <Card title="Hetzner" href="/install/hetzner">Docker on Hetzner VPS</Card>
-  <Card title="Hostinger" href="/install/hostinger">VPS with one-click setup</Card>
-  <Card title="GCP" href="/install/gcp">Compute Engine</Card>
-  <Card title="Azure" href="/install/azure">Linux VM</Card>
-  <Card title="exe.dev" href="/install/exe-dev">VM with HTTPS proxy</Card>
-  <Card title="Raspberry Pi" href="/install/raspberry-pi">ARM self-hosted</Card>
-</CardGroup>
-
-**AWS (EC2 / Lightsail / free tier)** also works well.
-A community video walkthrough is available at
-[x.com/techfrenAJ/status/2014934471095812547](https://x.com/techfrenAJ/status/2014934471095812547)
-(community resource -- may become unavailable).
-
-## How cloud setups work
-
-- The **Gateway runs on the VPS** and owns state + workspace.
-- You connect from your laptop or phone via the **Control UI** or **Tailscale/SSH**.
-- Treat the VPS as the source of truth and **back up** the state + workspace regularly.
-- Secure default: keep the Gateway on loopback and access it via SSH tunnel or Tailscale Serve.
-  If you bind to `lan` or `tailnet`, require `gateway.auth.token` or `gateway.auth.password`.
-
-Related pages: [Gateway remote access](/gateway/remote), [Platforms hub](/platforms).
-
-## Harden admin access first
-
-Before you install FengMing on a public VPS, decide how you want to administer
-the box itself.
-
-- If you want Tailnet-only admin access, install Tailscale first, join the VPS
-  to your tailnet, verify a second SSH session over the Tailscale IP or
-  MagicDNS name, then restrict public SSH.
-- If you are not using Tailscale, apply the equivalent hardening for your SSH
-  path before exposing more services.
-- This is separate from Gateway access. You can still keep FengMing bound to
-  loopback and use an SSH tunnel or Tailscale Serve for the dashboard.
-
-Tailscale-specific Gateway options live in [Tailscale](/gateway/tailscale).
-
-## Shared company agent on a VPS
-
-Running a single agent for a team is a valid setup when every user is in the same trust boundary and the agent is business-only.
-
-- Keep it on a dedicated runtime (VPS/VM/container + dedicated OS user/accounts).
-- Do not sign that runtime into personal Apple/Google accounts or personal browser/password-manager profiles.
-- If users are adversarial to each other, split by gateway/host/OS user.
-
-Security model details: [Security](/gateway/security).
-
-## Using nodes with a VPS
-
-You can keep the Gateway in the cloud and pair **nodes** on your local devices
-(Mac/iOS/Android/headless). Nodes provide local screen/camera/canvas and `system.run`
-capabilities while the Gateway stays in the cloud.
-
-Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes).
-
-## Startup tuning for small VMs and ARM hosts
-
-If CLI commands feel slow on low-power VMs (or ARM hosts), enable Node's module compile cache:
-
-```bash
-grep -q 'NODE_COMPILE_CACHE=/var/tmp/fengming-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF'
-export NODE_COMPILE_CACHE=/var/tmp/fengming-compile-cache
-mkdir -p /var/tmp/fengming-compile-cache
-export FENGMING_NO_RESPAWN=1
-EOF
-source ~/.bashrc
-```
-
-- `NODE_COMPILE_CACHE` improves repeated command startup times.
-- `FENGMING_NO_RESPAWN=1` keeps routine Gateway restarts in-process, which avoids extra process handoffs and keeps PID tracking simple on small hosts.
-- First command run warms the cache; subsequent runs are faster.
-- For Raspberry Pi specifics, see [Raspberry Pi](/install/raspberry-pi).
-
-### systemd tuning checklist (optional)
-
-For VM hosts using `systemd`, consider:
-
-- Add service env for a stable startup path:
-  - `FENGMING_NO_RESPAWN=1`
-  - `NODE_COMPILE_CACHE=/var/tmp/fengming-compile-cache`
-- Keep restart behavior explicit:
-  - `Restart=always`
-  - `RestartSec=2`
-  - `TimeoutStartSec=90`
-- Prefer SSD-backed disks for state/cache paths to reduce random-I/O cold-start penalties.
-
-For the standard `fengming onboard --install-daemon` path, edit the user unit:
-
-```bash
-systemctl --user edit fengming-gateway.service
-```
-
-```ini
-[Service]
-Environment=FENGMING_NO_RESPAWN=1
-Environment=NODE_COMPILE_CACHE=/var/tmp/fengming-compile-cache
-Restart=always
-RestartSec=2
-TimeoutStartSec=90
-```
-
-If you deliberately installed a system unit instead, edit
-`fengming-gateway.service` via `sudo systemctl edit fengming-gateway.service`.
-
-How `Restart=` policies help automated recovery:
-[systemd can automate service recovery](https://www.redhat.com/en/blog/systemd-automate-recovery).
-
-For Linux OOM behavior, child process victim selection, and `exit 137`
-diagnostics, see [Linux memory pressure and OOM kills](/platforms/linux#memory-pressure-and-oom-kills).
-
-## Related
-
-- [Install overview](/install)
-- [DigitalOcean](/install/digitalocean)
-- [Fly.io](/install/fly)
-- [Hetzner](/install/hetzner)

package/docs/web/control-ui.md

@@ -1,512 +0,0 @@
----
-summary: "Browser-based control UI for the Gateway (chat, activity, nodes, config)"
-read_when:
-  - You want to operate the Gateway from a browser
-  - You want Tailnet access without SSH tunnels
-title: "Control UI"
-sidebarTitle: "Control UI"
----
-
-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. `/fengming`)
-
-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/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/))
-
-If the page fails to load, start the Gateway first: `fengming gateway`.
-
-Auth is supplied during the WebSocket handshake via:
-
-- `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"`
-
-The dashboard settings panel keeps a token for the current browser tab session and selected gateway URL; passwords are not persisted. Onboarding usually generates a gateway token for shared-secret auth on first connect, but password auth works too when `gateway.auth.mode` is `"password"`.
-
-## Device pairing (first connection)
-
-When you connect to the Control UI from a new browser or device, the Gateway usually requires a **one-time pairing approval**. This is a security measure to prevent unauthorized access.
-
-**What you'll see:** "disconnected (1008): pairing required"
-
-<Steps>
-  <Step title="List pending requests">
-    ```bash
-    fengming devices list
-    ```
-  </Step>
-  <Step title="Approve by request ID">
-    ```bash
-    fengming devices approve <requestId>
-    ```
-  </Step>
-</Steps>
-
-If the browser retries pairing with changed auth details (role/scopes/public key), the previous pending request is superseded and a new `requestId` is created. Re-run `fengming devices list` before approval.
-
-If the browser is already paired and you change it from read access to write/admin access, this is treated as an approval upgrade, not a silent reconnect. FengMing keeps the old approval active, blocks the broader reconnect, and asks you to approve the new scope set explicitly.
-
-Once approved, the device is remembered and won't require re-approval unless you revoke it with `fengming devices revoke --device <id> --role <role>`. See [Devices CLI](/cli/devices) for token rotation and revocation.
-
-Paperclip agents that connect through the `fengming_gateway` adapter use the same first-run approval flow. After the initial connection attempt, run `fengming devices approve --latest` to preview the pending request, then rerun the printed `fengming devices approve <requestId>` command to approve it. Pass explicit `--url` and `--token` values for a remote gateway. To keep approvals stable across restarts, configure a persistent `adapterConfig.devicePrivateKeyPem` in Paperclip instead of letting it generate a new ephemeral device identity each run.
-
-<Note>
-- Direct local loopback browser connections (`127.0.0.1` / `localhost`) are auto-approved.
-- Tailscale Serve can skip the pairing round trip for Control UI operator sessions when `gateway.auth.allowTailscale: true`, Tailscale identity verifies, and the browser presents its device identity.
-- Direct Tailnet binds, LAN browser connects, and browser profiles without device identity still require explicit approval.
-- Each browser profile generates a unique device ID, so switching browsers or clearing browser data will require re-pairing.
-
-</Note>
-
-## Personal identity (browser-local)
-
-The Control UI supports a per-browser personal identity (display name and avatar) attached to outgoing messages for attribution in shared sessions. It lives in browser storage, is scoped to the current browser profile, and is not synced to other devices or persisted server-side beyond the normal transcript authorship metadata on messages you actually send. Clearing site data or switching browsers resets it to empty.
-
-The same browser-local pattern applies to the assistant avatar override. Uploaded assistant avatars overlay the gateway-resolved identity on the local browser only and never round-trip through `config.patch`. The shared `ui.assistant.avatar` config field is still available for non-UI clients writing the field directly (such as scripted gateways or custom dashboards).
-
-## Runtime config endpoint
-
-The Control UI fetches its runtime settings from `/__fengming/control-ui-config.json`. That endpoint is gated by the same gateway auth as the rest of the HTTP surface: unauthenticated browsers cannot fetch it, and a successful fetch requires either an already valid gateway token/password, Tailscale Serve identity, or a trusted-proxy identity.
-
-## Language support
-
-The Control UI can localize itself on first load based on your browser locale. To override it later, open **Overview -> Gateway Access -> Language**. The locale picker lives in the Gateway Access card, not under Appearance.
-
-- Supported locales: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
-- Non-English translations are lazy-loaded in the browser.
-- The selected locale is saved in browser storage and reused on future visits.
-- Missing translation keys fall back to English.
-
-Docs translations are generated for the same non-English locale set, but the docs site's built-in Mintlify language picker is limited to the locale codes Mintlify accepts. Thai (`th`) and Persian (`fa`) docs are still generated in the publish repo; they may not appear in that picker until Mintlify supports those codes.
-
-## Appearance themes
-
-The Appearance panel keeps the built-in Claw, Knot, and Dash themes, plus one browser-local tweakcn import slot. To import a theme, open [tweakcn editor](https://tweakcn.com/editor/theme), choose or create a theme, click **Share**, and paste the copied theme link into Appearance. The importer also accepts `https://tweakcn.com/r/themes/<id>` registry URLs, editor URLs like `https://tweakcn.com/editor/theme?theme=amethyst-haze`, relative `/themes/<id>` paths, raw theme IDs, and default theme names such as `amethyst-haze`.
-
-Appearance also includes a browser-local Text size setting. The setting is stored with the rest of Control UI preferences, applies to chat text, composer text, tool cards, and chat sidebars, and keeps text inputs at least 16px so mobile Safari does not auto-zoom on focus.
-
-Imported themes are stored only in the current browser profile. They are not written to gateway config and do not sync across devices. Replacing the imported theme updates the one local slot; clearing it switches the active theme back to Claw if the imported theme was selected.
-
-## What it can do (today)
-
-<AccordionGroup>
-  <Accordion title="Chat and Talk">
-    - Chat with the model via Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
-    - Chat history refreshes request a bounded recent window with per-message text caps so large sessions do not force the browser to render a full transcript payload before the chat becomes usable.
-    - Talk through browser realtime sessions. OpenAI uses direct WebRTC, Google Live uses a constrained one-use browser token over WebSocket, and backend-only realtime voice plugins use the Gateway relay transport. Client-owned provider sessions start with `talk.client.create`; Gateway relay sessions start with `talk.session.create`. The relay keeps provider credentials on the Gateway while the browser streams microphone PCM through `talk.session.appendAudio`, forwards `fengming_agent_consult` provider tool calls through `talk.client.toolCall` for Gateway policy and the larger configured FengMing model, and routes active-run voice steering through `talk.client.steer` or `talk.session.steer`.
-    - Stream tool calls + live tool output cards in Chat (agent events).
-    - Activity tab with browser-local, redaction-first summaries of live tool activity from existing `session.tool` / tool event delivery.
-
-  </Accordion>
-  <Accordion title="Channels, instances, sessions, dreams">
-    - Channels: built-in plus bundled/external plugin channels status, QR login, and per-channel config (`channels.status`, `web.login.*`, `config.patch`).
-    - Channel probe refreshes keep the previous snapshot visible while slow provider checks finish, and partial snapshots are labeled when a probe or audit exceeds its UI budget.
-    - Instances: presence list + refresh (`system-presence`).
-    - Sessions: list configured-agent sessions by default, fall back from stale unconfigured agent session keys, and apply per-session model/thinking/fast/verbose/trace/reasoning overrides (`sessions.list`, `sessions.patch`).
-    - Dreams: dreaming status, enable/disable toggle, and Dream Diary reader (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
-
-  </Accordion>
-  <Accordion title="Cron, skills, nodes, exec approvals">
-    - Cron jobs: list/add/edit/run/enable/disable + run history (`cron.*`).
-    - Skills: status, enable/disable, install, API key updates (`skills.*`).
-    - Nodes: list + caps (`node.list`).
-    - Exec approvals: edit gateway or node allowlists + ask policy for `exec host=gateway/node` (`exec.approvals.*`).
-
-  </Accordion>
-  <Accordion title="Config">
-    - View/edit `~/.fengming/fengming.json` (`config.get`, `config.set`).
-    - Apply + restart with validation (`config.apply`) and wake the last active session.
-    - Writes include a base-hash guard to prevent clobbering concurrent edits.
-    - Writes (`config.set`/`config.apply`/`config.patch`) preflight active SecretRef resolution for refs in the submitted config payload; unresolved active submitted refs are rejected before write.
-    - Form saves discard stale redacted placeholders that cannot be restored from the saved config while preserving redacted values that still map to saved secrets.
-    - Schema + form rendering (`config.schema` / `config.schema.lookup`, including field `title` / `description`, matched UI hints, immediate child summaries, docs metadata on nested object/wildcard/array/composition nodes, plus plugin + channel schemas when available); Raw JSON editor is available only when the snapshot has a safe raw round-trip.
-    - If a snapshot cannot safely round-trip raw text, Control UI forces Form mode and disables Raw mode for that snapshot.
-    - Raw JSON editor "Reset to saved" preserves the raw-authored shape (formatting, comments, `$include` layout) instead of re-rendering a flattened snapshot, so external edits survive a reset when the snapshot can safely round-trip.
-    - Structured SecretRef object values are rendered read-only in form text inputs to prevent accidental object-to-string corruption.
-
-  </Accordion>
-  <Accordion title="Debug, logs, update">
-    - Debug: status/health/models snapshots + event log + manual RPC calls (`status`, `health`, `models.list`).
-    - The event log includes Control UI refresh/RPC timings, slow chat/config render timings, and browser responsiveness entries for long animation frames or long tasks when the browser exposes those PerformanceObserver entry types.
-    - Logs: live tail of gateway file logs with filter/export (`logs.tail`).
-    - Update: run a package/git update + restart (`update.run`) with a restart report, then poll `update.status` after reconnect to verify the running gateway version.
-
-  </Accordion>
-  <Accordion title="Cron jobs panel notes">
-    - For isolated jobs, delivery defaults to announce summary. You can switch to none if you want internal-only runs.
-    - Channel/target fields appear when announce is selected.
-    - Webhook mode uses `delivery.mode = "webhook"` with `delivery.to` set to a valid HTTP(S) webhook URL.
-    - For main-session jobs, webhook and none delivery modes are available.
-    - Advanced edit controls include delete-after-run, clear agent override, cron exact/stagger options, agent model/thinking overrides, and best-effort delivery toggles.
-    - Form validation is inline with field-level errors; invalid values disable the save button until fixed.
-    - Set `cron.webhookToken` to send a dedicated bearer token, if omitted the webhook is sent without an auth header.
-    - Deprecated fallback: stored legacy jobs with `notify: true` can still use `cron.webhook` until migrated.
-
-  </Accordion>
-</AccordionGroup>
-
-## Activity tab
-
-The Activity tab is an ephemeral browser-local observer for live tool activity. It is derived from the same Gateway `session.tool` / tool event stream that powers Chat tool cards; it does not add another Gateway event family, endpoint, durable activity store, metrics feed, or external observer stream.
-
-Activity entries keep only sanitized summaries and redacted, truncated output previews. Tool argument values are not stored in Activity state; the UI shows that arguments are hidden and records only the argument field count. The in-memory list follows the current browser tab, survives navigation within the Control UI, and resets on page reload, session switch, or **Clear**.
-
-## Chat behavior
-
-<AccordionGroup>
-  <Accordion title="Send and history semantics">
-    - `chat.send` is **non-blocking**: it acks immediately with `{ runId, status: "started" }` and the response streams via `chat` events.
-    - Chat uploads accept images plus non-video files. Images keep the native image path; other files are stored as managed media and shown in history as attachment links.
-    - Re-sending with the same `idempotencyKey` returns `{ status: "in_flight" }` while running, and `{ status: "ok" }` after completion.
-    - `chat.history` responses are size-bounded for UI safety. When transcript entries are too large, Gateway may truncate long text fields, omit heavy metadata blocks, and replace oversized messages with a placeholder (`[chat.history omitted: message too large]`).
-    - Assistant/generated images are persisted as managed media references and served back through authenticated Gateway media URLs, so reloads do not depend on raw base64 image payloads staying in the chat history response.
-    - When rendering `chat.history`, the Control UI strips display-only inline directive tags from visible assistant text (for example `[[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, and omits assistant entries whose whole visible text is only the exact silent token `NO_REPLY` / `no_reply` or the heartbeat acknowledgement token `HEARTBEAT_OK`.
-    - During an active send and the final history refresh, the chat view keeps local optimistic user/assistant messages visible if `chat.history` briefly returns an older snapshot; the canonical transcript replaces those local messages once the Gateway history catches up.
-    - Live `chat` events are delivery state, while `chat.history` is rebuilt from the durable session transcript. After tool-final events the Control UI reloads history and merges only a small optimistic tail; the transcript boundary is documented in [WebChat](/web/webchat).
-    - `chat.inject` appends an assistant note to the session transcript and broadcasts a `chat` event for UI-only updates (no agent run, no channel delivery).
-    - The chat header shows the agent filter before the session picker, and the session picker is scoped by the selected agent. Switching agents shows only sessions tied to that agent and falls back to that agent's main session when it has no saved dashboard sessions yet.
-    - On desktop widths, chat controls stay on one compact row and collapse while scrolling down the transcript; scrolling up, returning to the top, or reaching the bottom restores the controls.
-    - Consecutive duplicate text-only messages render as one bubble with a count badge. Messages that carry images, attachments, tool output, or canvas previews are left uncollapsed.
-    - The chat header model and thinking pickers patch the active session immediately through `sessions.patch`; they are persistent session overrides, not one-turn-only send options.
-    - If you send a message while a model picker change for the same session is still saving, the composer waits for that session patch before calling `chat.send` so the send uses the selected model.
-    - Typing `/new` in the Control UI creates and switches to the same fresh dashboard session as New Chat, except when `session.dmScope: "main"` is configured and the current parent is the agent's main session; in that case it resets the main session in place. Typing `/reset` keeps the Gateway's explicit in-place reset for the current session.
-    - The chat model picker requests the Gateway's configured model view. If `agents.defaults.models` is present, that allowlist drives the picker, including `provider/*` entries that keep provider-scoped catalogs dynamic. Otherwise the picker shows explicit `models.providers.*.models` entries plus providers with usable auth. The full catalog stays available through the debug `models.list` RPC with `view: "all"`.
-    - When fresh Gateway session usage reports include current context tokens, the chat composer area shows a compact context usage indicator. It switches to warning styling at high context pressure and, at recommended compaction levels, shows a compact button that runs the normal session compaction path. Stale token snapshots are hidden until the Gateway reports fresh usage again.
-
-  </Accordion>
-  <Accordion title="Talk mode (browser realtime)">
-    Talk mode uses a registered realtime voice provider. Configure OpenAI with `talk.realtime.provider: "openai"` plus either `talk.realtime.providers.openai.apiKey`, `OPENAI_API_KEY`, or an `openai` OAuth profile; configure Google with `talk.realtime.provider: "google"` plus `talk.realtime.providers.google.apiKey`. For hosted GPT realtime models, FengMing prefers the `openai` OAuth profile before `OPENAI_API_KEY`; an explicit OpenAI realtime `apiKey` remains the advanced override. The browser never receives a standard provider API key. OpenAI receives an ephemeral Realtime client secret for WebRTC. Google Live receives a one-use constrained Live API auth token for a browser WebSocket session, with instructions and tool declarations locked into the token by the Gateway. Providers that only expose a backend realtime bridge run through the Gateway relay transport, so credentials and vendor sockets stay server-side while browser audio moves through authenticated Gateway RPCs. The Realtime session prompt is assembled by the Gateway; `talk.client.create` does not accept caller-provided instruction overrides.
-
-    The Chat composer includes a Talk options button next to the Talk start/stop button. The options apply to the next Talk session and can override provider, transport, model, voice, reasoning effort, VAD threshold, silence duration, and prefix padding. When an option is blank, the Gateway uses configured defaults where available or the provider default. Selecting Gateway relay forces the backend relay path; selecting WebRTC keeps the session client-owned and fails instead of silently falling back to relay if the provider cannot create a browser session.
-
-    In the Chat composer, the Talk control is the waves button next to the microphone dictation button. When Talk starts, the composer status row shows `Connecting Talk...`, then `Talk live` while audio is connected, or `Asking FengMing...` while a realtime tool call is consulting the configured larger model through `talk.client.toolCall`.
-
-    Maintainer live smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifies the OpenAI backend WebSocket bridge, OpenAI browser WebRTC SDP exchange, Google Live constrained-token browser WebSocket setup, and the Gateway relay browser adapter with fake microphone media. The command prints provider status only and does not log secrets.
-
-  </Accordion>
-  <Accordion title="Stop and abort">
-    - Click **Stop** (calls `chat.abort`).
-    - While a run is active, normal follow-ups queue. Click **Steer** on a queued message to inject that follow-up into the running turn.
-    - Type `/stop` (or standalone abort phrases like `stop`, `stop action`, `stop run`, `stop fengming`, `please stop`) to abort out-of-band.
-    - `chat.abort` supports `{ sessionKey }` (no `runId`) to abort all active runs for that session.
-
-  </Accordion>
-  <Accordion title="Abort partial retention">
-    - When a run is aborted, partial assistant text can still be shown in the UI.
-    - Gateway persists aborted partial assistant text into transcript history when buffered output exists.
-    - Persisted entries include abort metadata so transcript consumers can tell abort partials from normal completion output.
-
-  </Accordion>
-</AccordionGroup>
-
-## PWA install and web push
-
-The Control UI ships a `manifest.webmanifest` and a service worker, so modern browsers can install it as a standalone PWA. Web Push lets the Gateway wake the installed PWA with notifications even when the tab or browser window is not open.
-
-If the page shows **Protocol mismatch** right after an FengMing update, first reopen the dashboard with `fengming dashboard` and hard-refresh the page. If it still fails, clear site data for the dashboard origin or test in a private browser window; an old tab or browser service-worker cache can keep running a pre-update Control UI bundle against the newer Gateway.
-
-| Surface                                               | What it does                                                       |
-| ----------------------------------------------------- | ------------------------------------------------------------------ |
-| `ui/public/manifest.webmanifest`                      | PWA manifest. Browsers offer "Install app" once it is reachable.   |
-| `ui/public/sw.js`                                     | Service worker that handles `push` events and notification clicks. |
-| `push/vapid-keys.json` (under the FengMing state dir) | Auto-generated VAPID keypair used to sign Web Push payloads.       |
-| `push/web-push-subscriptions.json`                    | Persisted browser subscription endpoints.                          |
-
-Override the VAPID keypair through env vars on the Gateway process when you want to pin keys (for multi-host deployments, secrets rotation, or tests):
-
-- `FENGMING_VAPID_PUBLIC_KEY`
-- `FENGMING_VAPID_PRIVATE_KEY`
-- `FENGMING_VAPID_SUBJECT` (defaults to `https://fengming.ai`)
-
-The Control UI uses these scope-gated Gateway methods to register and test browser subscriptions:
-
-- `push.web.vapidPublicKey` — fetches the active VAPID public key.
-- `push.web.subscribe` — registers an `endpoint` plus `keys.p256dh`/`keys.auth`.
-- `push.web.unsubscribe` — removes a registered endpoint.
-- `push.web.test` — sends a test notification to the caller's subscription.
-
-<Note>
-Web Push is independent of the iOS APNS relay path (see [Configuration](/gateway/configuration) for relay-backed push) and the existing `push.test` method, which target native mobile pairing.
-</Note>
-
-## Hosted embeds
-
-Assistant messages can render hosted web content inline with the `[embed ...]` shortcode. The iframe sandbox policy is controlled by `gateway.controlUi.embedSandbox`:
-
-<Tabs>
-  <Tab title="strict">
-    Disables script execution inside hosted embeds.
-  </Tab>
-  <Tab title="scripts (default)">
-    Allows interactive embeds while keeping origin isolation; this is the default and is usually enough for self-contained browser games/widgets.
-  </Tab>
-  <Tab title="trusted">
-    Adds `allow-same-origin` on top of `allow-scripts` for same-site documents that intentionally need stronger privileges.
-  </Tab>
-</Tabs>
-
-Example:
-
-```json5
-{
-  gateway: {
-    controlUi: {
-      embedSandbox: "scripts",
-    },
-  },
-}
-```
-
-<Warning>
-Use `trusted` only when the embedded document genuinely needs same-origin behavior. For most agent-generated games and interactive canvases, `scripts` is the safer choice.
-</Warning>
-
-Absolute external `http(s)` embed URLs stay blocked by default. If you intentionally want `[embed url="https://..."]` to load third-party pages, set `gateway.controlUi.allowExternalEmbedUrls: true`.
-
-## Chat message width
-
-Grouped chat messages use a readable default max-width. Wide-monitor deployments can override it without patching bundled CSS by setting `gateway.controlUi.chatMessageMaxWidth`:
-
-```json5
-{
-  gateway: {
-    controlUi: {
-      chatMessageMaxWidth: "min(1280px, 82%)",
-    },
-  },
-}
-```
-
-The value is validated before it reaches the browser. Supported values include plain lengths and percentages such as `960px` or `82%`, plus constrained `min(...)`, `max(...)`, `clamp(...)`, `calc(...)`, and `fit-content(...)` width expressions.
-
-## Tailnet access (recommended)
-
-<Tabs>
-  <Tab title="Integrated Tailscale Serve (preferred)">
-    Keep the Gateway on loopback and let Tailscale Serve proxy it with HTTPS:
-
-    ```bash
-    fengming gateway --tailscale serve
-    ```
-
-    Open:
-
-    - `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
-
-    By default, Control UI/WebSocket Serve requests can authenticate via Tailscale identity headers (`tailscale-user-login`) when `gateway.auth.allowTailscale` is `true`. FengMing verifies the identity by resolving the `x-forwarded-for` address with `tailscale whois` and matching it to the header, and only accepts these when the request hits loopback with Tailscale's `x-forwarded-*` headers. For Control UI operator sessions with browser device identity, this verified Serve path also skips the device-pairing round trip; device-less browsers and node-role connections still follow the normal device checks. Set `gateway.auth.allowTailscale: false` if you want to require explicit shared-secret credentials even for Serve traffic. Then use `gateway.auth.mode: "token"` or `"password"`.
-
-    For that async Serve identity path, failed auth attempts for the same client IP and auth scope are serialized before rate-limit writes. Concurrent bad retries from the same browser can therefore show `retry later` on the second request instead of two plain mismatches racing in parallel.
-
-    <Warning>
-    Tokenless Serve auth assumes the gateway host is trusted. If untrusted local code may run on that host, require token/password auth.
-    </Warning>
-
-  </Tab>
-  <Tab title="Bind to tailnet + token">
-    ```bash
-    fengming gateway --bind tailnet --token "$(openssl rand -hex 32)"
-    ```
-
-    Then open:
-
-    - `http://<tailscale-ip>:18789/` (or your configured `gateway.controlUi.basePath`)
-
-    Paste the matching shared secret into the UI settings (sent as `connect.params.auth.token` or `connect.params.auth.password`).
-
-  </Tab>
-</Tabs>
-
-## Insecure HTTP
-
-If you open the dashboard over plain HTTP (`http://<lan-ip>` or `http://<tailscale-ip>`), the browser runs in a **non-secure context** and blocks WebCrypto. By default, FengMing **blocks** Control UI connections without device identity.
-
-Documented exceptions:
-
-- localhost-only insecure HTTP compatibility with `gateway.controlUi.allowInsecureAuth=true`
-- successful operator Control UI auth through `gateway.auth.mode: "trusted-proxy"`
-- break-glass `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
-
-**Recommended fix:** use HTTPS (Tailscale Serve) or open the UI locally:
-
-- `https://<magicdns>/` (Serve)
-- `http://127.0.0.1:18789/` (on the gateway host)
-
-<AccordionGroup>
-  <Accordion title="Insecure-auth toggle behavior">
-    ```json5
-    {
-      gateway: {
-        controlUi: { allowInsecureAuth: true },
-        bind: "tailnet",
-        auth: { mode: "token", token: "replace-me" },
-      },
-    }
-    ```
-
-    `allowInsecureAuth` is a local compatibility toggle only:
-
-    - It allows localhost Control UI sessions to proceed without device identity in non-secure HTTP contexts.
-    - It does not bypass pairing checks.
-    - It does not relax remote (non-localhost) device identity requirements.
-
-  </Accordion>
-  <Accordion title="Break-glass only">
-    ```json5
-    {
-      gateway: {
-        controlUi: { dangerouslyDisableDeviceAuth: true },
-        bind: "tailnet",
-        auth: { mode: "token", token: "replace-me" },
-      },
-    }
-    ```
-
-    <Warning>
-    `dangerouslyDisableDeviceAuth` disables Control UI device identity checks and is a severe security downgrade. Revert quickly after emergency use.
-    </Warning>
-
-  </Accordion>
-  <Accordion title="Trusted-proxy note">
-    - Successful trusted-proxy auth can admit **operator** Control UI sessions without device identity.
-    - This does **not** extend to node-role Control UI sessions.
-    - Same-host loopback reverse proxies still do not satisfy trusted-proxy auth; see [Trusted proxy auth](/gateway/trusted-proxy-auth).
-
-  </Accordion>
-</AccordionGroup>
-
-See [Tailscale](/gateway/tailscale) for HTTPS setup guidance.
-
-## Content security policy
-
-The Control UI ships with a tight `img-src` policy: only **same-origin** assets, `data:` URLs, and locally generated `blob:` URLs are allowed. Remote `http(s)` and protocol-relative image URLs are rejected by the browser and do not issue network fetches.
-
-What this means in practice:
-
-- Avatars and images served under relative paths (for example `/avatars/<id>`) still render, including authenticated avatar routes that the UI fetches and converts into local `blob:` URLs.
-- Inline `data:image/...` URLs still render (useful for in-protocol payloads).
-- Local `blob:` URLs created by the Control UI still render.
-- Remote avatar URLs emitted by channel metadata are stripped at the Control UI's avatar helpers and replaced with the built-in logo/badge, so a compromised or malicious channel cannot force arbitrary remote image fetches from an operator browser.
-
-You do not need to change anything to get this behavior — it is always on and not configurable.
-
-## Avatar route auth
-
-When gateway auth is configured, the Control UI avatar endpoint requires the same gateway token as the rest of the API:
-
-- `GET /avatar/<agentId>` returns the avatar image only to authenticated callers. `GET /avatar/<agentId>?meta=1` returns the avatar metadata under the same rule.
-- Unauthenticated requests to either route are rejected (matching the sibling assistant-media route). This prevents the avatar route from leaking agent identity on hosts that are otherwise protected.
-- The Control UI itself forwards the gateway token as a bearer header when fetching avatars, and uses authenticated blob URLs so the image still renders in dashboards.
-
-If you disable gateway auth (not recommended on shared hosts), the avatar route also becomes unauthenticated, in line with the rest of the gateway.
-
-## Assistant media route auth
-
-When gateway auth is configured, assistant local-media previews use a two-step route:
-
-- `GET /__fengming__/assistant-media?meta=1&source=<path>` requires the normal Control UI operator auth. The browser sends the gateway token as a bearer header when checking availability.
-- Successful metadata responses include a short-lived `mediaTicket` scoped to that exact source path.
-- Browser-rendered image, audio, video, and document URLs use `mediaTicket=<ticket>` instead of the active gateway token or password. The ticket expires quickly and cannot authorize a different source.
-
-This keeps normal media rendering compatible with browser-native media elements without putting reusable gateway credentials in visible media URLs.
-
-## Building the UI
-
-The Gateway serves static files from `dist/control-ui`. Build them with:
-
-```bash
-pnpm ui:build
-```
-
-Optional absolute base (when you want fixed asset URLs):
-
-```bash
-FENGMING_CONTROL_UI_BASE_PATH=/fengming/ pnpm ui:build
-```
-
-For local development (separate dev server):
-
-```bash
-pnpm ui:dev
-```
-
-Then point the UI at your Gateway WS URL (e.g. `ws://127.0.0.1:18789`).
-
-## Blank Control UI page
-
-If the browser loads a blank dashboard and DevTools shows no useful error, an extension or early content script may have prevented the JavaScript module app from evaluating. The static page includes a plain HTML recovery panel that appears when `<fengming-app>` is not registered after startup.
-
-Use the panel's **Try again** action after changing the browser environment, or reload manually after these checks:
-
-- Disable extensions that inject into all pages, especially extensions with `<all_urls>` content scripts.
-- Try a private window, a clean browser profile, or another browser.
-- Keep the Gateway running and verify the same dashboard URL after the browser change.
-
-## Debugging/testing: dev server + remote Gateway
-
-The Control UI is static files; the WebSocket target is configurable and can be different from the HTTP origin. This is handy when you want the Vite dev server locally but the Gateway runs elsewhere.
-
-<Steps>
-  <Step title="Start the UI dev server">
-    ```bash
-    pnpm ui:dev
-    ```
-  </Step>
-  <Step title="Open with gatewayUrl">
-    ```text
-    http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
-    ```
-
-    Optional one-time auth (if needed):
-
-    ```text
-    http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
-    ```
-
-  </Step>
-</Steps>
-
-<AccordionGroup>
-  <Accordion title="Notes">
-    - `gatewayUrl` is stored in localStorage after load and removed from the URL.
-    - If you pass a full `ws://` or `wss://` endpoint via `gatewayUrl`, URL-encode the `gatewayUrl` value so the browser parses the query string correctly.
-    - `token` should be passed via the URL fragment (`#token=...`) whenever possible. Fragments are not sent to the server, which avoids request-log and Referer leakage. Legacy `?token=` query params are still imported once for compatibility, but only as a fallback, and are stripped immediately after bootstrap.
-    - `password` is kept in memory only.
-    - When `gatewayUrl` is set, the UI does not fall back to config or environment credentials. Provide `token` (or `password`) explicitly. Missing explicit credentials is an error.
-    - Use `wss://` when the Gateway is behind TLS (Tailscale Serve, HTTPS proxy, etc.).
-    - `gatewayUrl` is only accepted in a top-level window (not embedded) to prevent clickjacking.
-    - Public non-loopback Control UI deployments must set `gateway.controlUi.allowedOrigins` explicitly (full origins). Private same-origin LAN/Tailnet loads from loopback, RFC1918/link-local, `.local`, `.ts.net`, or Tailscale CGNAT hosts are accepted without enabling Host-header fallback.
-    - Gateway startup may seed local origins such as `http://localhost:<port>` and `http://127.0.0.1:<port>` from the effective runtime bind and port, but remote browser origins still need explicit entries.
-    - Do not use `gateway.controlUi.allowedOrigins: ["*"]` except for tightly controlled local testing. It means allow any browser origin, not "match whatever host I am using."
-    - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` enables Host-header origin fallback mode, but it is a dangerous security mode.
-
-  </Accordion>
-</AccordionGroup>
-
-Example:
-
-```json5
-{
-  gateway: {
-    controlUi: {
-      allowedOrigins: ["http://localhost:5173"],
-    },
-  },
-}
-```
-
-Remote access setup details: [Remote access](/gateway/remote).
-
-## Related
-
-- [Dashboard](/web/dashboard) — gateway dashboard
-- [Health Checks](/gateway/health) — gateway health monitoring
-- [TUI](/web/tui) — terminal user interface
-- [WebChat](/web/webchat) — browser-based chat interface