@symerian/symi 3.0.20 → 3.0.22

package/docs/channels/nextcloud-talk.md

@@ -1,138 +0,0 @@
----
-summary: "Nextcloud Talk support status, capabilities, and configuration"
-read_when:
-  - Working on Nextcloud Talk channel features
-title: "Nextcloud Talk"
----
-
-# Nextcloud Talk (plugin)
-
-Status: supported via plugin (webhook bot). Direct messages, rooms, reactions, and markdown messages are supported.
-
-## Plugin required
-
-Nextcloud Talk ships as a plugin and is not bundled with the core install.
-
-Install via CLI (npm registry):
-
-```bash
-symi plugins install @symi/nextcloud-talk
-```
-
-Local checkout (when running from a git repo):
-
-```bash
-symi plugins install ./extensions/nextcloud-talk
-```
-
-If you choose Nextcloud Talk during configure/onboarding and a git checkout is detected,
-Symi will offer the local install path automatically.
-
-Details: [Plugins](/tools/plugin)
-
-## Onboarding
-
-1. Install the Nextcloud Talk plugin.
-2. On your Nextcloud server, create a bot:
-
-   ```bash
-   ./occ talk:bot:install "Symi" "<shared-secret>" "<webhook-url>" --feature reaction
-   ```
-
-3. Enable the bot in the target room settings.
-4. Configure Symi:
-   - Config: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
-   - Or env: `NEXTCLOUD_TALK_BOT_SECRET` (default account only)
-5. Restart the gateway (or finish onboarding).
-
-Minimal config:
-
-```json5
-{
-  channels: {
-    "nextcloud-talk": {
-      enabled: true,
-      baseUrl: "https://cloud.example.com",
-      botSecret: "shared-secret",
-      dmPolicy: "pairing",
-    },
-  },
-}
-```
-
-## Notes
-
-- Bots cannot initiate DMs. The user must message the bot first.
-- Webhook URL must be reachable by the Gateway; set `webhookPublicUrl` if behind a proxy.
-- Media uploads are not supported by the bot API; media is sent as URLs.
-- The webhook payload does not distinguish DMs vs rooms; set `apiUser` + `apiPassword` to enable room-type lookups (otherwise DMs are treated as rooms).
-
-## Access control (DMs)
-
-- Default: `channels.nextcloud-talk.dmPolicy = "pairing"`. Unknown senders get a pairing code.
-- Approve via:
-  - `symi pairing list nextcloud-talk`
-  - `symi pairing approve nextcloud-talk <CODE>`
-- Public DMs: `channels.nextcloud-talk.dmPolicy="open"` plus `channels.nextcloud-talk.allowFrom=["*"]`.
-- `allowFrom` matches Nextcloud user IDs only; display names are ignored.
-
-## Rooms (groups)
-
-- Default: `channels.nextcloud-talk.groupPolicy = "allowlist"` (mention-gated).
-- Allowlist rooms with `channels.nextcloud-talk.rooms`:
-
-```json5
-{
-  channels: {
-    "nextcloud-talk": {
-      rooms: {
-        "room-token": { requireMention: true },
-      },
-    },
-  },
-}
-```
-
-- To allow no rooms, keep the allowlist empty or set `channels.nextcloud-talk.groupPolicy="disabled"`.
-
-## Capabilities
-
-| Feature         | Status        |
-| --------------- | ------------- |
-| Direct messages | Supported     |
-| Rooms           | Supported     |
-| Threads         | Not supported |
-| Media           | URL-only      |
-| Reactions       | Supported     |
-| Native commands | Not supported |
-
-## Configuration
-
-Full configuration: [Configuration](/gateway/configuration)
-
-Provider options:
-
-- `channels.nextcloud-talk.enabled`: enable/disable channel startup.
-- `channels.nextcloud-talk.baseUrl`: Nextcloud instance URL.
-- `channels.nextcloud-talk.botSecret`: bot shared secret.
-- `channels.nextcloud-talk.botSecretFile`: secret file path.
-- `channels.nextcloud-talk.apiUser`: API user for room lookups (DM detection).
-- `channels.nextcloud-talk.apiPassword`: API/app password for room lookups.
-- `channels.nextcloud-talk.apiPasswordFile`: API password file path.
-- `channels.nextcloud-talk.webhookPort`: webhook listener port (default: 8788).
-- `channels.nextcloud-talk.webhookHost`: webhook host (default: 0.0.0.0).
-- `channels.nextcloud-talk.webhookPath`: webhook path (default: /nextcloud-talk-webhook).
-- `channels.nextcloud-talk.webhookPublicUrl`: externally reachable webhook URL.
-- `channels.nextcloud-talk.dmPolicy`: `pairing | allowlist | open | disabled`.
-- `channels.nextcloud-talk.allowFrom`: DM allowlist (user IDs). `open` requires `"*"`.
-- `channels.nextcloud-talk.groupPolicy`: `allowlist | open | disabled`.
-- `channels.nextcloud-talk.groupAllowFrom`: group allowlist (user IDs).
-- `channels.nextcloud-talk.rooms`: per-room settings and allowlist.
-- `channels.nextcloud-talk.historyLimit`: group history limit (0 disables).
-- `channels.nextcloud-talk.dmHistoryLimit`: DM history limit (0 disables).
-- `channels.nextcloud-talk.dms`: per-DM overrides (historyLimit).
-- `channels.nextcloud-talk.textChunkLimit`: outbound text chunk size (chars).
-- `channels.nextcloud-talk.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking.
-- `channels.nextcloud-talk.blockStreaming`: disable block streaming for this channel.
-- `channels.nextcloud-talk.blockStreamingCoalesce`: block streaming coalesce tuning.
-- `channels.nextcloud-talk.mediaMaxMb`: inbound media cap (MB).

package/docs/channels/nostr.md

@@ -1,233 +0,0 @@
----
-summary: "Nostr DM channel via NIP-04 encrypted messages"
-read_when:
-  - You want Symi to receive DMs via Nostr
-  - You're setting up decentralized messaging
-title: "Nostr"
----
-
-# Nostr
-
-**Status:** Optional plugin (disabled by default).
-
-Nostr is a decentralized protocol for social networking. This channel enables Symi to receive and respond to encrypted direct messages (DMs) via NIP-04.
-
-## Install (on demand)
-
-### Onboarding (recommended)
-
-- The onboarding wizard (`symi onboard`) and `symi channels add` list optional channel plugins.
-- Selecting Nostr prompts you to install the plugin on demand.
-
-Install defaults:
-
-- **Dev channel + git checkout available:** uses the local plugin path.
-- **Stable/Beta:** downloads from npm.
-
-You can always override the choice in the prompt.
-
-### Manual install
-
-```bash
-symi plugins install @symi/nostr
-```
-
-Use a local checkout (dev workflows):
-
-```bash
-symi plugins install --link <path-to-symi>/extensions/nostr
-```
-
-Restart the Gateway after installing or enabling plugins.
-
-## Onboarding
-
-1. Generate a Nostr keypair (if needed):
-
-```bash
-# Using nak
-nak key generate
-```
-
-2. Add to config:
-
-```json
-{
-  "channels": {
-    "nostr": {
-      "privateKey": "${NOSTR_PRIVATE_KEY}"
-    }
-  }
-}
-```
-
-3. Export the key:
-
-```bash
-export NOSTR_PRIVATE_KEY="nsec1..."
-```
-
-4. Restart the Gateway.
-
-## Configuration
-
-| Key          | Type     | Default                                     | Description                         |
-| ------------ | -------- | ------------------------------------------- | ----------------------------------- |
-| `privateKey` | string   | required                                    | Private key in `nsec` or hex format |
-| `relays`     | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | Relay URLs (WebSocket)              |
-| `dmPolicy`   | string   | `pairing`                                   | DM access policy                    |
-| `allowFrom`  | string[] | `[]`                                        | Allowed sender pubkeys              |
-| `enabled`    | boolean  | `true`                                      | Enable/disable channel              |
-| `name`       | string   | -                                           | Display name                        |
-| `profile`    | object   | -                                           | NIP-01 profile metadata             |
-
-## Profile metadata
-
-Profile data is published as a NIP-01 `kind:0` event. You can manage it from the Control UI (Channels -> Nostr -> Profile) or set it directly in config.
-
-Example:
-
-```json
-{
-  "channels": {
-    "nostr": {
-      "privateKey": "${NOSTR_PRIVATE_KEY}",
-      "profile": {
-        "name": "symi",
-        "displayName": "Symi",
-        "about": "Personal assistant DM bot",
-        "picture": "https://example.com/avatar.png",
-        "banner": "https://example.com/banner.png",
-        "website": "https://example.com",
-        "nip05": "symi@example.com",
-        "lud16": "symi@example.com"
-      }
-    }
-  }
-}
-```
-
-Notes:
-
-- Profile URLs must use `https://`.
-- Importing from relays merges fields and preserves local overrides.
-
-## Access control
-
-### DM policies
-
-- **pairing** (default): unknown senders get a pairing code.
-- **allowlist**: only pubkeys in `allowFrom` can DM.
-- **open**: public inbound DMs (requires `allowFrom: ["*"]`).
-- **disabled**: ignore inbound DMs.
-
-### Allowlist example
-
-```json
-{
-  "channels": {
-    "nostr": {
-      "privateKey": "${NOSTR_PRIVATE_KEY}",
-      "dmPolicy": "allowlist",
-      "allowFrom": ["npub1abc...", "npub1xyz..."]
-    }
-  }
-}
-```
-
-## Key formats
-
-Accepted formats:
-
-- **Private key:** `nsec...` or 64-char hex
-- **Pubkeys (`allowFrom`):** `npub...` or hex
-
-## Relays
-
-Defaults: `relay.damus.io` and `nos.lol`.
-
-```json
-{
-  "channels": {
-    "nostr": {
-      "privateKey": "${NOSTR_PRIVATE_KEY}",
-      "relays": ["wss://relay.damus.io", "wss://relay.primal.net", "wss://nostr.wine"]
-    }
-  }
-}
-```
-
-Tips:
-
-- Use 2-3 relays for redundancy.
-- Avoid too many relays (latency, duplication).
-- Paid relays can improve reliability.
-- Local relays are fine for testing (`ws://localhost:7777`).
-
-## Protocol support
-
-| NIP    | Status    | Description                           |
-| ------ | --------- | ------------------------------------- |
-| NIP-01 | Supported | Basic event format + profile metadata |
-| NIP-04 | Supported | Encrypted DMs (`kind:4`)              |
-| NIP-17 | Planned   | Gift-wrapped DMs                      |
-| NIP-44 | Planned   | Versioned encryption                  |
-
-## Testing
-
-### Local relay
-
-```bash
-# Start strfry
-docker run -p 7777:7777 ghcr.io/hoytech/strfry
-```
-
-```json
-{
-  "channels": {
-    "nostr": {
-      "privateKey": "${NOSTR_PRIVATE_KEY}",
-      "relays": ["ws://localhost:7777"]
-    }
-  }
-}
-```
-
-### Manual test
-
-1. Note the bot pubkey (npub) from logs.
-2. Open a Nostr client (Damus, Amethyst, etc.).
-3. DM the bot pubkey.
-4. Verify the response.
-
-## Troubleshooting
-
-### Not receiving messages
-
-- Verify the private key is valid.
-- Ensure relay URLs are reachable and use `wss://` (or `ws://` for local).
-- Confirm `enabled` is not `false`.
-- Check Gateway logs for relay connection errors.
-
-### Not sending responses
-
-- Check relay accepts writes.
-- Verify outbound connectivity.
-- Watch for relay rate limits.
-
-### Duplicate responses
-
-- Expected when using multiple relays.
-- Messages are deduplicated by event ID; only the first delivery triggers a response.
-
-## Security
-
-- Never commit private keys.
-- Use environment variables for keys.
-- Consider `allowlist` for production bots.
-
-## Limitations (MVP)
-
-- Direct messages only (no group chats).
-- No media attachments.
-- NIP-04 only (NIP-17 gift-wrap planned).

