docs(newwhats): contrato de integração Motor ↔ Satélite (auditoria + plano)

Documenta o contrato bidirecional (ext-api A: satélite→motor; webhook + /nw/* B:
motor→satélite), config, recursos do satélite (transcrição/sync-knowledge) e o
estado faseado da sincronização (contrato + alias numbers feitos; config,
sync-knowledge e2e e mover-recursos pendentes).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

projetos/newwhats.clube67.com/integracao-satelites.md

@@ -0,0 +1,50 @@
+# newwhats.clube67.com — Contrato de integração Motor ↔ Satélite
+
+> O **motor** (newwhats) expõe a plataforma WhatsApp + Secretária IA; cada
+> **satélite** (ex.: mercado.clube67.com / "Alemão Conveniências", plugin
+> `newwhats` v2.1.0) consome o motor e fornece dados do seu negócio.
+> Fonte da verdade do contrato (auditado em 28/jun/2026).
+
+## Config do satélite (plugin_configs, manifest `newwhats`)
+`newwhats_url` (URL do motor) · `integration_key` (x-nw-key, rotas `/nw/*`) ·
+`api_token` (Bearer, envio de mensagens) · `webhook_secret` (HMAC do webhook).
+
+## Contrato A — Satélite → Motor (ext-api `/api/ext/v1/*`)
+| Satélite chama | Motor (ext-api) | Status |
+|---|---|---|
+| `inbox`, `inbox/:chatId/messages`, `inbox/:chatId/send` | idem | ✅ |
+| `media/:messageId` | `media/:messageId` | ✅ |
+| `stream` (WS) | `stream` | ✅ |
+| `secretaria/ask` | `secretaria/ask` (routes.ts) | ✅ |
+| `secretaria/numbers` | **alias adicionado** → `sec_numbers` | ✅ (corrigido) |
+| `secretaria/*` interno (`sync-knowledge`) | `/api/secretaria/*` (plugin) | ✅ |
+
+> Demais dados da Secretária no ext-api ficam sob `/sec/*` (`sec/agent`,
+> `sec/nodes`, `sec/slots`, `sec/conversations`, `sec/keys`, `sec/handoff`).
+
+## Contrato B — Motor → Satélite
+| Mecanismo | Satélite | Auth |
+|---|---|---|
+| Webhook `POST /api/webhook/newwhats` (`message.new`, `session.status`) | `webhook-receiver.js` | HMAC `webhook_secret` |
+| Secretária consulta `/nw/*` (`/cliente`, `/clube`, `/parceiros`, `/promocoes`, `/sorteio`, `/vagas`, `/ping`) | `routes.js` | `integration_key` (timingSafeEqual) |
+
+## O que o satélite já faz (e poderia migrar ao motor)
+- `media-transcribe.js`: transcrição de áudio + descrição de imagem via Gemini
+  (cache Redis, fallback Whisper). **Hoje só no satélite** → candidato a ir ao motor.
+- `sync-knowledge.js`: monta o nó de conhecimento com dados reais e envia ao motor.
+- `smart-router.js` (roteamento sem LLM), `personas.js`, `follow-up-detector.js`,
+  `context-builder.js` (contexto local do negócio).
+
+## Estado da sincronização (faseado)
+1. ✅ **Contrato documentado** (este arquivo).
+2. ✅ **Compatibilidade de API**: alias `GET /secretaria/numbers` no ext-api do
+   motor (retrocompatível) — fecha o gap do `webhook-receiver`. (commit motor)
+3. ⏳ **Config/conexão**: validar `newwhats_url`/keys do satélite apontando para o
+   motor correto (dev/prod) e o HMAC do webhook. *(requer credenciais reais.)*
+4. ⏳ **Conhecimento**: rodar `sync-knowledge` end-to-end (satélite → motor).
+5. ⏳ **Mover recursos**: transcrição/memória para o motor (genéricos a todos os
+   satélites); satélite passa a só enviar contexto. Ver `secretaria-ia-evolucao.md`.
+
+## Inconsistência anotada
+A transcrição no satélite usa `process.env.GEMINI_API_KEY`; o RAG/memória do motor
+usa `cfg.gemini_key` (config do plugin). Unificar a fonte da chave ao migrar.