@lionchat/mcp-server 0.3.1 → 0.3.2

package/dist/docs/instructions.md

@@ -153,6 +153,12 @@ Quando precisar de detalhes profundos, leia um destes documents via `resources/r
 - `lionchat://docs/data-model` — Modelo de dados detalhado, FKs, índices
 - `lionchat://docs/reports-guide` — Como interpretar cada um dos 19 endpoints de relatório
 - `lionchat://docs/api-conventions` — Auth, paginação, filtros, errors, rate limits
+- `lionchat://docs/conversation-flows` — Ciclo de vida de uma conversa (criação, auto-assignment, IA, resolução)
+- `lionchat://docs/kanban-deep-dive` — Estrutura completa do Kanban (Funnel/Stage/Item/pipeline)
+- `lionchat://docs/best-practices` — Como economizar tokens, evitar rate limit, ordem de operações
+- `lionchat://docs/troubleshooting` — Códigos HTTP, erros comuns, debugging
+- `lionchat://docs/flowbuilder-design-guide` — **OBRIGATÓRIO** antes de criar/editar fluxo: schema de nodes, handles expostos por tipo, layout/positioning, erros comuns, checklist
+- `lionchat://docs/flowbuilder-patterns` — 10 templates de fluxos prontos pra adaptar (saudação, captura, qualificação, CSAT, IA, etc)
 
 ## 9. Prompts pré-prontos (workflows automatizados)
 
@@ -162,6 +168,24 @@ O usuário pode invocar via slash command (`/nome_do_prompt`):
 - `stuck_leads` — Leads parados há N dias no Kanban
 - `weekly_recap` — Resumo da semana
 - `customer_health` — Saúde completa de 1 cliente (conversas + Kanban + CSAT)
+- `inactive_contacts` — Contatos sem interação pra reativação
+- `team_load_balance` — Carga e distribuição da equipe
+- `quality_audit` — Auditoria de qualidade de conversas resolvidas
+- `whatsapp_template_usage` — Uso e performance de templates WhatsApp
+- `create_flow_brainstorm` — Banco de perguntas pra descobrir o que o cliente quer ANTES de criar um fluxo
+
+### Regras específicas para criação de FlowBuilder
+
+Quando o cliente pedir pra criar um fluxo:
+
+1. **Antes de gerar JSON**, avalie se você tem informação suficiente. Se faltar (canal, gatilho, conteúdo, ramificações), use o prompt `create_flow_brainstorm` como **guia de perguntas sugeridas** — escolha só as relevantes pro caso, não force checklist
+2. Fluxo simples (1-3 nodes, sem ramificação) → 2-3 perguntas bastam
+3. Fluxo complexo (5+ nodes, IA, API externa, várias ramificações) → vale aprofundar
+4. **SEMPRE consulte** `lionchat://docs/flowbuilder-design-guide` antes de chamar `flows_create` (schema, handles, layout)
+5. **SEMPRE verifique** se algum template em `lionchat://docs/flowbuilder-patterns` já resolve o caso — adaptar é mais seguro do que criar do zero
+6. **NUNCA crie** nodes sem `position: {x, y}` — eles ficam empilhados no canvas
+7. **NUNCA invente** `sourceHandle` — use só os listados no design guide por tipo de node (ex: condition usa `cond_0`/`cond_1`/`default`, não IDs livres)
+8. Antes de chamar `flows_create`, apresente um resumo em **linguagem natural** do que vai criar e confirme com o cliente
 
 ## 10. Idioma das respostas
 

package/dist/docs/prompts/create_flow_brainstorm.json

@@ -0,0 +1,9 @@
+{
+  "name": "create_flow_brainstorm",
+  "title": "Perguntas sugeridas para criar um FlowBuilder",
+  "description": "Banco de perguntas para descobrir o que o cliente quer ANTES de gerar o flow_data. Use APENAS as perguntas relevantes pro caso — nao force checklist. Fluxo simples (1-3 nodes) precisa de 2-3 perguntas no maximo; fluxo complexo (5+ nodes, ramificacoes, IA, API) vale aprofundar. Sempre consulte o resource lionchat://docs/flowbuilder-design-guide e lionchat://docs/flowbuilder-patterns antes de gerar o JSON.",
+  "arguments": [
+    { "name": "goal_hint", "description": "O que o cliente ja disse que quer (ex: 'fluxo de captura de lead')", "required": false }
+  ],
+  "template": "Cliente quer criar um fluxo no FlowBuilder do LionChat.\n\nObjetivo declarado: {{goal_hint|Nao informado}}\n\nINSTRUCAO: avalie o que o cliente JA disse e o que ainda falta saber. Pergunte SO o que falta. Nao force checklist. Em fluxo simples, 2-3 perguntas bastam. Em fluxo complexo, aprofunde.\n\nABAIXO esta o BANCO de perguntas sugeridas por categoria. ESCOLHA SO AS RELEVANTES.\n\n## Categoria A — Proposito e gatilho (quase sempre necessario)\n- Qual o objetivo do fluxo? (saudacao, qualificacao, captura, suporte, pos-venda, CSAT, agendamento, re-engajamento, outro)\n- Quando dispara? (mensagem recebida com palavra-chave, conversa criada, conversa resolvida, label aplicada, cron, webhook externo)\n- Se palavra-chave: quais palavras? Match exact ou contains?\n\n## Categoria B — Canal e escopo\n- Em qual canal vai rodar? (WAHA, WhatsApp Cloud, Webwidget, Telegram, Email, Twitter, Facebook, Instagram, Line, SMS, API, Voz, WhatsApp Business)\n- Em qual(is) inbox(es) especifica(s)? (peca o ID via inboxes_list se nao soube)\n- Tem filtro de quem entra? (so leads novos, so clientes existentes, so quem tem label X)\n\n## Categoria C — Conteudo da conversa\n- Vai mandar quais mensagens? Texto livre, templates WhatsApp aprovados, midia (imagem/audio/video), lista de botoes interativos?\n- Vai fazer perguntas pro cliente? Quantas? Quais?\n- Para cada pergunta: aceita qualquer resposta livre, opcoes fixas (ex: 1/2/3), ou regex (ex: CPF, email, telefone)?\n- Quanto tempo espera por cada resposta? (default sensato: 30-60 min)\n- O que mandar se nao responder no tempo? (mensagem de timeout, encerrar, escalar pra humano)\n\n## Categoria D — Captura, ramificacao e logica\n- Onde salva as respostas? Em variavel temporaria do flow, atributo da conversa, atributo do contato, custom_attributes\n- Tem ramificacao por condicao? Quais criterios? (ex: 'se valor > 1000 vai pra time premium')\n- Vai chamar API externa? (URL, metodo, headers, body, autenticacao)\n- Vai usar IA (Captain Assistant)? Em que momento? Pra que?\n  * generate = gerar resposta natural\n  * intent = classificar intencao da mensagem\n  * sentiment = analisar sentimento\n  * extract = extrair info estruturada (CPF, valor, etc)\n- Tem teste A/B? (randomizer)\n\n## Categoria E — Acoes finais\n- No fim do fluxo: criar card no Kanban? (em qual funil/etapa?) Atribuir agente/time? (ID) Adicionar/remover label? Mudar status/prioridade? Disparar webhook externo?\n- Tem criterio pra encerrar antes? (exit_conditions: ex: 'conversa marcada como resolvida' ou 'label X aplicada')\n\n## Antes de chamar flows_create\n1. Se faltou info CRITICA (ex: canal, gatilho, conteudo basico): pergunte agora\n2. Se a info que falta e mero detalhe: assuma defaults sensatos\n   - maxRetries: 3\n   - waitTime: 60min para resposta, 30min para timeouts\n   - sem ramificacao se cliente nao mencionou\n3. Apresente um RESUMO em linguagem natural do fluxo. Exemplo: 'Beleza, vou criar um fluxo assim: quando alguem mandar oi no WhatsApp, manda saudacao, pergunta se quer vendas/suporte, se vendas atribui ao time 1, se suporte ao time 2. Confirma?'\n4. Espere o cliente confirmar OU pedir ajustes\n5. So depois da confirmacao, chame flows_create\n6. ANTES de gerar o JSON: consulte lionchat://docs/flowbuilder-design-guide pra schema/handles/layout e lionchat://docs/flowbuilder-patterns pra ver se algum template ja resolve\n7. Apos gerar JSON, valide pelo checklist da secao 6 do design guide\n8. NUNCA crie node sem position. NUNCA invente sourceHandle.\n\nDEFAULTS SENSATOS quando cliente nao especificar:\n- channel_type: pergunte sempre, nao chute\n- inbox_ids: pergunte sempre\n- waitTime: 60 minutes\n- maxRetries: 3\n- waitUnit: minutes\n- saveTo: 'attribute' (conversa) na duvida\n- match_mode: 'contains' pra keywords"
+}

