synurex 2026.2.19-1

package/docs/tts.md

@@ -0,0 +1,396 @@
+---
+summary: "Text-to-speech (TTS) for outbound replies"
+read_when:
+  - Enabling text-to-speech for replies
+  - Configuring TTS providers or limits
+  - Using /tts commands
+title: "Text-to-Speech"
+---
+
+# Text-to-speech (TTS)
+
+Synurex can convert outbound replies into audio using ElevenLabs, OpenAI, or Edge TTS.
+It works anywhere Synurex can send audio; Telegram gets a round voice-note bubble.
+
+## Supported services
+
+- **ElevenLabs** (primary or fallback provider)
+- **OpenAI** (primary or fallback provider; also used for summaries)
+- **Edge TTS** (primary or fallback provider; uses `node-edge-tts`, default when no API keys)
+
+### Edge TTS notes
+
+Edge TTS uses Microsoft Edge's online neural TTS service via the `node-edge-tts`
+library. It's a hosted service (not local), uses Microsoft’s endpoints, and does
+not require an API key. `node-edge-tts` exposes speech configuration options and
+output formats, but not all options are supported by the Edge service. citeturn2search0
+
+Because Edge TTS is a public web service without a published SLA or quota, treat it
+as best-effort. If you need guaranteed limits and support, use OpenAI or ElevenLabs.
+Microsoft's Speech REST API documents a 10‑minute audio limit per request; Edge TTS
+does not publish limits, so assume similar or lower limits. citeturn0search3
+
+## Optional keys
+
+If you want OpenAI or ElevenLabs:
+
+- `ELEVENLABS_API_KEY` (or `XI_API_KEY`)
+- `OPENAI_API_KEY`
+
+Edge TTS does **not** require an API key. If no API keys are found, Synurex defaults
+to Edge TTS (unless disabled via `messages.tts.edge.enabled=false`).
+
+If multiple providers are configured, the selected provider is used first and the others are fallback options.
+Auto-summary uses the configured `summaryModel` (or `agents.defaults.model.primary`),
+so that provider must also be authenticated if you enable summaries.
+
+## Service links
+
+- [OpenAI Text-to-Speech guide](https://platform.openai.com/docs/guides/text-to-speech)
+- [OpenAI Audio API reference](https://platform.openai.com/docs/api-reference/audio)
+- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech)
+- [ElevenLabs Authentication](https://elevenlabs.io/docs/api-reference/authentication)
+- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)
+- [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
+
+## Is it enabled by default?
+
+No. Auto‑TTS is **off** by default. Enable it in config with
+`messages.tts.auto` or per session with `/tts always` (alias: `/tts on`).
+
+Edge TTS **is** enabled by default once TTS is on, and is used automatically
+when no OpenAI or ElevenLabs API keys are available.
+
+## Config
+
+TTS config lives under `messages.tts` in `synurex.json`.
+Full schema is in [Gateway configuration](/gateway/configuration).
+
+### Minimal config (enable + provider)
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "elevenlabs",
+    },
+  },
+}
+```
+
+### OpenAI primary with ElevenLabs fallback
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "openai",
+      summaryModel: "openai/gpt-4.1-mini",
+      modelOverrides: {
+        enabled: true,
+      },
+      openai: {
+        apiKey: "openai_api_key",
+        model: "gpt-4o-mini-tts",
+        voice: "alloy",
+      },
+      elevenlabs: {
+        apiKey: "elevenlabs_api_key",
+        baseUrl: "https://api.elevenlabs.io",
+        voiceId: "voice_id",
+        modelId: "eleven_multilingual_v2",
+        seed: 42,
+        applyTextNormalization: "auto",
+        languageCode: "en",
+        voiceSettings: {
+          stability: 0.5,
+          similarityBoost: 0.75,
+          style: 0.0,
+          useSpeakerBoost: true,
+          speed: 1.0,
+        },
+      },
+    },
+  },
+}
+```
+
+### Edge TTS primary (no API key)
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "edge",
+      edge: {
+        enabled: true,
+        voice: "en-US-MichelleNeural",
+        lang: "en-US",
+        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
+        rate: "+10%",
+        pitch: "-5%",
+      },
+    },
+  },
+}
+```
+
+### Disable Edge TTS
+
+```json5
+{
+  messages: {
+    tts: {
+      edge: {
+        enabled: false,
+      },
+    },
+  },
+}
+```
+
+### Custom limits + prefs path
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      maxTextLength: 4000,
+      timeoutMs: 30000,
+      prefsPath: "~/.synurex/settings/tts.json",
+    },
+  },
+}
+```
+
+### Only reply with audio after an inbound voice note
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "inbound",
+    },
+  },
+}
+```
+
+### Disable auto-summary for long replies
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+    },
+  },
+}
+```
+
+Then run:
+
+```
+/tts summary off
+```
+
+### Notes on fields
+
+- `auto`: auto‑TTS mode (`off`, `always`, `inbound`, `tagged`).
+  - `inbound` only sends audio after an inbound voice note.
+  - `tagged` only sends audio when the reply includes `[[tts]]` tags.
+- `enabled`: legacy toggle (doctor migrates this to `auto`).
+- `mode`: `"final"` (default) or `"all"` (includes tool/block replies).
+- `provider`: `"elevenlabs"`, `"openai"`, or `"edge"` (fallback is automatic).
+- If `provider` is **unset**, Synurex prefers `openai` (if key), then `elevenlabs` (if key),
+  otherwise `edge`.
+- `summaryModel`: optional cheap model for auto-summary; defaults to `agents.defaults.model.primary`.
+  - Accepts `provider/model` or a configured model alias.
+- `modelOverrides`: allow the model to emit TTS directives (on by default).
+- `maxTextLength`: hard cap for TTS input (chars). `/tts audio` fails if exceeded.
+- `timeoutMs`: request timeout (ms).
+- `prefsPath`: override the local prefs JSON path (provider/limit/summary).
+- `apiKey` values fall back to env vars (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `OPENAI_API_KEY`).
+- `elevenlabs.baseUrl`: override ElevenLabs API base URL.
+- `elevenlabs.voiceSettings`:
+  - `stability`, `similarityBoost`, `style`: `0..1`
+  - `useSpeakerBoost`: `true|false`
+  - `speed`: `0.5..2.0` (1.0 = normal)
+- `elevenlabs.applyTextNormalization`: `auto|on|off`
+- `elevenlabs.languageCode`: 2-letter ISO 639-1 (e.g. `en`, `de`)
+- `elevenlabs.seed`: integer `0..4294967295` (best-effort determinism)
+- `edge.enabled`: allow Edge TTS usage (default `true`; no API key).
+- `edge.voice`: Edge neural voice name (e.g. `en-US-MichelleNeural`).
+- `edge.lang`: language code (e.g. `en-US`).
+- `edge.outputFormat`: Edge output format (e.g. `audio-24khz-48kbitrate-mono-mp3`).
+  - See Microsoft Speech output formats for valid values; not all formats are supported by Edge.
+- `edge.rate` / `edge.pitch` / `edge.volume`: percent strings (e.g. `+10%`, `-5%`).
+- `edge.saveSubtitles`: write JSON subtitles alongside the audio file.
+- `edge.proxy`: proxy URL for Edge TTS requests.
+- `edge.timeoutMs`: request timeout override (ms).
+
+## Model-driven overrides (default on)
+
+By default, the model **can** emit TTS directives for a single reply.
+When `messages.tts.auto` is `tagged`, these directives are required to trigger audio.
+
+When enabled, the model can emit `[[tts:...]]` directives to override the voice
+for a single reply, plus an optional `[[tts:text]]...[[/tts:text]]` block to
+provide expressive tags (laughter, singing cues, etc) that should only appear in
+the audio.
+
+Example reply payload:
+
+```
+Here you go.
+
+[[tts:provider=elevenlabs voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
+[[tts:text]](laughs) Read the song once more.[[/tts:text]]
+```
+
+Available directive keys (when enabled):
+
+- `provider` (`openai` | `elevenlabs` | `edge`)
+- `voice` (OpenAI voice) or `voiceId` (ElevenLabs)
+- `model` (OpenAI TTS model or ElevenLabs model id)
+- `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`
+- `applyTextNormalization` (`auto|on|off`)
+- `languageCode` (ISO 639-1)
+- `seed`
+
+Disable all model overrides:
+
+```json5
+{
+  messages: {
+    tts: {
+      modelOverrides: {
+        enabled: false,
+      },
+    },
+  },
+}
+```
+
+Optional allowlist (disable specific overrides while keeping tags enabled):
+
+```json5
+{
+  messages: {
+    tts: {
+      modelOverrides: {
+        enabled: true,
+        allowProvider: false,
+        allowSeed: false,
+      },
+    },
+  },
+}
+```
+
+## Per-user preferences
+
+Slash commands write local overrides to `prefsPath` (default:
+`~/.synurex/settings/tts.json`, override with `SYNUREX_TTS_PREFS` or
+`messages.tts.prefsPath`).
+
+Stored fields:
+
+- `enabled`
+- `provider`
+- `maxLength` (summary threshold; default 1500 chars)
+- `summarize` (default `true`)
+
+These override `messages.tts.*` for that host.
+
+## Output formats (fixed)
+
+- **Telegram**: Opus voice note (`opus_48000_64` from ElevenLabs, `opus` from OpenAI).
+  - 48kHz / 64kbps is a good voice-note tradeoff and required for the round bubble.
+- **Other channels**: MP3 (`mp3_44100_128` from ElevenLabs, `mp3` from OpenAI).
+  - 44.1kHz / 128kbps is the default balance for speech clarity.
+- **Edge TTS**: uses `edge.outputFormat` (default `audio-24khz-48kbitrate-mono-mp3`).
+  - `node-edge-tts` accepts an `outputFormat`, but not all formats are available
+    from the Edge service. citeturn2search0
+  - Output format values follow Microsoft Speech output formats (including Ogg/WebM Opus). citeturn1search0
+  - Telegram `sendVoice` accepts OGG/MP3/M4A; use OpenAI/ElevenLabs if you need
+    guaranteed Opus voice notes. citeturn1search1
+  - If the configured Edge output format fails, Synurex retries with MP3.
+
+OpenAI/ElevenLabs formats are fixed; Telegram expects Opus for voice-note UX.
+
+## Auto-TTS behavior
+
+When enabled, Synurex:
+
+- skips TTS if the reply already contains media or a `MEDIA:` directive.
+- skips very short replies (< 10 chars).
+- summarizes long replies when enabled using `agents.defaults.model.primary` (or `summaryModel`).
+- attaches the generated audio to the reply.
+
+If the reply exceeds `maxLength` and summary is off (or no API key for the
+summary model), audio
+is skipped and the normal text reply is sent.
+
+## Flow diagram
+
+```
+Reply -> TTS enabled?
+  no  -> send text
+  yes -> has media / MEDIA: / short?
+          yes -> send text
+          no  -> length > limit?
+                   no  -> TTS -> attach audio
+                   yes -> summary enabled?
+                            no  -> send text
+                            yes -> summarize (summaryModel or agents.defaults.model.primary)
+                                      -> TTS -> attach audio
+```
+
+## Slash command usage
+
+There is a single command: `/tts`.
+See [Slash commands](/tools/slash-commands) for enablement details.
+
+Discord note: `/tts` is a built-in Discord command, so Synurex registers
+`/voice` as the native command there. Text `/tts ...` still works.
+
+```
+/tts off
+/tts always
+/tts inbound
+/tts tagged
+/tts status
+/tts provider openai
+/tts limit 2000
+/tts summary off
+/tts audio Hello from Synurex
+```
+
+Notes:
+
+- Commands require an authorized sender (allowlist/owner rules still apply).
+- `commands.text` or native command registration must be enabled.
+- `off|always|inbound|tagged` are per‑session toggles (`/tts on` is an alias for `/tts always`).
+- `limit` and `summary` are stored in local prefs, not the main config.
+- `/tts audio` generates a one-off audio reply (does not toggle TTS on).
+
+## Agent tool
+
+The `tts` tool converts text to speech and returns a `MEDIA:` path. When the
+result is Telegram-compatible, the tool includes `[[audio_as_voice]]` so
+Telegram sends a voice bubble.
+
+## Gateway RPC
+
+Gateway methods:
+
+- `tts.status`
+- `tts.enable`
+- `tts.disable`
+- `tts.convert`
+- `tts.setProvider`
+- `tts.providers`

