@quantumclaw/quantumclaw 2026.3.22

package/docs/channels/tlon.md

@@ -0,0 +1,276 @@
+---
+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. QuantumClaw 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, rich text formatting, and
+image uploads are supported. Reactions and polls are not yet supported.
+
+## Plugin required
+
+Tlon ships as a plugin and is not bundled with the core install.
+
+Install via CLI (npm registry):
+
+```bash
+quantumclaw plugins install @quantumclaw/tlon
+```
+
+Local checkout (when running from a git repo):
+
+```bash
+quantumclaw plugins install ./extensions/tlon
+```
+
+Details: [Plugins](/tools/plugin)
+
+## Setup
+
+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",
+      ownerShip: "~your-main-ship", // recommended: your ship, always allowed
+    },
+  },
+}
+```
+
+## Private/LAN ships
+
+By default, QuantumClaw 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:
+
+```json5
+{
+  channels: {
+    tlon: {
+      autoAcceptGroupInvites: true,
+    },
+  },
+}
+```
+
+## Delivery targets (CLI/cron)
+
+Use these with `quantumclaw 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
+quantumclaw status
+quantumclaw gateway status
+quantumclaw logs --follow
+quantumclaw 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 all group invites.
+- `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, QuantumClaw 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.

package/docs/channels/troubleshooting.md

@@ -0,0 +1,118 @@
+---
+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
+quantumclaw status
+quantumclaw gateway status
+quantumclaw logs --follow
+quantumclaw doctor
+quantumclaw 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     | `quantumclaw 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 | `quantumclaw channels status --probe` + logs           | Re-login and verify credentials directory is healthy.   |
+
+Full troubleshooting: [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting)
+
+## Telegram
+
+### Telegram failure signatures
+
+| Symptom                             | Fastest check                                   | Fix                                                                         |
+| ----------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
+| `/start` but no usable reply flow   | `quantumclaw 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`.                           |
+| `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   | `quantumclaw security audit` and config allowlists | Run `quantumclaw doctor --fix` or replace `@username` with numeric sender IDs. |
+
+Full troubleshooting: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
+
+## Discord
+
+### Discord failure signatures
+
+| Symptom                         | Fastest check                       | Fix                                                       |
+| ------------------------------- | ----------------------------------- | --------------------------------------------------------- |
+| Bot online but no guild replies | `quantumclaw 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`. |
+| DM replies missing              | `quantumclaw pairing list discord`     | Approve DM pairing or adjust DM policy.                   |
+
+Full troubleshooting: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
+
+## Slack
+
+### Slack failure signatures
+
+| Symptom                                | Fastest check                             | Fix                                               |
+| -------------------------------------- | ----------------------------------------- | ------------------------------------------------- |
+| Socket mode connected but no responses | `quantumclaw channels status --probe`        | Verify app token + bot token and required scopes. |
+| DMs blocked                            | `quantumclaw 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                | `quantumclaw pairing list imessage` or `quantumclaw pairing list bluebubbles` | Approve pairing or update allowlist.                  |
+
+Full troubleshooting:
+
+- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting)
+- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting)
+
+## Signal
+
+### Signal failure signatures
+
+| Symptom                         | Fastest check                              | Fix                                                      |
+| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
+| Daemon reachable but bot silent | `quantumclaw channels status --probe`         | Verify `signal-cli` daemon URL/account and receive mode. |
+| DM blocked                      | `quantumclaw 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 | `quantumclaw channels status --probe`           | Check `groupPolicy` and room allowlist.         |
+| DMs do not process                  | `quantumclaw 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)