## Context

The Telegram integration reveals a clear pattern with 4 layers:

```
Layer 1: npm package        (@tiledesk/tiledesk-telegram-connector)
Layer 2: Server pubmodule   (pubmodules/telegram/index.js + listener.js)
Layer 3: Dashboard UI       (12+ files: constants, templates, integrations, assets)
Layer 4: Helm config        (values.yaml, configmap.yaml, server-deployment.yaml)
```

Three published connector npm packages on npm under `@tiledesk` were downloaded and analyzed:

| Package | Version | Size | Lines of code (index.js) | Status |
|---------|---------|------|--------------------------|--------|
| `@tiledesk/tiledesk-telegram-connector` | 0.1.15 | ~531KB | 805 | Published |
| `@tiledesk/tiledesk-whatsapp-connector` | 0.1.66 | ~39KB | 1720 | Published |
| `@tiledesk/tiledesk-messenger-connector` | 0.1.30 | ~25KB | 962 | Published |
| `@tiledesk/tiledesk-twilio-connector` | — | — | — | Not published on npm |

All three published connectors share the **exact same export pattern**:
```js
module.exports = { router: router, startApp: startApp }
```

The `startApp(settings, callback)` function takes the same settings object with `MONGODB_URL` and `API_URL` as mandatory fields, and the router exposes the same REST endpoints (`/detail`, `/configure`, `/install`, `/uninstall`, `/update`, inbound/outbound message handlers).

Key differences found across implementations:
- **KVBaseMongo constructor API**: Telegram uses `new KVBaseMongo({KVBASE_COLLECTION, log})` (config object), WhatsApp/Messenger use `new KVBaseMongo(collectionName)` (string)
- **Custom lead_id prefix**: Telegram sets `_id: 'telegram-' + channel.from`, WhatsApp/Messenger have the equivalent code COMMENTED OUT
- **Translator classes**: Each has its own translator (TiledeskTelegramTranslator, TiledeskWhatsappTranslator, TiledeskMessengerTranslator) — this is the provider-specific logic
- **Channel client**: Each has its own API client (TiledeskTelegram, TiledeskWhatsapp, FacebookClient)
- **MessageHandler**: Shared across all three — same file, same logic
- **Helm env vars**: Telegram needs custom env vars (TELEGRAM_API_URL, TELEGRAM_FILE_URL). WhatsApp/Messenger don't need provider-specific env vars (they use the Twilio/Facebook config from the connector's own configuration form)

The common kernel (KVBaseMongo, TiledeskAppsClient, TiledeskSubscriptionClient, TiledeskChannel, MessageHandler) could be extracted into a shared library, leaving only the translator and API client as per-channel code.

## Goals / Non-Goals

**Goals:**
- Document all integration points for a new channel across the 4 layers
- Catalog existing connector packages with detailed comparison of what's common vs provider-specific
- Create a universal step-by-step guide that works for any channel
- Include code snippets, file paths, and configuration templates
- Highlight which parts can be copied verbatim vs which need custom implementation

**Non-Goals:**
- Implementing a specific channel
- Modifying any existing code
- Creating a shared library (document the pattern, don't refactor)

## Decisions

### Decision: Document as a single markdown manual
A single `docs/adding-new-channel-guide.md` file with clear sections per layer plus a comparison table of existing connectors.

### Decision: Include detailed connector comparison
The manual will include a comparison section with file structure diff, common patterns, and provider-specific code for each existing connector.

## Risks / Trade-offs

- **[Outdated connectors]** → WhatsApp is at v0.1.66 and actively maintained. Telegram at 0.1.15 and Messenger at 0.1.30 are older. Versions may change, but the core pattern is stable.
- **[KVBaseMongo API differences]** → Telegram uses a config object, others use a string. The manual should recommend the modern pattern (config object) for new channels.
- **[Dashboard integration UI may change]** → Focus on the stable integration points (constants, templates, config).