package/docs/vps.md

@@ -0,0 +1,43 @@
+---
+summary: "VPS hosting hub for Synurex (Oracle/Fly/Hetzner/GCP/exe.dev)"
+read_when:
+  - You want to run the Gateway in the cloud
+  - You need a quick map of VPS/hosting guides
+title: "VPS Hosting"
+---
+
+# VPS hosting
+
+This hub links to the supported VPS/hosting guides and explains how cloud
+deployments work at a high level.
+
+## Pick a provider
+
+- **Railway** (one‑click + browser setup): [Railway](/install/railway)
+- **Northflank** (one‑click + browser setup): [Northflank](/install/northflank)
+- **Oracle Cloud (Always Free)**: [Oracle](/platforms/oracle) — $0/month (Always Free, ARM; capacity/signup can be finicky)
+- **Fly.io**: [Fly.io](/install/fly)
+- **Hetzner (Docker)**: [Hetzner](/install/hetzner)
+- **GCP (Compute Engine)**: [GCP](/install/gcp)
+- **exe.dev** (VM + HTTPS proxy): [exe.dev](/install/exe-dev)
+- **AWS (EC2/Lightsail/free tier)**: works well too. Video guide:
+  [https://x.com/techfrenAJ/status/2014934471095812547](https://x.com/techfrenAJ/status/2014934471095812547)
+
+## How cloud setups work
+
+- The **Gateway runs on the VPS** and owns state + workspace.
+- You connect from your laptop/phone via the **Control UI** or **Tailscale/SSH**.
+- Treat the VPS as the source of truth and **back up** the state + workspace.
+- Secure default: keep the Gateway on loopback and access it via SSH tunnel or Tailscale Serve.
+  If you bind to `lan`/`tailnet`, require `gateway.auth.token` or `gateway.auth.password`.
+
+Remote access: [Gateway remote](/gateway/remote)  
+Platforms hub: [Platforms](/platforms)
+
+## 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)

package/docs/web/control-ui.md

@@ -0,0 +1,223 @@
+---
+summary: "Browser-based control UI for the Gateway (chat, nodes, config)"
+read_when:
+  - You want to operate the Gateway from a browser
+  - You want Tailnet access without SSH tunnels
+title: "Control UI"
+---
+
+# Control UI (browser)
+
+The Control UI is a small **Vite + Lit** single-page app served by the Gateway:
+
+- default: `http://<host>:18789/`
+- optional prefix: set `gateway.controlUi.basePath` (e.g. `/Synurex`)
+
+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: `Synurex gateway`.
+
+Auth is supplied during the WebSocket handshake via:
+
+- `connect.params.auth.token`
+- `connect.params.auth.password`
+  The dashboard settings panel lets you store a token; passwords are not persisted.
+  The onboarding wizard generates a gateway token by default, so paste it here on first connect.
+
+## Device pairing (first connection)
+
+When you connect to the Control UI from a new browser or device, the Gateway
+requires a **one-time pairing approval** — even if you're on the same Tailnet
+with `gateway.auth.allowTailscale: true`. This is a security measure to prevent
+unauthorized access.
+
+**What you'll see:** "disconnected (1008): pairing required"
+
+**To approve the device:**
+
+```bash
+# List pending requests
+Synurex devices list
+
+# Approve by request ID
+Synurex devices approve <requestId>
+```
+
+Once approved, the device is remembered and won't require re-approval unless
+you revoke it with `Synurex devices revoke --device <id> --role <role>`. See
+[Devices CLI](/cli/devices) for token rotation and revocation.
+
+**Notes:**
+
+- Local connections (`127.0.0.1`) are auto-approved.
+- Remote connections (LAN, Tailnet, etc.) require explicit approval.
+- Each browser profile generates a unique device ID, so switching browsers or
+  clearing browser data will require re-pairing.
+
+## What it can do (today)
+
+- Chat with the model via Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`)
+- Stream tool calls + live tool output cards in Chat (agent events)
+- Channels: WhatsApp/Telegram/Discord/Slack + plugin channels (Mattermost, etc.) status + QR login + per-channel config (`channels.status`, `web.login.*`, `config.patch`)
+- Instances: presence list + refresh (`system-presence`)
+- Sessions: list + per-session thinking/verbose overrides (`sessions.list`, `sessions.patch`)
+- Cron jobs: list/add/run/enable/disable + run history (`cron.*`)
+- Skills: status, enable/disable, install, API key updates (`skills.*`)
+- Nodes: list + caps (`node.list`)
+- Exec approvals: edit gateway or node allowlists + ask policy for `exec host=gateway/node` (`exec.approvals.*`)
+- Config: view/edit `~/.synurex/synurex.json` (`config.get`, `config.set`)
+- Config: apply + restart with validation (`config.apply`) and wake the last active session
+- Config writes include a base-hash guard to prevent clobbering concurrent edits
+- Config schema + form rendering (`config.schema`, including plugin + channel schemas); Raw JSON editor remains available
+- Debug: status/health/models snapshots + event log + manual RPC calls (`status`, `health`, `models.list`)
+- 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
+
+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.
+
+## Chat behavior
+
+- `chat.send` is **non-blocking**: it acks immediately with `{ runId, status: "started" }` and the response streams via `chat` events.
+- Re-sending with the same `idempotencyKey` returns `{ status: "in_flight" }` while running, and `{ status: "ok" }` after completion.
+- `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).
+- Stop:
+  - Click **Stop** (calls `chat.abort`)
+  - Type `/stop` (or `stop|esc|abort|wait|exit|interrupt`) to abort out-of-band
+  - `chat.abort` supports `{ sessionKey }` (no `runId`) to abort all active runs for that session
+
+## Tailnet access (recommended)
+
+### Integrated Tailscale Serve (preferred)
+
+Keep the Gateway on loopback and let Tailscale Serve proxy it with HTTPS:
+
+```bash
+Synurex gateway --tailscale serve
+```
+
+Open:
+
+- `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
+
+By default, Serve requests can authenticate via Tailscale identity headers
+(`tailscale-user-login`) when `gateway.auth.allowTailscale` is `true`. Synurex
+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. Set
+`gateway.auth.allowTailscale: false` (or force `gateway.auth.mode: "password"`)
+if you want to require a token/password even for Serve traffic.
+
+### Bind to tailnet + token
+
+```bash
+Synurex gateway --bind tailnet --token "$(openssl rand -hex 32)"
+```
+
+Then open:
+
+- `http://<tailscale-ip>:18789/` (or your configured `gateway.controlUi.basePath`)
+
+Paste the token into the UI settings (sent as `connect.params.auth.token`).
+
+## 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,
+Synurex **blocks** Control UI connections without device identity.
+
+**Recommended fix:** use HTTPS (Tailscale Serve) or open the UI locally:
+
+- `https://<magicdns>/` (Serve)
+- `http://127.0.0.1:18789/` (on the gateway host)
+
+**Downgrade example (token-only over HTTP):**
+
+```json5
+{
+  gateway: {
+    controlUi: { allowInsecureAuth: true },
+    bind: "tailnet",
+    auth: { mode: "token", token: "replace-me" },
+  },
+}
+```
+
+This disables device identity + pairing for the Control UI (even on HTTPS). Use
+only if you trust the network.
+
+See [Tailscale](/gateway/tailscale) for HTTPS setup guidance.
+
+## Building the UI
+
+The Gateway serves static files from `dist/control-ui`. Build them with:
+
+```bash
+pnpm ui:build # auto-installs UI deps on first run
+```
+
+Optional absolute base (when you want fixed asset URLs):
+
+```bash
+SYNUREX_CONTROL_UI_BASE_PATH=/Synurex/ pnpm ui:build
+```
+
+For local development (separate dev server):
+
+```bash
+pnpm ui:dev # auto-installs UI deps on first run
+```
+
+Then point the UI at your Gateway WS URL (e.g. `ws://127.0.0.1:18789`).
+
+## 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.
+
+1. Start the UI dev server: `pnpm ui:dev`
+2. Open a URL like:
+
+```text
+http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789
+```
+
+Optional one-time auth (if needed):
+
+```text
+http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789&token=<gateway-token>
+```
+
+Notes:
+
+- `gatewayUrl` is stored in localStorage after load and removed from the URL.
+- `token` is stored in localStorage; `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.
+- For cross-origin dev setups (e.g. `pnpm ui:dev` to a remote Gateway), add the UI
+  origin to `gateway.controlUi.allowedOrigins`.
+
+Example:
+
+```json5
+{
+  gateway: {
+    controlUi: {
+      allowedOrigins: ["http://localhost:5173"],
+    },
+  },
+}
+```
+
+Remote access setup details: [Remote access](/gateway/remote).

package/docs/web/dashboard.md

@@ -0,0 +1,46 @@
+---
+summary: "Gateway dashboard (Control UI) access and auth"
+read_when:
+  - Changing dashboard authentication or exposure modes
+title: "Dashboard"
+---
+
+# Dashboard (Control UI)
+
+The Gateway dashboard is the browser Control UI served at `/` by default
+(override with `gateway.controlUi.basePath`).
+
+Quick open (local Gateway):
+
+- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/))
+
+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 `connect.params.auth`
+(token or password). 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 stores the token in `localStorage` after first 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: `Synurex dashboard` (copies link, opens browser if possible, shows SSH hint if headless).
+- If the UI prompts for auth, paste the token from `gateway.auth.token` (or `SYNUREX_GATEWAY_TOKEN`) into Control UI settings.
+
+## Token basics (local vs remote)
+
+- **Localhost**: open `http://127.0.0.1:18789/`.
+- **Token source**: `gateway.auth.token` (or `SYNUREX_GATEWAY_TOKEN`); the UI stores a copy in localStorage after you connect.
+- **Not localhost**: use Tailscale Serve (tokenless if `gateway.auth.allowTailscale: true`), tailnet bind with a token, or an SSH tunnel. See [Web surfaces](/web).
+
+## If you see “unauthorized” / 1008
+
+- Ensure the gateway is reachable (local: `Synurex status`; remote: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`).
+- Retrieve the token from the gateway host: `Synurex config get gateway.auth.token` (or generate one: `Synurex doctor --generate-gateway-token`).
+- In the dashboard settings, paste the token into the auth field, then connect.