package/docs/channels/pairing.md

@@ -1,100 +0,0 @@
----
-summary: "Pairing overview: approve who can DM you + which nodes can join"
-read_when:
-  - Setting up DM access control
-  - Pairing a new iOS/Android node
-  - Reviewing Symi security posture
-title: "Pairing"
----
-
-# Pairing
-
-“Pairing” is Symi’s explicit **owner approval** step.
-It is used in two places:
-
-1. **DM pairing** (who is allowed to talk to the bot)
-2. **Node pairing** (which devices/nodes are allowed to join the gateway network)
-
-Security context: [Security](/gateway/security)
-
-## 1) DM pairing (inbound chat access)
-
-When a channel is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.
-
-Default DM policies are documented in: [Security](/gateway/security)
-
-Pairing codes:
-
-- 8 characters, uppercase, no ambiguous chars (`0O1I`).
-- **Expire after 1 hour**. The bot only sends the pairing message when a new request is created (roughly once per hour per sender).
-- Pending DM pairing requests are capped at **3 per channel** by default; additional requests are ignored until one expires or is approved.
-
-### Approve a sender
-
-```bash
-symi pairing list telegram
-symi pairing approve telegram <CODE>
-```
-
-### Where the state lives
-
-Stored under `~/.symi/credentials/`:
-
-- Pending requests: `<channel>-pairing.json`
-- Approved allowlist store: `<channel>-allowFrom.json`
-
-Treat these as sensitive (they gate access to your assistant).
-
-## 2) Node device pairing (iOS/Android/macOS/headless nodes)
-
-Nodes connect to the Gateway as **devices** with `role: node`. The Gateway
-creates a device pairing request that must be approved.
-
-### Pair via Telegram (recommended for iOS)
-
-If you use the `device-pair` plugin, you can do first-time device pairing entirely from Telegram:
-
-1. In Telegram, message your bot: `/pair`
-2. The bot replies with two messages: an instruction message and a separate **setup code** message (easy to copy/paste in Telegram).
-3. On your phone, open the Symi iOS app → Settings → Gateway.
-4. Paste the setup code and connect.
-5. Back in Telegram: `/pair approve`
-
-The setup code is a base64-encoded JSON payload that contains:
-
-- `url`: the Gateway WebSocket URL (`ws://...` or `wss://...`)
-- `token`: a short-lived pairing token
-
-Treat the setup code like a password while it is valid.
-
-### Approve a node device
-
-```bash
-symi devices list
-symi devices approve <requestId>
-symi devices reject <requestId>
-```
-
-### Node pairing state storage
-
-Stored under `~/.symi/devices/`:
-
-- `pending.json` (short-lived; pending requests expire)
-- `paired.json` (paired devices + tokens)
-
-### Notes
-
-- The legacy `node.pair.*` API (CLI: `symi nodes pending/approve`) is a
-  separate gateway-owned pairing store. WS nodes still require device pairing.
-
-## Related docs
-
-- Security model + prompt injection: [Security](/gateway/security)
-- Updating safely (run doctor): [Updating](/install/updating)
-- Channel configs:
-  - Telegram: [Telegram](/channels/telegram)
-  - WhatsApp: [WhatsApp](/channels/whatsapp)
-  - Signal: [Signal](/channels/signal)
-  - BlueBubbles (iMessage): [BlueBubbles](/channels/bluebubbles)
-  - iMessage (legacy): [iMessage](/channels/imessage)
-  - Slack: [Slack](/channels/slack)