fengming 0.3.10 → 0.3.12

package/docs/channels/tlon.md

@@ -1,296 +0,0 @@
----
-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. FengMing 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 FengMing 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
-fengming plugins install @fengming/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
-fengming plugins install ./path/to/local/tlon-plugin
-```
-
-Details: [Plugins](/tools/plugin)
-
-## Setup
-
-1. Ensure the Tlon plugin is available.
-   - Current packaged FengMing 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, FengMing 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 `fengming 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
-fengming status
-fengming gateway status
-fengming logs --follow
-fengming 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, FengMing 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

@@ -1,162 +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"
----
-
-Use this page when a channel connects but behavior is wrong.
-
-## Command ladder
-
-Run these in order first:
-
-```bash
-fengming status
-fengming gateway status
-fengming logs --follow
-fengming doctor
-fengming 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
-fengming status --all
-fengming doctor --fix
-fengming gateway restart
-fengming status --all
-```
-
-Look for `plugin load failed: dependency tree corrupted; run fengming doctor
---fix` in `fengming status --all`. That means the channel is configured, but
-the plugin setup/load path hit a corrupt dependency tree instead of registering
-the channel. `fengming doctor --fix` removes stale plugin dependency staging
-directories and stale auth shadows, then `fengming gateway restart` reloads the
-clean state.
-
-## WhatsApp
-
-### WhatsApp failure signatures
-
-| Symptom                             | Fastest check                                       | Fix                                                                                                                              |
-| ----------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| Connected but no DM replies         | `fengming 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     | `fengming channels status --probe` + logs           | Recent reconnects are flagged even when currently connected; watch logs, restart the gateway, then relink if flapping continues. |
-| `status=408 Request Time-out` loop  | Probe, logs, doctor, then gateway status            | Fix host connectivity/timing first; back up auth and re-link the account if the loop persists.                                   |
-| Replies arrive seconds/minutes late | `fengming 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    | `fengming 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  | `fengming 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    | `fengming security audit` and config allowlists  | Run `fengming 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           | `fengming 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                        | `fengming 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 | `fengming channels status --probe`        | Verify app token + bot token and required scopes; watch for `botTokenStatus` / `appTokenStatus = configured_unavailable` on SecretRef-backed setups. |
-| DMs blocked                            | `fengming 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 | `fengming channels status --probe --channel imessage`   | Run FengMing 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                    | `fengming 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 | `fengming channels status --probe`         | Verify `signal-cli` daemon URL/account and receive mode. |
-| DM blocked                      | `fengming 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             | `fengming 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 | `fengming channels status --probe`     | Check `groupPolicy`, room allowlist, and mention gating.                  |
-| DMs do not process                  | `fengming pairing list matrix`         | Approve sender or adjust DM policy.                                       |
-| Encrypted rooms fail                | `fengming matrix verify status`        | Re-verify the device, then check `fengming matrix verify backup status`.  |
-| Backup restore is pending/broken    | `fengming matrix verify backup status` | Run `fengming matrix verify backup restore` or rerun with a recovery key. |
-| Cross-signing/bootstrap looks wrong | `fengming 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)