@symerian/symi 3.0.21 → 3.0.22

package/docs/channels/tlon.md

@@ -1,148 +0,0 @@
----
-summary: "Tlon/Urbit support status, capabilities, and configuration"
-read_when:
-  - Working on Tlon/Urbit channel features
-title: "Tlon"
----
-
-# Tlon (plugin)
-
-Tlon is a decentralized messenger built on Urbit. Symi connects to your Urbit ship and can
-respond to DMs and group chat messages. Group replies require an @ mention by default and can
-be further restricted via allowlists.
-
-Status: supported via plugin. DMs, group mentions, thread replies, and text-only media fallback
-(URL appended to caption). Reactions, polls, and native media uploads are not supported.
-
-## Plugin required
-
-Tlon ships as a plugin and is not bundled with the core install.
-
-Install via CLI (npm registry):
-
-```bash
-symi plugins install @symi/tlon
-```
-
-Local checkout (when running from a git repo):
-
-```bash
-symi plugins install ./extensions/tlon
-```
-
-Details: [Plugins](/tools/plugin)
-
-## Onboarding
-
-1. Install the Tlon plugin.
-2. Gather your ship URL and login code.
-3. Configure `channels.tlon`.
-4. Restart the gateway.
-5. DM the bot or mention it in a group channel.
-
-Minimal config (single account):
-
-```json5
-{
-  channels: {
-    tlon: {
-      enabled: true,
-      ship: "~sampel-palnet",
-      url: "https://your-ship-host",
-      code: "lidlut-tabwed-pillex-ridrup",
-    },
-  },
-}
-```
-
-Private/LAN ship URLs (advanced):
-
-By default, Symi blocks private/internal hostnames and IP ranges for this plugin (SSRF hardening).
-If your ship URL is on a private network (for example `http://192.168.1.50:8080` or `http://localhost:8080`),
-you must explicitly opt in:
-
-```json5
-{
-  channels: {
-    tlon: {
-      allowPrivateNetwork: true,
-    },
-  },
-}
-```
-
-## Group channels
-
-Auto-discovery is enabled by default. You can also pin channels manually:
-
-```json5
-{
-  channels: {
-    tlon: {
-      groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
-    },
-  },
-}
-```
-
-Disable auto-discovery:
-
-```json5
-{
-  channels: {
-    tlon: {
-      autoDiscoverChannels: false,
-    },
-  },
-}
-```
-
-## Access control
-
-DM allowlist (empty = allow all):
-
-```json5
-{
-  channels: {
-    tlon: {
-      dmAllowlist: ["~zod", "~nec"],
-    },
-  },
-}
-```
-
-Group authorization (restricted by default):
-
-```json5
-{
-  channels: {
-    tlon: {
-      defaultAuthorizedShips: ["~zod"],
-      authorization: {
-        channelRules: {
-          "chat/~host-ship/general": {
-            mode: "restricted",
-            allowedShips: ["~zod", "~nec"],
-          },
-          "chat/~host-ship/announcements": {
-            mode: "open",
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-## Delivery targets (CLI/cron)
-
-Use these with `symi message send` or cron delivery:
-
-- DM: `~sampel-palnet` or `dm/~sampel-palnet`
-- Group: `chat/~host-ship/channel` or `group:~host-ship/channel`
-
-## Notes
-
-- Group replies require a mention (e.g. `~your-bot-ship`) to respond.
-- Thread replies: if the inbound message is in a thread, Symi replies in-thread.
-- Media: `sendMedia` falls back to text + URL (no native upload).

package/docs/channels/troubleshooting.md

@@ -1,110 +0,0 @@
----
-summary: "Fast channel level troubleshooting with per channel failure signatures and fixes"
-read_when:
-  - Channel transport says connected but replies fail
-  - You need channel specific checks before deep provider docs
-title: "Channel Troubleshooting"
----
-
-# Channel troubleshooting
-
-Use this page when a channel connects but behavior is wrong.
-
-## Command ladder
-
-Run these in order first:
-
-```bash
-symi status
-symi gateway status
-symi logs --follow
-symi doctor
-symi channels status --probe
-```
-
-Healthy baseline:
-
-- `Runtime: running`
-- `RPC probe: ok`
-- Channel probe shows connected/ready
-
-## WhatsApp
-
-### WhatsApp failure signatures
-
-| Symptom                         | Fastest check                                       | Fix                                                     |
-| ------------------------------- | --------------------------------------------------- | ------------------------------------------------------- |
-| Connected but no DM replies     | `symi pairing list whatsapp`                        | Approve sender or switch DM policy/allowlist.           |
-| Group messages ignored          | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group. |
-| Random disconnect/relogin loops | `symi channels status --probe` + logs               | Re-login and verify credentials directory is healthy.   |
-
-Full troubleshooting: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
-
-## Telegram
-
-### Telegram failure signatures
-
-| Symptom                           | Fastest check                                   | Fix                                                                     |
-| --------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
-| `/start` but no usable reply flow | `symi pairing list telegram`                    | Approve pairing or change DM policy.                                    |
-| Bot online but group stays silent | Verify mention requirement and bot privacy mode | Disable privacy mode for group visibility or mention bot.               |
-| Send failures with network errors | Inspect logs for Telegram API call failures     | Fix DNS/IPv6/proxy routing to `api.telegram.org`.                       |
-| Upgraded and allowlist blocks you | `symi security audit` and config allowlists     | Run `symi doctor --fix` or replace `@username` with numeric sender IDs. |
-
-Full troubleshooting: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
-
-| Symptom                         | Fastest check                       | Fix                                                       |
-| ------------------------------- | ----------------------------------- | --------------------------------------------------------- |
-| Bot online but no guild replies | `symi channels status --probe`      | Allow guild/channel and verify message content intent.    |
-| Group messages ignored          | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. |
-
-## Slack
-
-### Slack failure signatures
-
-| Symptom                                | Fastest check                             | Fix                                               |
-| -------------------------------------- | ----------------------------------------- | ------------------------------------------------- |
-| Socket mode connected but no responses | `symi channels status --probe`            | Verify app token + bot token and required scopes. |
-| DMs blocked                            | `symi pairing list slack`                 | Approve pairing or relax DM policy.               |
-| Channel message ignored                | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`.     |
-
-Full troubleshooting: [/channels/slack#troubleshooting](/channels/slack#troubleshooting)
-
-## iMessage and BlueBubbles
-
-### iMessage and BlueBubbles failure signatures
-
-| Symptom                          | Fastest check                                                   | Fix                                                   |
-| -------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- |
-| No inbound events                | Verify webhook/server reachability and app permissions          | Fix webhook URL or BlueBubbles server state.          |
-| Can send but no receive on macOS | Check macOS privacy permissions for Messages automation         | Re-grant TCC permissions and restart channel process. |
-| DM sender blocked                | `symi pairing list imessage` or `symi pairing list bluebubbles` | Approve pairing or update allowlist.                  |
-
-Full troubleshooting:
-
-- [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc)
-- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting)
-
-## Signal
-
-### Signal failure signatures
-
-| Symptom                         | Fastest check                              | Fix                                                      |
-| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
-| Daemon reachable but bot silent | `symi channels status --probe`             | Verify `signal-cli` daemon URL/account and receive mode. |
-| DM blocked                      | `symi pairing list signal`                 | Approve sender or adjust DM policy.                      |
-| Group replies do not trigger    | Check group allowlist and mention patterns | Add sender/group or loosen gating.                       |
-
-Full troubleshooting: [/channels/signal#troubleshooting](/channels/signal#troubleshooting)
-
-## Matrix
-
-### Matrix failure signatures
-
-| Symptom                             | Fastest check                                | Fix                                             |
-| ----------------------------------- | -------------------------------------------- | ----------------------------------------------- |
-| Logged in but ignores room messages | `symi channels status --probe`               | Check `groupPolicy` and room allowlist.         |
-| DMs do not process                  | `symi pairing list matrix`                   | Approve sender or adjust DM policy.             |
-| Encrypted rooms fail                | Verify crypto module and encryption settings | Enable encryption support and rejoin/sync room. |
-
-Full troubleshooting: [/channels/matrix#troubleshooting](/channels/matrix#troubleshooting)

package/docs/channels/twitch.md

@@ -1,379 +0,0 @@
----
-summary: "Twitch chat bot configuration and setup"
-read_when:
-  - Setting up Twitch chat integration for Symi
-title: "Twitch"
----
-
-# Twitch (plugin)
-
-Twitch chat support via IRC connection. Symi connects as a Twitch user (bot account) to receive and send messages in channels.
-
-## Plugin required
-
-Twitch ships as a plugin and is not bundled with the core install.
-
-Install via CLI (npm registry):
-
-```bash
-symi plugins install @symi/twitch
-```
-
-Local checkout (when running from a git repo):
-
-```bash
-symi plugins install ./extensions/twitch
-```
-
-Details: [Plugins](/tools/plugin)
-
-## Onboarding
-
-1. Create a dedicated Twitch account for the bot (or use an existing account).
-2. Generate credentials: [Twitch Token Generator](https://twitchtokengenerator.com/)
-   - Select **Bot Token**
-   - Verify scopes `chat:read` and `chat:write` are selected
-   - Copy the **Client ID** and **Access Token**
-3. Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)
-4. Configure the token:
-   - Env: `SYMI_TWITCH_ACCESS_TOKEN=...` (default account only)
-   - Or config: `channels.twitch.accessToken`
-   - If both are set, config takes precedence (env fallback is default-account only).
-5. Start the gateway.
-
-**⚠️ Important:** Add access control (`allowFrom` or `allowedRoles`) to prevent unauthorized users from triggering the bot. `requireMention` defaults to `true`.
-
-Minimal config:
-
-```json5
-{
-  channels: {
-    twitch: {
-      enabled: true,
-      username: "symi", // Bot's Twitch account
-      accessToken: "oauth:abc123...", // OAuth Access Token (or use SYMI_TWITCH_ACCESS_TOKEN env var)
-      clientId: "xyz789...", // Client ID from Token Generator
-      channel: "vevisk", // Which Twitch channel's chat to join (required)
-      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only - get it from https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
-    },
-  },
-}
-```
-
-## What it is
-
-- A Twitch channel owned by the Gateway.
-- Deterministic routing: replies always go back to Twitch.
-- Each account maps to an isolated session key `agent:<agentId>:twitch:<accountName>`.
-- `username` is the bot's account (who authenticates), `channel` is which chat room to join.
-
-## Onboarding (detailed, recommended)
-
-### Generate credentials
-
-Use [Twitch Token Generator](https://twitchtokengenerator.com/):
-
-- Select **Bot Token**
-- Verify scopes `chat:read` and `chat:write` are selected
-- Copy the **Client ID** and **Access Token**
-
-No manual app registration needed. Tokens expire after several hours.
-
-### Configure the bot
-
-**Env var (default account only):**
-
-```bash
-SYMI_TWITCH_ACCESS_TOKEN=oauth:abc123...
-```
-
-**Or config:**
-
-```json5
-{
-  channels: {
-    twitch: {
-      enabled: true,
-      username: "symi",
-      accessToken: "oauth:abc123...",
-      clientId: "xyz789...",
-      channel: "vevisk",
-    },
-  },
-}
-```
-
-If both env and config are set, config takes precedence.
-
-### Access control (recommended)
-
-```json5
-{
-  channels: {
-    twitch: {
-      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
-    },
-  },
-}
-```
-
-Prefer `allowFrom` for a hard allowlist. Use `allowedRoles` instead if you want role-based access.
-
-**Available roles:** `"moderator"`, `"owner"`, `"vip"`, `"subscriber"`, `"all"`.
-
-**Why user IDs?** Usernames can change, allowing impersonation. User IDs are permanent.
-
-Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/) (Convert your Twitch username to ID)
-
-## Token refresh (optional)
-
-Tokens from [Twitch Token Generator](https://twitchtokengenerator.com/) cannot be automatically refreshed - regenerate when expired.
-
-For automatic token refresh, create your own Twitch application at [Twitch Developer Console](https://dev.twitch.tv/console) and add to config:
-
-```json5
-{
-  channels: {
-    twitch: {
-      clientSecret: "your_client_secret",
-      refreshToken: "your_refresh_token",
-    },
-  },
-}
-```
-
-The bot automatically refreshes tokens before expiration and logs refresh events.
-
-## Multi-account support
-
-Use `channels.twitch.accounts` with per-account tokens. See [`gateway/configuration`](/gateway/configuration) for the shared pattern.
-
-Example (one bot account in two channels):
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        channel1: {
-          username: "symi",
-          accessToken: "oauth:abc123...",
-          clientId: "xyz789...",
-          channel: "vevisk",
-        },
-        channel2: {
-          username: "symi",
-          accessToken: "oauth:def456...",
-          clientId: "uvw012...",
-          channel: "secondchannel",
-        },
-      },
-    },
-  },
-}
-```
-
-**Note:** Each account needs its own token (one token per channel).
-
-## Access control
-
-### Role-based restrictions
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        default: {
-          allowedRoles: ["moderator", "vip"],
-        },
-      },
-    },
-  },
-}
-```
-
-### Allowlist by User ID (most secure)
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        default: {
-          allowFrom: ["123456789", "987654321"],
-        },
-      },
-    },
-  },
-}
-```
-
-### Role-based access (alternative)
-
-`allowFrom` is a hard allowlist. When set, only those user IDs are allowed.
-If you want role-based access, leave `allowFrom` unset and configure `allowedRoles` instead:
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        default: {
-          allowedRoles: ["moderator"],
-        },
-      },
-    },
-  },
-}
-```
-
-### Disable @mention requirement
-
-By default, `requireMention` is `true`. To disable and respond to all messages:
-
-```json5
-{
-  channels: {
-    twitch: {
-      accounts: {
-        default: {
-          requireMention: false,
-        },
-      },
-    },
-  },
-}
-```
-
-## Troubleshooting
-
-First, run diagnostic commands:
-
-```bash
-symi doctor
-symi channels status --probe
-```
-
-### Bot doesn't respond to messages
-
-**Check access control:** Ensure your user ID is in `allowFrom`, or temporarily remove
-`allowFrom` and set `allowedRoles: ["all"]` to test.
-
-**Check the bot is in the channel:** The bot must join the channel specified in `channel`.
-
-### Token issues
-
-**"Failed to connect" or authentication errors:**
-
-- Verify `accessToken` is the OAuth access token value (typically starts with `oauth:` prefix)
-- Check token has `chat:read` and `chat:write` scopes
-- If using token refresh, verify `clientSecret` and `refreshToken` are set
-
-### Token refresh not working
-
-**Check logs for refresh events:**
-
-```
-Using env token source for mybot
-Access token refreshed for user 123456 (expires in 14400s)
-```
-
-If you see "token refresh disabled (no refresh token)":
-
-- Ensure `clientSecret` is provided
-- Ensure `refreshToken` is provided
-
-## Config
-
-**Account config:**
-
-- `username` - Bot username
-- `accessToken` - OAuth access token with `chat:read` and `chat:write`
-- `clientId` - Twitch Client ID (from Token Generator or your app)
-- `channel` - Channel to join (required)
-- `enabled` - Enable this account (default: `true`)
-- `clientSecret` - Optional: For automatic token refresh
-- `refreshToken` - Optional: For automatic token refresh
-- `expiresIn` - Token expiry in seconds
-- `obtainmentTimestamp` - Token obtained timestamp
-- `allowFrom` - User ID allowlist
-- `allowedRoles` - Role-based access control (`"moderator" | "owner" | "vip" | "subscriber" | "all"`)
-- `requireMention` - Require @mention (default: `true`)
-
-**Provider options:**
-
-- `channels.twitch.enabled` - Enable/disable channel startup
-- `channels.twitch.username` - Bot username (simplified single-account config)
-- `channels.twitch.accessToken` - OAuth access token (simplified single-account config)
-- `channels.twitch.clientId` - Twitch Client ID (simplified single-account config)
-- `channels.twitch.channel` - Channel to join (simplified single-account config)
-- `channels.twitch.accounts.<accountName>` - Multi-account config (all account fields above)
-
-Full example:
-
-```json5
-{
-  channels: {
-    twitch: {
-      enabled: true,
-      username: "symi",
-      accessToken: "oauth:abc123...",
-      clientId: "xyz789...",
-      channel: "vevisk",
-      clientSecret: "secret123...",
-      refreshToken: "refresh456...",
-      allowFrom: ["123456789"],
-      allowedRoles: ["moderator", "vip"],
-      accounts: {
-        default: {
-          username: "mybot",
-          accessToken: "oauth:abc123...",
-          clientId: "xyz789...",
-          channel: "your_channel",
-          enabled: true,
-          clientSecret: "secret123...",
-          refreshToken: "refresh456...",
-          expiresIn: 14400,
-          obtainmentTimestamp: 1706092800000,
-          allowFrom: ["123456789", "987654321"],
-          allowedRoles: ["moderator"],
-        },
-      },
-    },
-  },
-}
-```
-
-## Tool actions
-
-The agent can call `twitch` with action:
-
-- `send` - Send a message to a channel
-
-Example:
-
-```json5
-{
-  action: "twitch",
-  params: {
-    message: "Hello Twitch!",
-    to: "#mychannel",
-  },
-}
-```
-
-## Safety & ops
-
-- **Treat tokens like passwords** - Never commit tokens to git
-- **Use automatic token refresh** for long-running bots
-- **Use user ID allowlists** instead of usernames for access control
-- **Monitor logs** for token refresh events and connection status
-- **Scope tokens minimally** - Only request `chat:read` and `chat:write`
-- **If stuck**: Restart the gateway after confirming no other process owns the session
-
-## Limits
-
-- **500 characters** per message (auto-chunked at word boundaries)
-- Markdown is stripped before chunking
-- No rate limiting (uses Twitch's built-in rate limits)