@symerian/symi 3.0.20 → 3.0.22

package/docs/gateway/configuration.md

@@ -1,488 +0,0 @@
----
-summary: "Configuration overview: common tasks, quick setup, and links to the full reference"
-read_when:
-  - Setting up Symi for the first time
-  - Looking for common configuration patterns
-  - Navigating to specific config sections
-title: "Configuration"
----
-
-# Configuration
-
-Symi reads an optional <Tooltip tip="JSON5 supports comments and trailing commas">**JSON5**</Tooltip> config from `~/.symi/symi.json`.
-
-If the file is missing, Symi uses safe defaults. Common reasons to add a config:
-
-- Connect channels and control who can message the bot
-- Set models, tools, sandboxing, or automation (cron, hooks)
-- Tune sessions, media, networking, or UI
-
-See the [full reference](/gateway/configuration-reference) for every available field.
-
-<Tip>
-**New to configuration?** Start with `symi onboard` for interactive setup, or check out the [Configuration Examples](/gateway/configuration-examples) guide for complete copy-paste configs.
-</Tip>
-
-## Minimal config
-
-```json5
-// ~/.symi/symi.json
-{
-  agents: { defaults: { workspace: "~/.symi/workspace" } },
-  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
-}
-```
-
-## Editing config
-
-<Tabs>
-  <Tab title="Interactive wizard">
-    ```bash
-    symi onboard       # full setup wizard
-    symi configure     # config wizard
-    ```
-  </Tab>
-  <Tab title="CLI (one-liners)">
-    ```bash
-    symi config get agents.defaults.workspace
-    symi config set agents.defaults.heartbeat.every "2h"
-    symi config unset tools.web.search.apiKey
-    ```
-  </Tab>
-  <Tab title="Control UI">
-    Open [http://127.0.0.1:18789](http://127.0.0.1:18789) and use the **Config** tab.
-    The Control UI renders a form from the config schema, with a **Raw JSON** editor as an escape hatch.
-  </Tab>
-  <Tab title="Direct edit">
-    Edit `~/.symi/symi.json` directly. The Gateway watches the file and applies changes automatically (see [hot reload](#config-hot-reload)).
-  </Tab>
-</Tabs>
-
-## Strict validation
-
-<Warning>
-Symi only accepts configurations that fully match the schema. Unknown keys, malformed types, or invalid values cause the Gateway to **refuse to start**. The only root-level exception is `$schema` (string), so editors can attach JSON Schema metadata.
-</Warning>
-
-When validation fails:
-
-- The Gateway does not boot
-- Only diagnostic commands work (`symi doctor`, `symi logs`, `symi health`, `symi status`)
-- Run `symi doctor` to see exact issues
-- Run `symi doctor --fix` (or `--yes`) to apply repairs
-
-## Common tasks
-
-<AccordionGroup>
-    Each channel has its own config section under `channels.<provider>`. See the dedicated channel page for setup steps:
-
-    - [WhatsApp](/channels/whatsapp) — `channels.whatsapp`
-    - [Telegram](/channels/telegram) — `channels.telegram`
-    - [Slack](/channels/slack) — `channels.slack`
-    - [Signal](/channels/signal) — `channels.signal`
-    - [iMessage](/channels/imessage) — `channels.imessage`
-    - [Google Chat](/channels/googlechat) — `channels.googlechat`
-    - [Mattermost](/channels/mattermost) — `channels.mattermost`
-    - [MS Teams](/channels/msteams) — `channels.msteams`
-
-    All channels share the same DM policy pattern:
-
-    ```json5
-    {
-      channels: {
-        telegram: {
-          enabled: true,
-          botToken: "123:abc",
-          dmPolicy: "pairing",   // pairing | allowlist | open | disabled
-          allowFrom: ["tg:123"], // only for allowlist/open
-        },
-      },
-    }
-    ```
-
-  </Accordion>
-
-  <Accordion title="Choose and configure models">
-    Set the primary model and optional fallbacks:
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          model: {
-            primary: "anthropic/claude-sonnet-4-5",
-            fallbacks: ["openai/gpt-5.2"],
-          },
-          models: {
-            "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
-            "openai/gpt-5.2": { alias: "GPT" },
-          },
-        },
-      },
-    }
-    ```
-
-    - `agents.defaults.models` defines the model catalog and acts as the allowlist for `/model`.
-    - Model refs use `provider/model` format (e.g. `anthropic/claude-opus-4-6`).
-    - `agents.defaults.imageMaxDimensionPx` controls transcript/tool image downscaling (default `1200`); lower values usually reduce vision-token usage on screenshot-heavy runs.
-    - See [Models CLI](/concepts/models) for switching models in chat and [Model Failover](/concepts/model-failover) for auth rotation and fallback behavior.
-    - For custom/self-hosted providers, see [Custom providers](/gateway/configuration-reference#custom-providers-and-base-urls) in the reference.
-
-  </Accordion>
-
-  <Accordion title="Control who can message the bot">
-    DM access is controlled per channel via `dmPolicy`:
-
-    - `"pairing"` (default): unknown senders get a one-time pairing code to approve
-    - `"allowlist"`: only senders in `allowFrom` (or the paired allow store)
-    - `"open"`: allow all inbound DMs (requires `allowFrom: ["*"]`)
-    - `"disabled"`: ignore all DMs
-
-    For groups, use `groupPolicy` + `groupAllowFrom` or channel-specific allowlists.
-
-    See the [full reference](/gateway/configuration-reference#dm-and-group-access) for per-channel details.
-
-  </Accordion>
-
-  <Accordion title="Set up group chat mention gating">
-    Group messages default to **require mention**. Configure patterns per agent:
-
-    ```json5
-    {
-      agents: {
-        list: [
-          {
-            id: "main",
-            groupChat: {
-              mentionPatterns: ["@symi", "symi"],
-            },
-          },
-        ],
-      },
-      channels: {
-        whatsapp: {
-          groups: { "*": { requireMention: true } },
-        },
-      },
-    }
-    ```
-
-    - **Metadata mentions**: native @-mentions (WhatsApp tap-to-mention, Telegram @bot, etc.)
-    - **Text patterns**: regex patterns in `mentionPatterns`
-    - See [full reference](/gateway/configuration-reference#group-chat-mention-gating) for per-channel overrides and self-chat mode.
-
-  </Accordion>
-
-  <Accordion title="Configure sessions and resets">
-    Sessions control conversation continuity and isolation:
-
-    ```json5
-    {
-      session: {
-        dmScope: "per-channel-peer",  // recommended for multi-user
-        reset: {
-          mode: "daily",
-          atHour: 4,
-          idleMinutes: 120,
-        },
-      },
-    }
-    ```
-
-    - `dmScope`: `main` (shared) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
-    - See [Session Management](/concepts/session) for scoping, identity links, and send policy.
-    - See [full reference](/gateway/configuration-reference#session) for all fields.
-
-  </Accordion>
-
-  <Accordion title="Enable sandboxing">
-    Run agent sessions in isolated Docker containers:
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          sandbox: {
-            mode: "non-main",  // off | non-main | all
-            scope: "agent",    // session | agent | shared
-          },
-        },
-      },
-    }
-    ```
-
-    Build the image first: `scripts/sandbox-setup.sh`
-
-    See [Sandboxing](/gateway/sandboxing) for the full guide and [full reference](/gateway/configuration-reference#sandbox) for all options.
-
-  </Accordion>
-
-  <Accordion title="Set up heartbeat (periodic check-ins)">
-    ```json5
-    {
-      agents: {
-        defaults: {
-          heartbeat: {
-            every: "30m",
-            target: "last",
-          },
-        },
-      },
-    }
-    ```
-
-    - `every`: duration string (`30m`, `2h`). Set `0m` to disable.
-    - See [Heartbeat](/gateway/heartbeat) for the full guide.
-
-  </Accordion>
-
-  <Accordion title="Configure cron jobs">
-    ```json5
-    {
-      cron: {
-        enabled: true,
-        maxConcurrentRuns: 2,
-        sessionRetention: "24h",
-      },
-    }
-    ```
-
-    See [Cron jobs](/automation/cron-jobs) for the feature overview and CLI examples.
-
-  </Accordion>
-
-  <Accordion title="Set up webhooks (hooks)">
-    Enable HTTP webhook endpoints on the Gateway:
-
-    ```json5
-    {
-      hooks: {
-        enabled: true,
-        token: "shared-secret",
-        path: "/hooks",
-        defaultSessionKey: "hook:ingress",
-        allowRequestSessionKey: false,
-        allowedSessionKeyPrefixes: ["hook:"],
-        mappings: [
-          {
-            match: { path: "gmail" },
-            action: "agent",
-            agentId: "main",
-            deliver: true,
-          },
-        ],
-      },
-    }
-    ```
-
-    See [full reference](/gateway/configuration-reference#hooks) for all mapping options and Gmail integration.
-
-  </Accordion>
-
-  <Accordion title="Configure multi-agent routing">
-    Run multiple isolated agents with separate workspaces and sessions:
-
-    ```json5
-    {
-      agents: {
-        list: [
-          { id: "home", default: true, workspace: "~/.symi/workspace-home" },
-          { id: "work", workspace: "~/.symi/workspace-work" },
-        ],
-      },
-      bindings: [
-        { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
-        { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
-      ],
-    }
-    ```
-
-    See [Multi-Agent](/concepts/multi-agent) and [full reference](/gateway/configuration-reference#multi-agent-routing) for binding rules and per-agent access profiles.
-
-  </Accordion>
-
-  <Accordion title="Split config into multiple files ($include)">
-    Use `$include` to organize large configs:
-
-    ```json5
-    // ~/.symi/symi.json
-    {
-      gateway: { port: 18789 },
-      agents: { $include: "./agents.json5" },
-      broadcast: {
-        $include: ["./clients/a.json5", "./clients/b.json5"],
-      },
-    }
-    ```
-
-    - **Single file**: replaces the containing object
-    - **Array of files**: deep-merged in order (later wins)
-    - **Sibling keys**: merged after includes (override included values)
-    - **Nested includes**: supported up to 10 levels deep
-    - **Relative paths**: resolved relative to the including file
-    - **Error handling**: clear errors for missing files, parse errors, and circular includes
-
-  </Accordion>
-</AccordionGroup>
-
-## Config hot reload
-
-The Gateway watches `~/.symi/symi.json` and applies changes automatically — no manual restart needed for most settings.
-
-### Reload modes
-
-| Mode                   | Behavior                                                                                |
-| ---------------------- | --------------------------------------------------------------------------------------- |
-| **`hybrid`** (default) | Hot-applies safe changes instantly. Automatically restarts for critical ones.           |
-| **`hot`**              | Hot-applies safe changes only. Logs a warning when a restart is needed — you handle it. |
-| **`restart`**          | Restarts the Gateway on any config change, safe or not.                                 |
-| **`off`**              | Disables file watching. Changes take effect on the next manual restart.                 |
-
-```json5
-{
-  gateway: {
-    reload: { mode: "hybrid", debounceMs: 300 },
-  },
-}
-```
-
-### What hot-applies vs what needs a restart
-
-Most fields hot-apply without downtime. In `hybrid` mode, restart-required changes are handled automatically.
-
-| Category            | Fields                                                               | Restart needed? |
-| ------------------- | -------------------------------------------------------------------- | --------------- |
-| Channels            | `channels.*`, `web` (WhatsApp) — all built-in and extension channels | No              |
-| Agent & models      | `agent`, `agents`, `models`, `routing`                               | No              |
-| Automation          | `hooks`, `cron`, `agent.heartbeat`                                   | No              |
-| Sessions & messages | `session`, `messages`                                                | No              |
-| Tools & media       | `tools`, `browser`, `skills`, `audio`, `talk`                        | No              |
-| UI & misc           | `ui`, `logging`, `identity`, `bindings`                              | No              |
-| Gateway server      | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP)                 | **Yes**         |
-| Infrastructure      | `discovery`, `canvasHost`, `plugins`                                 | **Yes**         |
-
-<Note>
-`gateway.reload` and `gateway.remote` are exceptions — changing them does **not** trigger a restart.
-</Note>
-
-## Config RPC (programmatic updates)
-
-<Note>
-Control-plane write RPCs (`config.apply`, `config.patch`, `update.run`) are rate-limited to **3 requests per 60 seconds** per `deviceId+clientIp`. When limited, the RPC returns `UNAVAILABLE` with `retryAfterMs`.
-</Note>
-
-<AccordionGroup>
-  <Accordion title="config.apply (full replace)">
-    Validates + writes the full config and restarts the Gateway in one step.
-
-    <Warning>
-    `config.apply` replaces the **entire config**. Use `config.patch` for partial updates, or `symi config set` for single keys.
-    </Warning>
-
-    Params:
-
-    - `raw` (string) — JSON5 payload for the entire config
-    - `baseHash` (optional) — config hash from `config.get` (required when config exists)
-    - `sessionKey` (optional) — session key for the post-restart wake-up ping
-    - `note` (optional) — note for the restart sentinel
-    - `restartDelayMs` (optional) — delay before restart (default 2000)
-
-    Restart requests are coalesced while one is already pending/in-flight, and a 30-second cooldown applies between restart cycles.
-
-    ```bash
-    symi gateway call config.get --params '{}'  # capture payload.hash
-    symi gateway call config.apply --params '{
-      "raw": "{ agents: { defaults: { workspace: \"~/.symi/workspace\" } } }",
-      "baseHash": "<hash>",
-      "sessionKey": "agent:main:whatsapp:dm:+15555550123"
-    }'
-    ```
-
-  </Accordion>
-
-  <Accordion title="config.patch (partial update)">
-    Merges a partial update into the existing config (JSON merge patch semantics):
-
-    - Objects merge recursively
-    - `null` deletes a key
-    - Arrays replace
-
-    Params:
-
-    - `raw` (string) — JSON5 with just the keys to change
-    - `baseHash` (required) — config hash from `config.get`
-    - `sessionKey`, `note`, `restartDelayMs` — same as `config.apply`
-
-    Restart behavior matches `config.apply`: coalesced pending restarts plus a 30-second cooldown between restart cycles.
-
-    ```bash
-    symi gateway call config.patch --params '{
-      "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
-      "baseHash": "<hash>"
-    }'
-    ```
-
-  </Accordion>
-</AccordionGroup>
-
-## Environment variables
-
-Symi reads env vars from the parent process plus:
-
-- `.env` from the current working directory (if present)
-- `~/.symi/.env` (global fallback)
-
-Neither file overrides existing env vars. You can also set inline env vars in config:
-
-```json5
-{
-  env: {
-    OPENROUTER_API_KEY: "sk-or-...",
-    vars: { GROQ_API_KEY: "gsk-..." },
-  },
-}
-```
-
-<Accordion title="Shell env import (optional)">
-  If enabled and expected keys aren't set, Symi runs your login shell and imports only the missing keys:
-
-```json5
-{
-  env: {
-    shellEnv: { enabled: true, timeoutMs: 15000 },
-  },
-}
-```
-
-Env var equivalent: `SYMI_LOAD_SHELL_ENV=1`
-</Accordion>
-
-<Accordion title="Env var substitution in config values">
-  Reference env vars in any config string value with `${VAR_NAME}`:
-
-```json5
-{
-  gateway: { auth: { token: "${SYMI_GATEWAY_TOKEN}" } },
-  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
-}
-```
-
-Rules:
-
-- Only uppercase names matched: `[A-Z_][A-Z0-9_]*`
-- Missing/empty vars throw an error at load time
-- Escape with `$${VAR}` for literal output
-- Works inside `$include` files
-- Inline substitution: `"${BASE}/v1"` → `"https://api.example.com/v1"`
-
-</Accordion>
-
-See [Environment](/help/environment) for full precedence and sources.
-
-## Full reference
-
-For the complete field-by-field reference, see **[Configuration Reference](/gateway/configuration-reference)**.
-
----
-
-_Related: [Configuration Examples](/gateway/configuration-examples) · [Configuration Reference](/gateway/configuration-reference) · [Doctor](/gateway/doctor)_

package/docs/gateway/discovery.md

@@ -1,123 +0,0 @@
----
-summary: "Node discovery and transports (Bonjour, Tailscale, SSH) for finding the gateway"
-read_when:
-  - Implementing or changing Bonjour discovery/advertising
-  - Adjusting remote connection modes (direct vs SSH)
-  - Designing node discovery + pairing for remote nodes
-title: "Discovery and Transports"
----
-
-# Discovery & transports
-
-Symi has two distinct problems that look similar on the surface:
-
-1. **Operator remote control**: the macOS menu bar app controlling a gateway running elsewhere.
-2. **Node pairing**: iOS/Android (and future nodes) finding a gateway and pairing securely.
-
-The design goal is to keep all network discovery/advertising in the **Node Gateway** (`symi gateway`) and keep clients (mac app, iOS) as consumers.
-
-## Terms
-
-- **Gateway**: a single long-running gateway process that owns state (sessions, pairing, node registry) and runs channels. Most setups use one per host; isolated multi-gateway setups are possible.
-- **Gateway WS (control plane)**: the WebSocket endpoint on `127.0.0.1:18789` by default; can be bound to LAN/tailnet via `gateway.bind`.
-- **Direct WS transport**: a LAN/tailnet-facing Gateway WS endpoint (no SSH).
-- **SSH transport (fallback)**: remote control by forwarding `127.0.0.1:18789` over SSH.
-- **Legacy TCP bridge (deprecated/removed)**: older node transport (see [Bridge protocol](/gateway/bridge-protocol)); no longer advertised for discovery.
-
-Protocol details:
-
-- [Gateway protocol](/gateway/protocol)
-- [Bridge protocol (legacy)](/gateway/bridge-protocol)
-
-## Why we keep both “direct” and SSH
-
-- **Direct WS** is the best UX on the same network and within a tailnet:
-  - auto-discovery on LAN via Bonjour
-  - pairing tokens + ACLs owned by the gateway
-  - no shell access required; protocol surface can stay tight and auditable
-- **SSH** remains the universal fallback:
-  - works anywhere you have SSH access (even across unrelated networks)
-  - survives multicast/mDNS issues
-  - requires no new inbound ports besides SSH
-
-## Discovery inputs (how clients learn where the gateway is)
-
-### 1) Bonjour / mDNS (LAN only)
-
-Bonjour is best-effort and does not cross networks. It is only used for “same LAN” convenience.
-
-Target direction:
-
-- The **gateway** advertises its WS endpoint via Bonjour.
-- Clients browse and show a “pick a gateway” list, then store the chosen endpoint.
-
-Troubleshooting and beacon details: [Bonjour](/gateway/bonjour).
-
-#### Service beacon details
-
-- Service types:
-  - `_symi-gw._tcp` (gateway transport beacon)
-- TXT keys (non-secret):
-  - `role=gateway`
-  - `lanHost=<hostname>.local`
-  - `sshPort=22` (or whatever is advertised)
-  - `gatewayPort=18789` (Gateway WS + HTTP)
-  - `gatewayTls=1` (only when TLS is enabled)
-  - `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
-  - `canvasPort=<port>` (canvas host port; currently the same as `gatewayPort` when the canvas host is enabled)
-  - `cliPath=<path>` (optional; absolute path to a runnable `symi` entrypoint or binary)
-  - `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)
-
-Security notes:
-
-- Bonjour/mDNS TXT records are **unauthenticated**. Clients must treat TXT values as UX hints only.
-- Routing (host/port) should prefer the **resolved service endpoint** (SRV + A/AAAA) over TXT-provided `lanHost`, `tailnetDns`, or `gatewayPort`.
-- TLS pinning must never allow an advertised `gatewayTlsSha256` to override a previously stored pin.
-- iOS/Android nodes should treat discovery-based direct connects as **TLS-only** and require an explicit “trust this fingerprint” confirmation before storing a first-time pin (out-of-band verification).
-
-Disable/override:
-
-- `SYMI_DISABLE_BONJOUR=1` disables advertising.
-- `gateway.bind` in `~/.symi/symi.json` controls the Gateway bind mode.
-- `SYMI_SSH_PORT` overrides the SSH port advertised in TXT (defaults to 22).
-- `SYMI_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS).
-- `SYMI_CLI_PATH` overrides the advertised CLI path.
-
-### 2) Tailnet (cross-network)
-
-For London/Vienna style setups, Bonjour won’t help. The recommended “direct” target is:
-
-- Tailscale MagicDNS name (preferred) or a stable tailnet IP.
-
-If the gateway can detect it is running under Tailscale, it publishes `tailnetDns` as an optional hint for clients (including wide-area beacons).
-
-### 3) Manual / SSH target
-
-When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.
-
-See [Remote access](/gateway/remote).
-
-## Transport selection (client policy)
-
-Recommended client behavior:
-
-1. If a paired direct endpoint is configured and reachable, use it.
-2. Else, if Bonjour finds a gateway on LAN, offer a one-tap “Use this gateway” choice and save it as the direct endpoint.
-3. Else, if a tailnet DNS/IP is configured, try direct.
-4. Else, fall back to SSH.
-
-## Pairing + auth (direct transport)
-
-The gateway is the source of truth for node/client admission.
-
-- Pairing requests are created/approved/rejected in the gateway (see [Gateway pairing](/gateway/pairing)).
-- The gateway enforces:
-  - auth (token / keypair)
-  - scopes/ACLs (the gateway is not a raw proxy to every method)
-  - rate limits
-
-## Responsibilities by component
-
-- **Gateway**: advertises discovery beacons, owns pairing decisions, and hosts the WS endpoint.
-- **macOS app**: helps you pick a gateway, shows pairing prompts, and uses SSH only as a fallback.
-- **iOS/Android nodes**: browse Bonjour as a convenience and connect to the paired Gateway WS.