package/dist/docs/resources/flowbuilder-design-guide.md

@@ -0,0 +1,427 @@
+# FlowBuilder — Guia de Design
+
+Como criar fluxos do LionChat (FlowBuilder) que abrem certinhos no canvas, sem nodes empilhados, sem edges quebradas, sem campos inventados. Consulte sempre que for chamar `flows_create` ou `flows_update`.
+
+---
+
+## 1. Decisão de node — qual usar pra cada caso
+
+| Cliente quer | Use o node | NÃO use |
+|---|---|---|
+| Mandar mensagem (texto, template WhatsApp, áudio, imagem, lista de botões) | `send_message` | `action` pra mandar mensagem |
+| Esperar resposta com opções fixas (1, 2, 3) | `wait_response` com `validation: 'options'` | `condition` depois — o próprio wait_response roteia pelas opções |
+| Esperar resposta livre | `wait_response` com `validation: 'any'` | - |
+| Validar CPF/email/telefone | `wait_response` com `validation: 'regex'` | `condition` com regex |
+| Ramificar por valor de variável/atributo | `condition` | `wait_response` |
+| Atribuir agente, time, label, status, prioridade, kanban, captain | `action` com `key` específica | - |
+| Chamar API externa | `api` | `action` (não tem chamada HTTP genérica) |
+| Esperar X tempo | `wait` | - |
+| Esperar "segunda-feira às 9h" | `wait` com `waitUnit: 'weekday'` | `condition` por horário |
+| Salvar valor calculado em variável | `set_variable` | `action` |
+| Gerar resposta com IA | `ai` mode `generate` | - |
+| Extrair info da mensagem (ex: pegar valor numérico) | `ai` mode `extract` | regex no wait_response |
+| Classificar intenção da mensagem | `ai` mode `intent` | - |
+| Analisar sentimento | `ai` mode `sentiment` | - |
+| Encerrar fluxo no meio | `action` com `key: 'deactivate_flow'` OU `exit_conditions` no nível do flow | - |
+| Distribuir aleatório entre branches | `randomizer` | - |
+| Atualizar info de grupo WhatsApp (WAHA) | `update_group` | - |
+| Iniciar outro fluxo | `action` com `key: 'start_flow'` OU node `activate_flow` | - |
+
+---
+
+## 2. Schema válido por tipo de node
+
+Todo node tem essa estrutura base:
+
+```json
+{
+  "id": "uuid-ou-string-unica",
+  "type": "<tipo do node>",
+  "position": { "x": 0, "y": 0 },
+  "data": { "...": "campos específicos do tipo" }
+}
+```
+
+### 2.1 `start`
+
+```json
+{
+  "id": "node-start",
+  "type": "start",
+  "position": { "x": 50, "y": 300 },
+  "data": {
+    "label": "Início",
+    "triggers": [
+      { "type": "message_received", "keywords": ["oi", "ola"], "match_mode": "contains" }
+    ]
+  }
+}
+```
+
+**Triggers válidos:** `message_received`, `conversation_created`, `conversation_resolved`, `label_added`, `label_removed`, `cron`, `webhook`.
+
+**Handles que SAEM:** `success`.
+
+### 2.2 `send_message`
+
+```json
+{
+  "id": "node-send-1",
+  "type": "send_message",
+  "position": { "x": 370, "y": 300 },
+  "data": {
+    "label": "Boas-vindas",
+    "messageItems": [
+      { "id": "m1", "type": "text", "content": "Oi {{contact.name}}! Como posso ajudar?" },
+      { "id": "m2", "type": "delay", "seconds": 2 },
+      { "id": "m3", "type": "whatsapp_template", "templateId": 123, "params": ["valor1"] }
+    ]
+  }
+}
+```
+
+**Tipos de item válidos:** `text`, `whatsapp_template` (ou `template`), `canned_response`, `user_input` (lista de botões interativos), `delay`, `attachment`, `audio`.
+
+**ATENÇÃO:** usa `messageItems` (NÃO `items`).
+
+**Handles que SAEM:** `success`, `no_response` (quando tem `user_input` com timeout), `error`.
+
+### 2.3 `wait_response`
+
+```json
+{
+  "id": "node-wait-1",
+  "type": "wait_response",
+  "position": { "x": 690, "y": 300 },
+  "data": {
+    "label": "Pergunta menu",
+    "waitTime": 60,
+    "waitUnit": "minutes",
+    "validation": "options",
+    "acceptedOptions": ["1", "2", "3"],
+    "invalidMessage": "Por favor responda com 1, 2 ou 3",
+    "maxRetries": 3,
+    "saveTo": "attribute",
+    "saveAttrKey": "escolha_menu"
+  }
+}
+```
+
+**`validation` válidos:** `any`, `options`, `regex`.
+
+**`saveTo` válidos:** `variable` (variável temporária do flow), `attribute` (custom_attributes da CONVERSA), `contact_attribute` (custom_attributes do CONTATO), `""` (não salva).
+
+**Handles que SAEM dependem da validation:**
+- `validation: 'any'` → `success`, `timeout`
+- `validation: 'options'` → `option_<valor>` para cada valor em `acceptedOptions` (ex: `option_1`, `option_2`, `option_sim`) + `timeout`
+- `validation: 'regex'` → `success`, `timeout`
+
+**REGRA:** depois de wait_response com options, NUNCA coloque node `condition` pra ramificar — ligue os edges direto nos handles `option_X`.
+
+### 2.4 `condition`
+
+```json
+{
+  "id": "node-cond-1",
+  "type": "condition",
+  "position": { "x": 1010, "y": 300 },
+  "data": {
+    "label": "Tipo de cliente",
+    "conditions": [
+      { "id": "c1", "label": "VIP", "field": "contact.custom_attributes.plano", "operator": "equal", "value": "premium" },
+      { "id": "c2", "label": "Padrão", "field": "contact.custom_attributes.plano", "operator": "equal", "value": "standard" }
+    ]
+  }
+}
+```
+
+**Operadores válidos:** `equal` (ou `field_equals`), `not_equal`, `contains`, `not_contains`, `starts_with`, `ends_with`, `greater_than`, `less_than`, `is_present`, `is_blank`, `regex`.
+
+**Handles que SAEM:** `cond_0`, `cond_1`, `cond_2`, ... (UM POR CONDIÇÃO, pela ordem do array — NÃO use o `id` da condição) + `default` (quando nenhuma bate).
+
+**ATENÇÃO:** o handle é `cond_INDEX` baseado na posição no array, NÃO o `id` da condição. Se você definir `conditions[0].id = "vip"`, mesmo assim o handle é `cond_0`.
+
+### 2.5 `action`
+
+```json
+{
+  "id": "node-action-1",
+  "type": "action",
+  "position": { "x": 1330, "y": 300 },
+  "data": {
+    "label": "Finalizar atendimento",
+    "items": [
+      { "key": "assign_team", "config": { "team_id": 5 } },
+      { "key": "add_label", "config": { "labels": ["lead-qualificado"] } },
+      { "key": "create_kanban_item", "config": { "funnel_id": 3, "funnel_stage": "novo_lead" } }
+    ]
+  }
+}
+```
+
+**ATENÇÃO:** items usa `config` (NÃO `params`).
+
+**Keys de action válidas:**
+
+| Key | config esperado | Efeito |
+|---|---|---|
+| `assign_agent` | `{ agent_id }` | Atribui agente humano à conversa |
+| `assign_team` | `{ team_id }` | Atribui time |
+| `change_status` | `{ status: 'open' \| 'resolved' \| 'pending' \| 'snoozed' }` | Muda status da conversa |
+| `change_priority` | `{ priority: 'urgent' \| 'high' \| 'medium' \| 'low' }` | Muda prioridade |
+| `add_label` | `{ labels: ['slug1', 'slug2'] }` | Adiciona labels |
+| `remove_label` | `{ labels: ['slug'] }` | Remove labels |
+| `mute_conversation` | `{}` | Silencia notificações |
+| `add_private_note` | `{ content: 'texto' }` | Adiciona nota interna |
+| `create_kanban_item` | `{ funnel_id, funnel_stage, item_details? }` | Cria card no Kanban |
+| `move_kanban_item_to_stage` | `{ funnel_stage }` | Move card (precisa ter card vinculado) |
+| `move_kanban_stage` | `{ funnel_id, funnel_stage }` | Idem |
+| `set_kanban_item_status` | `{ status: 'won' \| 'lost' \| 'active' }` | Marca status do card |
+| `set_won` | `{}` | Atalho pra ganho |
+| `set_lost` | `{ reason? }` | Atalho pra perdido |
+| `assign_agent_card` | `{ agent_id }` | Atribui agente ao card |
+| `add_card_note` | `{ content }` | Nota no card |
+| `send_webhook` | `{ url, headers?, body? }` | Dispara webhook externo |
+| `start_flow` | `{ flow_id }` | Inicia outro fluxo |
+| `deactivate_flow` ou `disable_flow` | `{}` | Encerra fluxo atual |
+| `update_attribute` | `{ entity: 'contact'\|'conversation'\|'card', key, value }` | Seta custom_attribute |
+| `assign_captain` (ou `assign_captain_assistant`) | `{ assistant_id }` | Atribui IA Captain |
+| `deactivate_captain` | `{}` | Tira a IA da conversa |
+
+**Handles que SAEM:** `success`. Não tem handle `error` — falhas viram warning silencioso e o flow continua.
+
+### 2.6 `api`
+
+```json
+{
+  "id": "node-api-1",
+  "type": "api",
+  "position": { "x": 1330, "y": 480 },
+  "data": {
+    "label": "Consulta CRM externo",
+    "method": "POST",
+    "url": "https://api.example.com/leads",
+    "headers": [
+      { "key": "Authorization", "value": "Bearer {{env.CRM_TOKEN}}" },
+      { "key": "Content-Type", "value": "application/json" }
+    ],
+    "body": "{\"name\":\"{{contact.name}}\",\"email\":\"{{contact.email}}\"}",
+    "apiResponseVar": "crm_response"
+  }
+}
+```
+
+**Handles que SAEM:** `success`, `error`.
+
+### 2.7 `ai`
+
+```json
+{
+  "id": "node-ai-1",
+  "type": "ai",
+  "position": { "x": 1010, "y": 300 },
+  "data": {
+    "label": "Classifica intenção",
+    "aiMode": "intent",
+    "aiPrompt": "Classifique a intenção da última mensagem como: compra, suporte, reclamacao ou outro",
+    "aiIntentOptions": ["compra", "suporte", "reclamacao", "outro"],
+    "aiResponseVar": "intent_result"
+  }
+}
+```
+
+**`aiMode` válidos:** `generate`, `intent`, `sentiment`, `extract`.
+
+**Handles que SAEM dependem do mode:**
+- `generate` → `success`, `error`
+- `intent` → uma saída por opção em `aiIntentOptions` (ex: `intent_compra`, `intent_suporte`) + `error`
+- `sentiment` → `positive`, `negative`, `neutral` + `error`
+- `extract` → `success`, `error` (resultado salvo em `aiResponseVar`)
+
+### 2.8 `wait`
+
+```json
+{
+  "id": "node-wait-time-1",
+  "type": "wait",
+  "position": { "x": 690, "y": 300 },
+  "data": {
+    "label": "Espera 10 min",
+    "waitTime": 10,
+    "waitUnit": "minutes"
+  }
+}
+```
+
+**`waitUnit` válidos:** `seconds`, `minutes`, `hours`, `days`, `weekday` (espera próximo dia da semana).
+
+Pra `weekday`, use também `targetWeekday` (0=domingo, 1=segunda... 6=sábado) e `targetHour` (0-23).
+
+**Handles que SAEM:** `success`.
+
+### 2.9 `set_variable`
+
+```json
+{
+  "id": "node-setvar-1",
+  "type": "set_variable",
+  "position": { "x": 370, "y": 300 },
+  "data": {
+    "label": "Define contexto",
+    "variables": [
+      { "name": "origem_lead", "value": "Facebook Ads" },
+      { "name": "score", "value": "{{contact.custom_attributes.lead_score}}" }
+    ]
+  }
+}
+```
+
+**Handles que SAEM:** `success`.
+
+### 2.10 `randomizer`
+
+```json
+{
+  "id": "node-rand-1",
+  "type": "randomizer",
+  "position": { "x": 690, "y": 300 },
+  "data": {
+    "label": "A/B test mensagem",
+    "mode": "branches",
+    "branches": [
+      { "id": "A", "label": "Variante A", "weight": 50 },
+      { "id": "B", "label": "Variante B", "weight": 50 }
+    ]
+  }
+}
+```
+
+**Handles que SAEM:** o `id` de cada branch (`A`, `B`, ...). Em `mode: 'distribute_agents'` é `success`.
+
+### 2.11 `update_group` (WAHA apenas)
+
+Atualiza nome/descrição/foto de grupo WhatsApp. Use só quando flow roda em inbox WAHA e a conversa for de grupo.
+
+**Handles que SAEM:** `success`, `error`.
+
+### 2.12 `activate_flow`
+
+```json
+{
+  "id": "node-act-1",
+  "type": "activate_flow",
+  "position": { "x": 1010, "y": 300 },
+  "data": { "label": "Inicia flow B", "flow_id": 42 }
+}
+```
+
+**Handles que SAEM:** `success`, `error`.
+
+---
+
+## 3. Edges
+
+```json
+{
+  "id": "edge-1",
+  "source": "node-start",
+  "target": "node-send-1",
+  "sourceHandle": "success",
+  "type": "deletable",
+  "animated": true
+}
+```
+
+**REGRAS:**
+- `sourceHandle` é OBRIGATÓRIO em todo edge
+- Tem que casar com um handle que o node `source` EFETIVAMENTE EXPÕE (ver tabelas acima)
+- `id`: usar formato `edge-N` ou `e<source>-<target>`
+- `type: 'deletable'` e `animated: true` são os defaults visuais
+
+**Handles INVENTADOS quebram o flow.** Exemplos do que NÃO usar:
+- `c1`, `c2`, `c3` (use `cond_0`, `cond_1`)
+- `branch1`, `branchA` (no condition; use `cond_X`)
+- `out`, `output`, `next` (use o nome real do handle)
+- `option1` sem underscore (use `option_1`)
+
+---
+
+## 4. Layout e positioning
+
+Sem `position`, todos os nodes empilham no (0,0). Sempre informe.
+
+### Regras de espaçamento
+
+| Direção | Valor |
+|---|---|
+| Espaço horizontal entre nodes sequenciais | **+320** em X |
+| Espaço vertical entre branches paralelos | **+150** em Y (2 ramos), **+180** (3 ramos), **+150** cada (4+) |
+| Y do node start | **300** (ponto médio) |
+
+### Exemplo de layout
+
+Fluxo linear de 4 nodes:
+```
+(50, 300) → (370, 300) → (690, 300) → (1010, 300)
+```
+
+Fluxo com 1 wait_response 3 opções:
+```
+                                       (1330, 120)  -> option_1
+                                              ↑
+(50,300) → (370,300) → (690,300) → wait → (1330, 300)  -> option_2
+                                              ↓
+                                       (1330, 480)  -> option_3
+```
+
+Cada branch continua em seu próprio Y, X avança normal:
+```
+option_1 path: (1330, 120) → (1650, 120) → (1970, 120)
+option_2 path: (1330, 300) → (1650, 300) → (1970, 300)
+option_3 path: (1330, 480) → (1650, 480) → (1970, 480)
+```
+
+### Regra importante
+
+Nodes nunca devem ficar com a mesma coordenada `(x, y)`. Se dois nodes têm posição idêntica, eles SOBREPÕEM visualmente no canvas.
+
+---
+
+## 5. Erros comuns (lista negra)
+
+| Erro | Por que quebra | Forma certa |
+|---|---|---|
+| `items` no send_message | Schema usa `messageItems` | `messageItems: [...]` |
+| `items[].params` no action | Schema usa `config` | `items: [{ key, config: {...} }]` |
+| Falta `position` em algum node | Nodes empilham no canvas | Sempre `position: {x, y}` |
+| `sourceHandle: "c1"` ou `"vip"` no condition | Não existem | `"cond_0"`, `"cond_1"`, etc |
+| Node `condition` depois de `wait_response` com options | Redundante e atrapalha | Ligue `option_X` direto no próximo node |
+| Edge sem `sourceHandle` | Frontend não consegue rotear | Sempre informe |
+| Edge com `target` apontando pra ID que não existe | Quebra o grafo | Confira que `target` está em `nodes[]` |
+| `channel_type: "WhatsApp"` | Precisa do nome de classe Rails | `"Channel::Whatsapp"`, `"Channel::Waha"`, `"Channel::WebWidget"` |
+| `validation: "option"` (singular) | Não existe | `"options"` (plural) |
+| `waitTime: "60"` (string) | Espera Integer | `waitTime: 60` |
+| `inbox_ids` aninhado em `{flow:{...}}` | No MCP, achata-se sozinho | Passa `inbox_ids: [1, 2]` no nível raiz |
+| Mais de 1 node `start` | Flow precisa ter exatamente 1 ponto de entrada | Só 1 |
+| Node sem edge entrando (exceto start) | Node nunca executa | Confira que todo node não-start tem ao menos 1 edge target apontando pra ele |
+| `flow_data` sem `nodes` ou sem `edges` | Estrutura inválida | Inclua sempre, mesmo que `edges: []` |
+
+---
+
+## 6. Checklist pre-submit
+
+Antes de chamar `flows_create` ou `flows_update`, valide mentalmente:
+
+- [ ] Existe exatamente 1 node `type: 'start'`
+- [ ] Todo node tem `id` único
+- [ ] Todo node tem `type` válido (lista da seção 1)
+- [ ] Todo node tem `position: { x: <int>, y: <int> }`
+- [ ] Nenhum par de nodes tem a mesma posição `(x, y)`
+- [ ] Todo node tem `data` com campos do schema do tipo
+- [ ] Todo node não-start tem pelo menos 1 edge chegando (`edge.target = node.id`)
+- [ ] Todo edge tem `source`, `target` e `sourceHandle`
+- [ ] Todo `sourceHandle` é um handle real exposto pelo node source (seção 2)
+- [ ] `channel_type` é classe Rails (`Channel::Waha` etc)
+- [ ] `inbox_ids` (se enviado) tem inboxes do mesmo `channel_type`
+- [ ] Não tem `condition` redundante depois de `wait_response` com options
+- [ ] Layout: nodes em ordem visual da esquerda pra direita, sem sobreposição

