nodmix 2026.5.25

package/docs/channels/tlon.md

@@ -0,0 +1,296 @@
+---
+summary: "Tlon/Urbit support status, capabilities, and configuration"
+read_when:
+  - Working on Tlon/Urbit channel features
+title: "Tlon"
+---
+
+Tlon is a decentralized messenger built on Urbit. Nodmix 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: bundled plugin. DMs, group mentions, thread replies, rich text formatting, and
+image uploads are supported. Reactions and polls are not yet supported.
+
+## Bundled plugin
+
+Tlon ships as a bundled plugin in current Nodmix releases, so normal packaged
+builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Tlon, install a
+current npm package:
+
+Install via CLI (npm registry):
+
+```bash
+nodmix plugins install @nodmix/tlon
+```
+
+Use the bare package to follow the current official release tag. Pin an exact
+version only when you need a reproducible install.
+
+Local checkout (when running from a git repo):
+
+```bash
+nodmix plugins install ./path/to/local/tlon-plugin
+```
+
+Details: [Plugins](/tools/plugin)
+
+## Setup
+
+1. Ensure the Tlon plugin is available.
+   - Current packaged Nodmix releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
+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",
+      ownerShip: "~your-main-ship", // recommended: your ship, always allowed
+    },
+  },
+}
+```
+
+## Private/LAN ships
+
+By default, Nodmix blocks private/internal hostnames and IP ranges for SSRF protection.
+If your ship is running on a private network (localhost, LAN IP, or internal hostname),
+you must explicitly opt in:
+
+```json5
+{
+  channels: {
+    tlon: {
+      url: "http://localhost:8080",
+      allowPrivateNetwork: true,
+    },
+  },
+}
+```
+
+This applies to URLs like:
+
+- `http://localhost:8080`
+- `http://192.168.x.x:8080`
+- `http://my-ship.local:8080`
+
+⚠️ Only enable this if you trust your local network. This setting disables SSRF protections
+for requests to your ship URL.
+
+## 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 = no DMs allowed, use `ownerShip` for approval flow):
+
+```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",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Owner and approval system
+
+Set an owner ship to receive approval requests when unauthorized users try to interact:
+
+```json5
+{
+  channels: {
+    tlon: {
+      ownerShip: "~your-main-ship",
+    },
+  },
+}
+```
+
+The owner ship is **automatically authorized everywhere** — DM invites are auto-accepted and
+channel messages are always allowed. You don't need to add the owner to `dmAllowlist` or
+`defaultAuthorizedShips`.
+
+When set, the owner receives DM notifications for:
+
+- DM requests from ships not in the allowlist
+- Mentions in channels without authorization
+- Group invite requests
+
+## Auto-accept settings
+
+Auto-accept DM invites (for ships in dmAllowlist):
+
+```json5
+{
+  channels: {
+    tlon: {
+      autoAcceptDmInvites: true,
+    },
+  },
+}
+```
+
+Auto-accept group invites from trusted ships:
+
+```json5
+{
+  channels: {
+    tlon: {
+      autoAcceptGroupInvites: true,
+      groupInviteAllowlist: ["~zod"],
+    },
+  },
+}
+```
+
+`autoAcceptGroupInvites` fails closed when `groupInviteAllowlist` is empty. Set the
+allowlist to the ships whose group invites should be accepted automatically.
+
+## Delivery targets (CLI/cron)
+
+Use these with `nodmix message send` or cron delivery:
+
+- DM: `~sampel-palnet` or `dm/~sampel-palnet`
+- Group: `chat/~host-ship/channel` or `group:~host-ship/channel`
+
+## Bundled skill
+
+The Tlon plugin includes a bundled skill ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill))
+that provides CLI access to Tlon operations:
+
+- **Contacts**: get/update profiles, list contacts
+- **Channels**: list, create, post messages, fetch history
+- **Groups**: list, create, manage members
+- **DMs**: send messages, react to messages
+- **Reactions**: add/remove emoji reactions to posts and DMs
+- **Settings**: manage plugin permissions via slash commands
+
+The skill is automatically available when the plugin is installed.
+
+## Capabilities
+
+| Feature         | Status                                  |
+| --------------- | --------------------------------------- |
+| Direct messages | ✅ Supported                            |
+| Groups/channels | ✅ Supported (mention-gated by default) |
+| Threads         | ✅ Supported (auto-replies in thread)   |
+| Rich text       | ✅ Markdown converted to Tlon format    |
+| Images          | ✅ Uploaded to Tlon storage             |
+| Reactions       | ✅ Via [bundled skill](#bundled-skill)  |
+| Polls           | ❌ Not yet supported                    |
+| Native commands | ✅ Supported (owner-only by default)    |
+
+## Troubleshooting
+
+Run this ladder first:
+
+```bash
+nodmix status
+nodmix gateway status
+nodmix logs --follow
+nodmix doctor
+```
+
+Common failures:
+
+- **DMs ignored**: sender not in `dmAllowlist` and no `ownerShip` configured for approval flow.
+- **Group messages ignored**: channel not discovered or sender not authorized.
+- **Connection errors**: check ship URL is reachable; enable `allowPrivateNetwork` for local ships.
+- **Auth errors**: verify login code is current (codes rotate).
+
+## Configuration reference
+
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+
+- `channels.tlon.enabled`: enable/disable channel startup.
+- `channels.tlon.ship`: bot's Urbit ship name (e.g. `~sampel-palnet`).
+- `channels.tlon.url`: ship URL (e.g. `https://sampel-palnet.tlon.network`).
+- `channels.tlon.code`: ship login code.
+- `channels.tlon.allowPrivateNetwork`: allow localhost/LAN URLs (SSRF bypass).
+- `channels.tlon.ownerShip`: owner ship for approval system (always authorized).
+- `channels.tlon.dmAllowlist`: ships allowed to DM (empty = none).
+- `channels.tlon.autoAcceptDmInvites`: auto-accept DMs from allowlisted ships.
+- `channels.tlon.autoAcceptGroupInvites`: auto-accept group invites from allowlisted ships.
+- `channels.tlon.groupInviteAllowlist`: ships whose group invites may be auto-accepted.
+- `channels.tlon.autoDiscoverChannels`: auto-discover group channels (default: true).
+- `channels.tlon.groupChannels`: manually pinned channel nests.
+- `channels.tlon.defaultAuthorizedShips`: ships authorized for all channels.
+- `channels.tlon.authorization.channelRules`: per-channel auth rules.
+- `channels.tlon.showModelSignature`: append model name to messages.
+
+## Notes
+
+- Group replies require a mention (e.g. `~your-bot-ship`) to respond.
+- Thread replies: if the inbound message is in a thread, Nodmix replies in-thread.
+- Rich text: Markdown formatting (bold, italic, code, headers, lists) is converted to Tlon's native format.
+- Images: URLs are uploaded to Tlon storage and embedded as image blocks.
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening

package/docs/channels/troubleshooting.md

@@ -0,0 +1,161 @@
+---
+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"
+---
+
+Use this page when a channel connects but behavior is wrong.
+
+## Command ladder
+
+Run these in order first:
+
+```bash
+nodmix status
+nodmix gateway status
+nodmix logs --follow
+nodmix doctor
+nodmix channels status --probe
+```
+
+Healthy baseline:
+
+- `Runtime: running`
+- `Connectivity probe: ok`
+- `Capability: read-only`, `write-capable`, or `admin-capable`
+- Channel probe shows transport connected and, where supported, `works` or `audit ok`
+
+## After an update
+
+Use this when Telegram, iMessage, BlueBubbles-era configs, or another plugin
+channel disappears after updating.
+
+```bash
+nodmix status --all
+nodmix doctor --fix
+nodmix gateway restart
+nodmix status --all
+```
+
+Look for `plugin load failed: dependency tree corrupted; run nodmix doctor
+--fix` in `nodmix status --all`. That means the channel is configured, but
+the plugin setup/load path hit a corrupt dependency tree instead of registering
+the channel. `nodmix doctor --fix` removes stale plugin dependency staging
+directories and stale auth shadows, then `nodmix gateway restart` reloads the
+clean state.
+
+## WhatsApp
+
+### WhatsApp failure signatures
+
+| Symptom                             | Fastest check                                       | Fix                                                                                                                              |
+| ----------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Connected but no DM replies         | `nodmix 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.                                                                          |
+| QR login times out with 408         | Check gateway `HTTPS_PROXY` / `HTTP_PROXY` env      | Set a reachable proxy; use `NO_PROXY` only for bypasses.                                                                         |
+| Random disconnect/relogin loops     | `nodmix channels status --probe` + logs           | Recent reconnects are flagged even when currently connected; watch logs, restart the gateway, then relink if flapping continues. |
+| Replies arrive seconds/minutes late | `nodmix doctor --fix`                             | Doctor stops verified stale local TUI clients when they are degrading the Gateway event loop.                                    |
+
+Full troubleshooting: [WhatsApp troubleshooting](/channels/whatsapp#troubleshooting)
+
+## Telegram
+
+### Telegram failure signatures
+
+| Symptom                              | Fastest check                                    | Fix                                                                                                                        |
+| ------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `/start` but no usable reply flow    | `nodmix 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`.                                                                          |
+| Startup reports `getMe returned 401` | Check configured token source                    | Re-copy or regenerate the BotFather token and update `botToken`, `tokenFile`, or default-account `TELEGRAM_BOT_TOKEN`.     |
+| Polling stalls or reconnects slowly  | `nodmix logs --follow` for polling diagnostics | Upgrade; if restarts are false positives, tune `pollingStallThresholdMs`. Persistent stalls still point to proxy/DNS/IPv6. |
+| `setMyCommands` rejected at startup  | Inspect logs for `BOT_COMMANDS_TOO_MUCH`         | Reduce plugin/skill/custom Telegram commands or disable native menus.                                                      |
+| Upgraded and allowlist blocks you    | `nodmix security audit` and config allowlists  | Run `nodmix doctor --fix` or replace `@username` with numeric sender IDs.                                                |
+
+Full troubleshooting: [Telegram troubleshooting](/channels/telegram#troubleshooting)
+
+## Discord
+
+### Discord failure signatures
+
+| Symptom                                   | Fastest check                                                                                                                | Fix                                                                                                                                                                                                                                                                   |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Bot online but no guild replies           | `nodmix 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`.                                                                                                                                                                                                             |
+| Typing/token usage but no Discord message | Check whether this is an ambient room event or an opted-in `message_tool` room where the model missed `message(action=send)` | Inspect the gateway verbose log for suppressed final payload metadata, verify `messages.groupChat.unmentionedInbound`, read [Ambient room events](/channels/ambient-room-events), or keep `messages.groupChat.visibleReplies: "automatic"` for normal group requests. |
+| DM replies missing                        | `nodmix pairing list discord`                                                                                              | Approve DM pairing or adjust DM policy.                                                                                                                                                                                                                               |
+
+Full troubleshooting: [Discord troubleshooting](/channels/discord#troubleshooting)
+
+## Slack
+
+### Slack failure signatures
+
+| Symptom                                | Fastest check                             | Fix                                                                                                                                                  |
+| -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Socket mode connected but no responses | `nodmix channels status --probe`        | Verify app token + bot token and required scopes; watch for `botTokenStatus` / `appTokenStatus = configured_unavailable` on SecretRef-backed setups. |
+| DMs blocked                            | `nodmix 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: [Slack troubleshooting](/channels/slack#troubleshooting)
+
+## iMessage
+
+### iMessage failure signatures
+
+| Symptom                              | Fastest check                                           | Fix                                                                   |
+| ------------------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------- |
+| `imsg` missing or fails on non-macOS | `nodmix channels status --probe --channel imessage`   | Run Nodmix on the Messages Mac or use an SSH wrapper for `cliPath`. |
+| 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                    | `nodmix pairing list imessage`                        | Approve pairing or update allowlist.                                  |
+
+Full troubleshooting:
+
+- [iMessage troubleshooting](/channels/imessage#troubleshooting)
+
+## Signal
+
+### Signal failure signatures
+
+| Symptom                         | Fastest check                              | Fix                                                      |
+| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
+| Daemon reachable but bot silent | `nodmix channels status --probe`         | Verify `signal-cli` daemon URL/account and receive mode. |
+| DM blocked                      | `nodmix 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: [Signal troubleshooting](/channels/signal#troubleshooting)
+
+## QQ Bot
+
+### QQ Bot failure signatures
+
+| Symptom                         | Fastest check                               | Fix                                                             |
+| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
+| Bot replies "gone to Mars"      | Verify `appId` and `clientSecret` in config | Set credentials or restart the gateway.                         |
+| No inbound messages             | `nodmix channels status --probe`          | Verify credentials on the QQ Open Platform.                     |
+| Voice not transcribed           | Check STT provider config                   | Configure `channels.qqbot.stt` or `tools.media.audio`.          |
+| Proactive messages not arriving | Check QQ platform interaction requirements  | QQ may block bot-initiated messages without recent interaction. |
+
+Full troubleshooting: [QQ Bot troubleshooting](/channels/qqbot#troubleshooting)
+
+## Matrix
+
+### Matrix failure signatures
+
+| Symptom                             | Fastest check                          | Fix                                                                       |
+| ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
+| Logged in but ignores room messages | `nodmix channels status --probe`     | Check `groupPolicy`, room allowlist, and mention gating.                  |
+| DMs do not process                  | `nodmix pairing list matrix`         | Approve sender or adjust DM policy.                                       |
+| Encrypted rooms fail                | `nodmix matrix verify status`        | Re-verify the device, then check `nodmix matrix verify backup status`.  |
+| Backup restore is pending/broken    | `nodmix matrix verify backup status` | Run `nodmix matrix verify backup restore` or rerun with a recovery key. |
+| Cross-signing/bootstrap looks wrong | `nodmix matrix verify bootstrap`     | Repair secret storage, cross-signing, and backup state in one pass.       |
+
+Full setup and config: [Matrix](/channels/matrix)
+
+## Related
+
+- [Pairing](/channels/pairing)
+- [Channel routing](/channels/channel-routing)
+- [Gateway troubleshooting](/gateway/troubleshooting)