package/dist/docs/resources/flowbuilder-patterns.md

@@ -0,0 +1,362 @@
+# FlowBuilder — Templates Prontos
+
+10 padrões testados para você adaptar em vez de criar do zero. Cada um já vem com layout válido, handles certos e campos no formato esperado. **Copie o `flow_data`, ajuste só o que o cliente pediu, e chame `flows_create`.**
+
+---
+
+## 1. Boas-vindas com triagem
+
+**Caso:** lead nova chega no WhatsApp, oferece menu (vendas/suporte/financeiro), atribui ao time certo.
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "conversation_created" }] } },
+    { "id": "n2", "type": "send_message", "position": { "x": 370, "y": 300 }, "data": { "label": "Saudação", "messageItems": [
+      { "id": "m1", "type": "text", "content": "Oi {{contact.name|default:'tudo bem?'}} 👋 Como posso ajudar hoje?\n\n1️⃣ Vendas\n2️⃣ Suporte\n3️⃣ Financeiro" }
+    ] } },
+    { "id": "n3", "type": "wait_response", "position": { "x": 690, "y": 300 }, "data": {
+      "label": "Aguarda escolha", "waitTime": 30, "waitUnit": "minutes", "validation": "options",
+      "acceptedOptions": ["1","2","3"], "invalidMessage": "Por favor responda 1, 2 ou 3", "maxRetries": 2, "saveTo": ""
+    } },
+    { "id": "n4", "type": "action", "position": { "x": 1010, "y": 120 }, "data": { "label": "→ Vendas", "items": [
+      { "key": "assign_team", "config": { "team_id": 1 } },
+      { "key": "add_label", "config": { "labels": ["vendas"] } }
+    ] } },
+    { "id": "n5", "type": "action", "position": { "x": 1010, "y": 300 }, "data": { "label": "→ Suporte", "items": [
+      { "key": "assign_team", "config": { "team_id": 2 } },
+      { "key": "add_label", "config": { "labels": ["suporte"] } }
+    ] } },
+    { "id": "n6", "type": "action", "position": { "x": 1010, "y": 480 }, "data": { "label": "→ Financeiro", "items": [
+      { "key": "assign_team", "config": { "team_id": 3 } },
+      { "key": "add_label", "config": { "labels": ["financeiro"] } }
+    ] } },
+    { "id": "n7", "type": "send_message", "position": { "x": 1330, "y": 660 }, "data": { "label": "Timeout msg", "messageItems": [
+      { "id": "m2", "type": "text", "content": "Não recebi sua resposta. Vou encaminhar pra equipe geral." }
+    ] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e3", "source": "n3", "target": "n4", "sourceHandle": "option_1", "type": "deletable", "animated": true },
+    { "id": "e4", "source": "n3", "target": "n5", "sourceHandle": "option_2", "type": "deletable", "animated": true },
+    { "id": "e5", "source": "n3", "target": "n6", "sourceHandle": "option_3", "type": "deletable", "animated": true },
+    { "id": "e6", "source": "n3", "target": "n7", "sourceHandle": "timeout", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## 2. Captura de lead simples
+
+**Caso:** pega nome + email + interesse, cria card no funil "Novos Leads".
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "conversation_created" }] } },
+    { "id": "n2", "type": "send_message", "position": { "x": 370, "y": 300 }, "data": { "label": "Pede nome", "messageItems": [
+      { "id": "m1", "type": "text", "content": "Olá! Antes de continuar, qual seu nome completo?" }
+    ] } },
+    { "id": "n3", "type": "wait_response", "position": { "x": 690, "y": 300 }, "data": {
+      "label": "Aguarda nome", "waitTime": 15, "waitUnit": "minutes", "validation": "any",
+      "saveTo": "contact_attribute", "saveAttrKey": "nome_completo"
+    } },
+    { "id": "n4", "type": "send_message", "position": { "x": 1010, "y": 300 }, "data": { "label": "Pede email", "messageItems": [
+      { "id": "m2", "type": "text", "content": "Perfeito, {{contact.custom_attributes.nome_completo}}. Qual seu melhor email?" }
+    ] } },
+    { "id": "n5", "type": "wait_response", "position": { "x": 1330, "y": 300 }, "data": {
+      "label": "Aguarda email", "waitTime": 15, "waitUnit": "minutes", "validation": "regex",
+      "regexPattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "invalidMessage": "Esse não parece um email válido. Tenta de novo?", "maxRetries": 2,
+      "saveTo": "contact_attribute", "saveAttrKey": "email"
+    } },
+    { "id": "n6", "type": "action", "position": { "x": 1650, "y": 300 }, "data": { "label": "Cria card", "items": [
+      { "key": "create_kanban_item", "config": { "funnel_id": 1, "funnel_stage": "novo_lead" } },
+      { "key": "add_label", "config": { "labels": ["lead-capturado"] } }
+    ] } },
+    { "id": "n7", "type": "send_message", "position": { "x": 1970, "y": 300 }, "data": { "label": "Confirma", "messageItems": [
+      { "id": "m3", "type": "text", "content": "Tudo certo! Em breve um consultor vai te chamar." }
+    ] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e3", "source": "n3", "target": "n4", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e4", "source": "n4", "target": "n5", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e5", "source": "n5", "target": "n6", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e6", "source": "n6", "target": "n7", "sourceHandle": "success", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## 3. Qualificação BANT (Budget / Authority / Need / Timing)
+
+**Caso:** 4 perguntas pra qualificar lead B2B. Ramifica em "quente" vs "frio".
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "message_received", "keywords": ["proposta","orçamento"], "match_mode": "contains" }] } },
+    { "id": "n2", "type": "send_message", "position": { "x": 370, "y": 300 }, "data": { "label": "B - Budget", "messageItems": [{ "id": "m1", "type": "text", "content": "Pra te ajudar melhor, qual a faixa de investimento que vocês têm em mente?\n\n1️⃣ Até R$ 5k\n2️⃣ R$ 5k a R$ 20k\n3️⃣ Acima de R$ 20k" }] } },
+    { "id": "n3", "type": "wait_response", "position": { "x": 690, "y": 300 }, "data": { "label": "Budget", "waitTime": 60, "waitUnit": "minutes", "validation": "options", "acceptedOptions": ["1","2","3"], "saveTo": "contact_attribute", "saveAttrKey": "budget_tier" } },
+    { "id": "n4", "type": "send_message", "position": { "x": 1010, "y": 300 }, "data": { "label": "A - Authority", "messageItems": [{ "id": "m2", "type": "text", "content": "Você é o decisor ou tem outras pessoas envolvidas?" }] } },
+    { "id": "n5", "type": "wait_response", "position": { "x": 1330, "y": 300 }, "data": { "label": "Autoridade", "waitTime": 60, "waitUnit": "minutes", "validation": "any", "saveTo": "contact_attribute", "saveAttrKey": "authority" } },
+    { "id": "n6", "type": "send_message", "position": { "x": 1650, "y": 300 }, "data": { "label": "N - Need", "messageItems": [{ "id": "m3", "type": "text", "content": "Conta um pouco: o que vocês precisam resolver hoje?" }] } },
+    { "id": "n7", "type": "wait_response", "position": { "x": 1970, "y": 300 }, "data": { "label": "Necessidade", "waitTime": 60, "waitUnit": "minutes", "validation": "any", "saveTo": "contact_attribute", "saveAttrKey": "need" } },
+    { "id": "n8", "type": "send_message", "position": { "x": 2290, "y": 300 }, "data": { "label": "T - Timing", "messageItems": [{ "id": "m4", "type": "text", "content": "Em quanto tempo precisam ter a solução rodando?\n\n1️⃣ Esse mês\n2️⃣ Próximos 3 meses\n3️⃣ Sem pressa" }] } },
+    { "id": "n9", "type": "wait_response", "position": { "x": 2610, "y": 300 }, "data": { "label": "Prazo", "waitTime": 60, "waitUnit": "minutes", "validation": "options", "acceptedOptions": ["1","2","3"], "saveTo": "contact_attribute", "saveAttrKey": "timing_tier" } },
+    { "id": "n10", "type": "condition", "position": { "x": 2930, "y": 300 }, "data": { "label": "Quente?", "conditions": [
+      { "id": "c1", "label": "Lead quente", "field": "contact.custom_attributes.budget_tier", "operator": "not_equal", "value": "1" }
+    ] } },
+    { "id": "n11", "type": "action", "position": { "x": 3250, "y": 180 }, "data": { "label": "Quente", "items": [
+      { "key": "assign_team", "config": { "team_id": 1 } },
+      { "key": "add_label", "config": { "labels": ["lead-quente"] } },
+      { "key": "create_kanban_item", "config": { "funnel_id": 1, "funnel_stage": "qualificado" } }
+    ] } },
+    { "id": "n12", "type": "action", "position": { "x": 3250, "y": 420 }, "data": { "label": "Frio", "items": [
+      { "key": "add_label", "config": { "labels": ["lead-frio"] } },
+      { "key": "create_kanban_item", "config": { "funnel_id": 1, "funnel_stage": "nutrir" } }
+    ] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e3", "source": "n3", "target": "n4", "sourceHandle": "option_1", "type": "deletable", "animated": true },
+    { "id": "e4", "source": "n3", "target": "n4", "sourceHandle": "option_2", "type": "deletable", "animated": true },
+    { "id": "e5", "source": "n3", "target": "n4", "sourceHandle": "option_3", "type": "deletable", "animated": true },
+    { "id": "e6", "source": "n4", "target": "n5", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e7", "source": "n5", "target": "n6", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e8", "source": "n6", "target": "n7", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e9", "source": "n7", "target": "n8", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e10", "source": "n8", "target": "n9", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e11", "source": "n9", "target": "n10", "sourceHandle": "option_1", "type": "deletable", "animated": true },
+    { "id": "e12", "source": "n9", "target": "n10", "sourceHandle": "option_2", "type": "deletable", "animated": true },
+    { "id": "e13", "source": "n9", "target": "n10", "sourceHandle": "option_3", "type": "deletable", "animated": true },
+    { "id": "e14", "source": "n10", "target": "n11", "sourceHandle": "cond_0", "type": "deletable", "animated": true },
+    { "id": "e15", "source": "n10", "target": "n12", "sourceHandle": "default", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## 4. Pesquisa CSAT pós-atendimento
+
+**Caso:** ao resolver conversa, pede nota de 1 a 5 e comentário.
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "conversation_resolved" }] } },
+    { "id": "n2", "type": "wait", "position": { "x": 370, "y": 300 }, "data": { "label": "Aguarda 5 min", "waitTime": 5, "waitUnit": "minutes" } },
+    { "id": "n3", "type": "send_message", "position": { "x": 690, "y": 300 }, "data": { "label": "Pede nota", "messageItems": [{ "id": "m1", "type": "text", "content": "Antes de fechar: de 1 a 5, como foi seu atendimento?\n\n5 = excelente\n1 = ruim" }] } },
+    { "id": "n4", "type": "wait_response", "position": { "x": 1010, "y": 300 }, "data": { "label": "Nota", "waitTime": 60, "waitUnit": "minutes", "validation": "options", "acceptedOptions": ["1","2","3","4","5"], "saveTo": "attribute", "saveAttrKey": "csat_score" } },
+    { "id": "n5", "type": "send_message", "position": { "x": 1330, "y": 300 }, "data": { "label": "Pede comentário", "messageItems": [{ "id": "m2", "type": "text", "content": "Obrigado pela nota! Quer deixar algum comentário?" }] } },
+    { "id": "n6", "type": "wait_response", "position": { "x": 1650, "y": 300 }, "data": { "label": "Comentário", "waitTime": 30, "waitUnit": "minutes", "validation": "any", "saveTo": "attribute", "saveAttrKey": "csat_comment" } },
+    { "id": "n7", "type": "send_message", "position": { "x": 1970, "y": 300 }, "data": { "label": "Encerra", "messageItems": [{ "id": "m3", "type": "text", "content": "Valeu pelo feedback! 🙏" }] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e3", "source": "n3", "target": "n4", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e4", "source": "n4", "target": "n5", "sourceHandle": "option_1", "type": "deletable", "animated": true },
+    { "id": "e5", "source": "n4", "target": "n5", "sourceHandle": "option_2", "type": "deletable", "animated": true },
+    { "id": "e6", "source": "n4", "target": "n5", "sourceHandle": "option_3", "type": "deletable", "animated": true },
+    { "id": "e7", "source": "n4", "target": "n5", "sourceHandle": "option_4", "type": "deletable", "animated": true },
+    { "id": "e8", "source": "n4", "target": "n5", "sourceHandle": "option_5", "type": "deletable", "animated": true },
+    { "id": "e9", "source": "n5", "target": "n6", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e10", "source": "n6", "target": "n7", "sourceHandle": "success", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## 5. Roteamento por horário comercial
+
+**Caso:** se dentro do expediente, atribui agente. Se fora, manda ausência.
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "conversation_created" }] } },
+    { "id": "n2", "type": "condition", "position": { "x": 370, "y": 300 }, "data": { "label": "Horário comercial?", "conditions": [
+      { "id": "c1", "label": "Dentro do horário", "field": "now.hour", "operator": "greater_than", "value": "8" }
+    ] } },
+    { "id": "n3", "type": "action", "position": { "x": 690, "y": 180 }, "data": { "label": "Atribui agente", "items": [
+      { "key": "assign_team", "config": { "team_id": 1 } }
+    ] } },
+    { "id": "n4", "type": "send_message", "position": { "x": 690, "y": 420 }, "data": { "label": "Ausência", "messageItems": [
+      { "id": "m1", "type": "text", "content": "Recebemos sua mensagem! Nosso horário é das 9h às 18h, dias úteis. Retornamos assim que possível." }
+    ] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "cond_0", "type": "deletable", "animated": true },
+    { "id": "e3", "source": "n2", "target": "n4", "sourceHandle": "default", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## 6. Triagem com IA (classificação de intenção)
+
+**Caso:** usa IA pra ler a primeira mensagem e classificar como compra/suporte/reclamação/dúvida.
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "message_received" }] } },
+    { "id": "n2", "type": "ai", "position": { "x": 370, "y": 300 }, "data": {
+      "label": "Classifica", "aiMode": "intent",
+      "aiPrompt": "Classifique a intenção da última mensagem do cliente",
+      "aiIntentOptions": ["compra", "suporte", "reclamacao", "duvida"],
+      "aiResponseVar": "intent"
+    } },
+    { "id": "n3", "type": "action", "position": { "x": 690, "y": 60 }, "data": { "label": "→ Compra", "items": [{ "key": "assign_team", "config": { "team_id": 1 } }, { "key": "add_label", "config": { "labels": ["intent-compra"] } }] } },
+    { "id": "n4", "type": "action", "position": { "x": 690, "y": 240 }, "data": { "label": "→ Suporte", "items": [{ "key": "assign_team", "config": { "team_id": 2 } }, { "key": "add_label", "config": { "labels": ["intent-suporte"] } }] } },
+    { "id": "n5", "type": "action", "position": { "x": 690, "y": 420 }, "data": { "label": "→ Reclamação", "items": [{ "key": "assign_team", "config": { "team_id": 3 } }, { "key": "change_priority", "config": { "priority": "high" } }, { "key": "add_label", "config": { "labels": ["intent-reclamacao"] } }] } },
+    { "id": "n6", "type": "action", "position": { "x": 690, "y": 600 }, "data": { "label": "→ Dúvida", "items": [{ "key": "assign_captain", "config": { "assistant_id": 1 } }] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "intent_compra", "type": "deletable", "animated": true },
+    { "id": "e3", "source": "n2", "target": "n4", "sourceHandle": "intent_suporte", "type": "deletable", "animated": true },
+    { "id": "e4", "source": "n2", "target": "n5", "sourceHandle": "intent_reclamacao", "type": "deletable", "animated": true },
+    { "id": "e5", "source": "n2", "target": "n6", "sourceHandle": "intent_duvida", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## 7. Re-engajamento de lead frio
+
+**Caso:** após 7 dias sem resposta, manda template aprovado e marca label.
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "label_added", "label": "follow-up" }] } },
+    { "id": "n2", "type": "wait", "position": { "x": 370, "y": 300 }, "data": { "label": "Espera 7 dias", "waitTime": 7, "waitUnit": "days" } },
+    { "id": "n3", "type": "send_message", "position": { "x": 690, "y": 300 }, "data": { "label": "Template re-engajamento", "messageItems": [
+      { "id": "m1", "type": "whatsapp_template", "templateId": 42, "params": ["{{contact.name}}"] }
+    ] } },
+    { "id": "n4", "type": "action", "position": { "x": 1010, "y": 300 }, "data": { "label": "Marca tentativa", "items": [
+      { "key": "add_label", "config": { "labels": ["reengajamento-enviado"] } },
+      { "key": "remove_label", "config": { "labels": ["follow-up"] } }
+    ] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e3", "source": "n3", "target": "n4", "sourceHandle": "success", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## 8. Suporte com escalation pra humano
+
+**Caso:** tenta resolver com IA. Se cliente pedir "atendente humano" ou IA não souber, escala.
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "message_received" }] } },
+    { "id": "n2", "type": "condition", "position": { "x": 370, "y": 300 }, "data": { "label": "Pede humano?", "conditions": [
+      { "id": "c1", "label": "Sim", "field": "last_message.content", "operator": "contains", "value": "humano" }
+    ] } },
+    { "id": "n3", "type": "action", "position": { "x": 690, "y": 120 }, "data": { "label": "→ Humano", "items": [
+      { "key": "deactivate_captain", "config": {} },
+      { "key": "assign_team", "config": { "team_id": 2 } },
+      { "key": "add_label", "config": { "labels": ["escalado-humano"] } }
+    ] } },
+    { "id": "n4", "type": "action", "position": { "x": 690, "y": 480 }, "data": { "label": "→ IA atende", "items": [
+      { "key": "assign_captain", "config": { "assistant_id": 1 } }
+    ] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "cond_0", "type": "deletable", "animated": true },
+    { "id": "e3", "source": "n2", "target": "n4", "sourceHandle": "default", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## 9. Agendamento via API externa
+
+**Caso:** cliente quer marcar reunião — fluxo chama API de booking, salva ID, confirma.
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "message_received", "keywords": ["agendar","reunião"], "match_mode": "contains" }] } },
+    { "id": "n2", "type": "send_message", "position": { "x": 370, "y": 300 }, "data": { "label": "Pede data", "messageItems": [{ "id": "m1", "type": "text", "content": "Em que data você prefere? (formato DD/MM)" }] } },
+    { "id": "n3", "type": "wait_response", "position": { "x": 690, "y": 300 }, "data": { "label": "Data", "waitTime": 30, "waitUnit": "minutes", "validation": "regex", "regexPattern": "^\\d{2}/\\d{2}$", "invalidMessage": "Formato inválido. Use DD/MM (ex: 25/05)", "maxRetries": 2, "saveTo": "variable", "saveVariable": "data_pref" } },
+    { "id": "n4", "type": "api", "position": { "x": 1010, "y": 300 }, "data": {
+      "label": "Cria booking", "method": "POST",
+      "url": "https://api.example.com/bookings",
+      "headers": [{ "key": "Authorization", "value": "Bearer {{env.BOOKING_TOKEN}}" }, { "key": "Content-Type", "value": "application/json" }],
+      "body": "{\"contact_id\":\"{{contact.id}}\",\"date\":\"{{data_pref}}\"}",
+      "apiResponseVar": "booking_result"
+    } },
+    { "id": "n5", "type": "send_message", "position": { "x": 1330, "y": 180 }, "data": { "label": "Confirma", "messageItems": [{ "id": "m2", "type": "text", "content": "Reunião agendada! ID {{booking_result.id}}. Te mando lembrete 1h antes." }] } },
+    { "id": "n6", "type": "send_message", "position": { "x": 1330, "y": 420 }, "data": { "label": "Erro", "messageItems": [{ "id": "m3", "type": "text", "content": "Não consegui agendar agora. Um atendente vai te ajudar." }] } },
+    { "id": "n7", "type": "action", "position": { "x": 1650, "y": 420 }, "data": { "label": "Escala", "items": [{ "key": "assign_team", "config": { "team_id": 1 } }] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e3", "source": "n3", "target": "n4", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e4", "source": "n4", "target": "n5", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e5", "source": "n4", "target": "n6", "sourceHandle": "error", "type": "deletable", "animated": true },
+    { "id": "e6", "source": "n6", "target": "n7", "sourceHandle": "success", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## 10. Notificação interna por webhook (label aplicada)
+
+**Caso:** quando label "urgente" é aplicada, dispara webhook pro n8n/Slack.
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "label_added", "label": "urgente" }] } },
+    { "id": "n2", "type": "action", "position": { "x": 370, "y": 300 }, "data": { "label": "Dispara webhook", "items": [
+      { "key": "send_webhook", "config": {
+        "url": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
+        "headers": [{ "key": "Content-Type", "value": "application/json" }],
+        "body": "{\"text\":\"🚨 Conversa urgente: {{conversation.id}} — cliente {{contact.name}}\"}"
+      } },
+      { "key": "change_priority", "config": { "priority": "urgent" } }
+    ] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## Como usar este catálogo
+
+1. **Identifique o pattern mais próximo** do que o cliente pediu
+2. **Copie o `flow_data` inteiro**
+3. **Substitua os IDs e valores reais** (team_id, funnel_id, assistant_id, templateId, URLs, etc) — confira antes via `teams_list`, `funnels_list`, `captain_assistants_list`, `inboxes_whatsapp_templates_list`
+4. **Adicione campos do flow**: `name`, `description`, `channel_type` (`Channel::Waha` etc), `inbox_ids`
+5. **Chame `flows_create`** com o payload completo
+6. Após criar, **ative** com `flows_toggle` se o cliente quiser que rode já
+
+Se a necessidade não bate com nenhum pattern, monte do zero seguindo o **`flowbuilder-design-guide`** — mas use estes templates como referência de layout/handle/schema válidos.

package/dist/index.js

@@ -49,8 +49,8 @@ async function main() {
         console.error(`Base URL: ${config.baseUrl}`);
         console.error(`Account: ${config.accountId}`);
         console.error(`Tools registered: ${toolCount}`);
-        console.error(`Resources registered: 8 (glossary, data-model, reports-guide, api-conventions, conversation-flows, kanban-deep-dive, best-practices, troubleshooting)`);
-        console.error(`Prompts registered: 8 (productivity_report, stuck_leads, weekly_recap, customer_health, inactive_contacts, team_load_balance, quality_audit, whatsapp_template_usage)`);
+        console.error(`Resources registered: 10 (glossary, data-model, reports-guide, api-conventions, conversation-flows, kanban-deep-dive, best-practices, troubleshooting, flowbuilder-design-guide, flowbuilder-patterns)`);
+        console.error(`Prompts registered: 9 (productivity_report, stuck_leads, weekly_recap, customer_health, inactive_contacts, team_load_balance, quality_audit, whatsapp_template_usage, create_flow_brainstorm)`);
         if (config.categories) {
             console.error(`Categories filter: ${config.categories.join(', ')}`);
         }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,oFAAoF;AACpF,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AACxF,MAAM,OAAO,GAAW,GAAG,CAAC,OAAO,CAAC;AAEpC,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,6FAA6F;QAC7F,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAE5B,+EAA+E;QAC/E,IACE,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC;YACtC,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;YACrC,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EACrC,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,4EAA4E,CAAC,CAAC;QAC9F,CAAC;QAED,0FAA0F;QAC1F,gFAAgF;QAChF,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;YACE,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,OAAO;SACjB,EACD;YACE,YAAY,EAAE,qBAAqB,EAAE;YACrC,YAAY,EAAE;gBACZ,KAAK,EAAE,EAAE;gBACT,SAAS,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE;gBACnD,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;aAChC;SACF,CACF,CAAC;QAEF,wEAAwE;QACxE,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QAE1C,uFAAuF;QACvF,MAAM,SAAS,GAAG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAExD,6EAA6E;QAC7E,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC1B,eAAe,CAAC,MAAM,CAAC,CAAC;QAExB,iFAAiF;QACjF,OAAO,CAAC,KAAK,CAAC,wBAAwB,OAAO,EAAE,CAAC,CAAC;QACjD,OAAO,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,OAAO,CAAC,KAAK,CAAC,YAAY,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QAC9C,OAAO,CAAC,KAAK,CAAC,qBAAqB,SAAS,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,KAAK,CAAC,uJAAuJ,CAAC,CAAC;QACvK,OAAO,CAAC,KAAK,CAAC,uKAAuK,CAAC,CAAC;QACvL,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,sBAAsB,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;QAED,kEAAkE;QAClE,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/resources.js

@@ -53,6 +53,18 @@ export const RESOURCES = [
         description: 'Codigos HTTP, erros comuns (401/403/422/429), erros MCP, debugging, quando reportar suporte. Use pra interpretar erros.',
         filename: 'troubleshooting.md',
     },
+    {
+        name: 'FlowBuilder Design Guide',
+        uri: 'lionchat://docs/flowbuilder-design-guide',
+        description: 'OBRIGATORIO antes de criar/editar fluxo. Arvore de decisao por necessidade, schema por tipo de node (com handles expostos), regras de layout/positioning, erros comuns, checklist pre-submit.',
+        filename: 'flowbuilder-design-guide.md',
+    },
+    {
+        name: 'FlowBuilder Patterns',
+        uri: 'lionchat://docs/flowbuilder-patterns',
+        description: '10 templates de fluxos prontos pra adaptar: saudacao, captura, qualificacao BANT, CSAT, horario comercial, IA intent, re-engajamento, escalation, agendamento, webhook. Cada um com layout valido e handles certos.',
+        filename: 'flowbuilder-patterns.md',
+    },
 ];
 function findDocsPath(filename) {
     const candidates = [

package/dist/resources.js.map

@@ -1 +1 @@
-{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,iEAAiE;AAEjE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAS1D,MAAM,CAAC,MAAM,SAAS,GAAkB;IACtC;QACE,IAAI,EAAE,oBAAoB;QAC1B,GAAG,EAAE,0BAA0B;QAC/B,WAAW,EACT,mIAAmI;QACrI,QAAQ,EAAE,aAAa;KACxB;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,GAAG,EAAE,4BAA4B;QACjC,WAAW,EACT,sGAAsG;QACxG,QAAQ,EAAE,eAAe;KAC1B;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,GAAG,EAAE,+BAA+B;QACpC,WAAW,EACT,4GAA4G;QAC9G,QAAQ,EAAE,kBAAkB;KAC7B;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,GAAG,EAAE,iCAAiC;QACtC,WAAW,EACT,iHAAiH;QACnH,QAAQ,EAAE,oBAAoB;KAC/B;IACD;QACE,IAAI,EAAE,uBAAuB;QAC7B,GAAG,EAAE,oCAAoC;QACzC,WAAW,EACT,oJAAoJ;QACtJ,QAAQ,EAAE,uBAAuB;KAClC;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,GAAG,EAAE,kCAAkC;QACvC,WAAW,EACT,oIAAoI;QACtI,QAAQ,EAAE,qBAAqB;KAChC;IACD;QACE,IAAI,EAAE,eAAe;QACrB,GAAG,EAAE,gCAAgC;QACrC,WAAW,EACT,2HAA2H;QAC7H,QAAQ,EAAE,mBAAmB;KAC9B;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,GAAG,EAAE,iCAAiC;QACtC,WAAW,EACT,yHAAyH;QAC3H,QAAQ,EAAE,oBAAoB;KAC/B;CACF,CAAC;AAEF,SAAS,YAAY,CAAC,QAAgB;IACpC,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,SAAS,EAAE,mBAAmB,EAAE,QAAQ,CAAC;QAC9C,IAAI,CAAC,SAAS,EAAE,0BAA0B,EAAE,QAAQ,CAAC;KACtD,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAiB;IACjD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,MAAM,CAAC,gBAAgB,CACrB,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,GAAG,EACP;YACE,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,QAAQ,EAAE,eAAe;SAC1B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE;YACZ,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC5D,CAAC;YACD,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,GAAG,CAAC,IAAI;wBACb,QAAQ,EAAE,eAAe;wBACzB,IAAI,EAAE,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC;qBACtC;iBACF;aACF,CAAC;QACJ,CAAC,CACF,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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"}

package/endpoints.json

@@ -8817,7 +8817,7 @@
     "method": "POST",
     "path": "/api/v1/accounts/{account_id}/flows",
     "title": "Criar Flow",
-    "description": "Cria um flow (FlowBuilder) na conta. Requer Admin. flow_data segue formato Vue Flow {nodes:[], edges:[]}. NODE SCHEMA — start: {label}. send_message: {label, messageItems:[{id, type:'text', content}]} handles: success/no_response/error. wait_response: {label, waitTime, waitUnit:'minutes'|'seconds', validation:'any'|'options'|'regex', acceptedOptions:['1','2'] (se options), regexPattern (se regex), invalidMessage, maxRetries:3, saveTo:'variable'|'attribute'|'', saveVariable, saveAttrKey} — quando validation='options' os handles ficam 'option_{val}' + 'timeout'; senão 'success' + 'timeout' — NUNCA precisa de condition node depois. condition: {label, conditions:[{id, label, field, operator, value}]} handles = id de cada condicao + 'default'. action: {label, items:[{key, config:{...}}]} keys comuns assign_team({team_id}), assign_agent({agent_id}), add_label({labels:['slug',...]}), remove_label({labels}), change_status({status}), change_priority({priority}), mute_conversation({}), add_private_note({content}), create_kanban_item({funnel_id, funnel_stage,...}), move_kanban_stage({funnel_id, funnel_stage}), deactivate_flow({}), assign_captain({assistant_id}). api: {label, method, url, headers:[{key,value}], body, apiResponseVar}. set_variable: {label, variables:[{name, value}]}. wait: {label, waitTime, waitUnit}. EDGE SCHEMA: {id, source, target, sourceHandle (opcional, OBRIGATORIO casar com handle exposto pelo node source), type:'deletable', animated:true}. ERROS COMUNS QUE DEVEM SER EVITADOS: (1) action usa items[].config NAO items[].params; (2) send_message usa messageItems NAO items; (3) wait_response com validation='options' NAO precisa de condition node — use sourceHandle='option_X' diretamente; (4) sourceHandle inventado tipo 'c1','c2' nao funciona — sempre usar o handle real; (5) inbox_ids precisa vir aninhado em {flow:{inbox_ids:[]}} no PUT bruto, mas no MCP basta inbox_ids no nivel raiz. Cria novo flow. Obrigatórios: name, channel_type. Valida unicidade quando aplicável. Retorna o flow criado com ID atribuído.",
+    "description": "Cria um flow (FlowBuilder) na conta. Requer Admin. flow_data segue formato Vue Flow {nodes:[], edges:[]}. NODE SCHEMA — start: {label}. send_message: {label, messageItems:[{id, type:'text', content}]} handles: success/no_response/error. wait_response: {label, waitTime, waitUnit:'minutes'|'seconds', validation:'any'|'options'|'regex', acceptedOptions:['1','2'] (se options), regexPattern (se regex), invalidMessage, maxRetries:3, saveTo:'variable'|'attribute'|'', saveVariable, saveAttrKey} — quando validation='options' os handles ficam 'option_{val}' + 'timeout'; senão 'success' + 'timeout' — NUNCA precisa de condition node depois. condition: {label, conditions:[{id, label, field, operator, value}]} handles = id de cada condicao + 'default'. action: {label, items:[{key, config:{...}}]} keys comuns assign_team({team_id}), assign_agent({agent_id}), add_label({labels:['slug',...]}), remove_label({labels}), change_status({status}), change_priority({priority}), mute_conversation({}), add_private_note({content}), create_kanban_item({funnel_id, funnel_stage,...}), move_kanban_stage({funnel_id, funnel_stage}), deactivate_flow({}), assign_captain({assistant_id}). api: {label, method, url, headers:[{key,value}], body, apiResponseVar}. set_variable: {label, variables:[{name, value}]}. wait: {label, waitTime, waitUnit}. EDGE SCHEMA: {id, source, target, sourceHandle (opcional, OBRIGATORIO casar com handle exposto pelo node source), type:'deletable', animated:true}. ERROS COMUNS QUE DEVEM SER EVITADOS: (1) action usa items[].config NAO items[].params; (2) send_message usa messageItems NAO items; (3) wait_response com validation='options' NAO precisa de condition node — use sourceHandle='option_X' diretamente; (4) sourceHandle inventado tipo 'c1','c2' nao funciona — sempre usar o handle real; (5) inbox_ids precisa vir aninhado em {flow:{inbox_ids:[]}} no PUT bruto, mas no MCP basta inbox_ids no nivel raiz. Cria novo flow. Obrigatórios: name, channel_type. Valida unicidade quando aplicável. Retorna o flow criado com ID atribuído. POSITIONING (CRITICO): cada node DEVE ter position:{x,y}. Sem isso, todos empilham no canvas no (0,0). Regra basica de layout: start em {x:50,y:300}, espaco horizontal +320 entre nodes sequenciais, ramificacoes em +/-150 vertical. ANTES DE GERAR JSON consulte o resource lionchat://docs/flowbuilder-design-guide (schema completo de cada tipo de node, handles expostos, erros comuns, checklist) e lionchat://docs/flowbuilder-patterns (10 templates prontos pra adaptar). BRAINSTORMING: se faltou info critica (canal, gatilho, conteudo), use o prompt create_flow_brainstorm como banco de perguntas sugeridas — pergunte SO o que falta, sem checklist forcado. APOS GERAR: rode o checklist da secao 6 do design guide antes de submeter (1 node start, todo node com id unico + position + data, todo edge com sourceHandle valido). NUNCA invente sourceHandle (no condition use cond_0/cond_1/default, no wait_response options use option_X, no AI intent use intent_<opcao>).",
     "category": "Flows",
     "params": [
       {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lionchat/mcp-server",
-  "version": "0.3.1",
-  "description": "MCP server for LionChat API — 547 tools + 8 resources + 8 prompts for AI agents",
+  "version": "0.3.2",
+  "description": "MCP server for LionChat API — 547 tools + 10 resources + 9 prompts for AI agents (FlowBuilder enriched)",
   "type": "module",
   "main": "dist/index.js",
   "bin": {