@lionchat/mcp-server 1.14.0 → 1.16.0

package/dist/docs/instructions.md

@@ -120,7 +120,11 @@ marcar supervisor num lugar protege no outro.
 
 ### Datas
 - **Formato:** ISO 8601 com timezone, ex: `"2026-05-18T14:32:00-03:00"`
-- **Timezone padrão:** `America/Sao_Paulo` (BRT, UTC-3)
+- **Timezone:** a CONTA tem fuso próprio — leia `timezone` em `lionchat_account_show` (IANA, ex.
+  `America/Sao_Paulo`, `America/Campo_Grande`) e use ELE em filtros de data, `timezone_offset` de
+  relatórios e ao escrever horários. O padrão da plataforma é `America/Sao_Paulo` (UTC-3), mas
+  Mato Grosso, Mato Grosso do Sul, Amazonas e Acre são outro fuso e há cliente fora do Brasil.
+  Nunca chute -3.
 - **Timestamps Unix** aparecem em alguns campos (ex: `last_activity_at`) — sempre em segundos, não milissegundos
 
 ### Paginação
@@ -269,6 +273,8 @@ teams, conversations_summary) exigem as DUAS pontas; nos demais, `since` ou `unt
 2. lionchat_campaigns_estimate_audience (MESMO audience+mode) → mostrar contagem ao usuário
 3. CONFIRMAR com o usuário (é envio em massa — seção 7b)
 4. lionchat_campaigns_create (inbox_id define o tipo: WhatsApp oficial, QR Code/WAHA, SMS, Website)
+   Modelo oficial com variáveis: `template_params.processed_params.body` precisa ter TODAS as
+   posições (`"1"`, `"2"`...) preenchidas — posição vazia NÃO falha, sai como "." pra todo mundo.
 5. Acompanhar com lionchat_campaigns_statistics (sent/delivered/read/failed)
 ```
 Estrutura do audience: `[{type:'Label', id}, {type:'Funnel', id, stages:[], include_won, include_lost}, {type:'ConversationAttribute', key, value}]`.
@@ -347,9 +353,14 @@ Antes de QUALQUER ação que escreve, modifica, apaga ou envia, pare e avalie se
 
 **Como confirmar:** descreva o efeito em linguagem do usuário e aguarde o "sim". Ex.: *"Vou apagar o contato #312 — isso remove as 4 conversas dele também. Confirma?"*. Se faltar dado, peça só o que falta (1-2 perguntas), nunca um questionário.
 
+**Ferramentas com trava dura de confirmação.** Algumas ferramentas **recusam a chamada** sem `confirm: true` — a recusa vem do conector, antes de tocar no sistema. Não é erro: é o pedido de OK. O caminho é sempre o mesmo — descreva ao usuário exatamente o que será criado/alterado/apagado, aguarde o "sim", e só então reenvie a MESMA chamada com `confirm: true`. Nunca mande `confirm: true` na primeira tentativa "pra economizar uma volta": a trava existe justamente porque a descrição sozinha não segurava. Hoje: `lionchat_custom_dashboards_create`, `_update` e `_destroy` (relatório personalizado aparece na tela do cliente; alterar substitui a lista de blocos e apagar não tem desfazer).
+
 **Aja sem perguntar apenas em operações idempotentes:** leitura, busca, resumo, classificação.
 
 **Excluir agente/usuário (`lionchat_agents_destroy`) — SEMPRE pergunte o destino primeiro.** Se o agente tem recursos vinculados (conversas, tarefas — inclusive as que ele **criou** —, cards do Kanban, campanhas, agendamentos), o sistema EXIGE um destino de reatribuição. Antes de excluir: consulte `lionchat_agents_assigned_resources` (o retorno inclui `tasks_created`, tarefas criadas por ele); se houver QUALQUER recurso, **pergunte pra qual agente transferir tudo** e passe `reassign_to_agent_id` no destroy. Nunca tente excluir sem o destino — o sistema recusa e o trabalho do agente ficaria órfão. Ao excluir, tudo passa pro agente escolhido; o excluído fica só no histórico.
+Quando o pedido for "fulano saiu e ciclano entrou no lugar", prefira `lionchat_agents_replace` a
+`destroy` + `create`: a troca é uma só, a carteira vai inteira pro novo e a vaga do plano não
+trava a criação.
 
 **NUNCA sobrescreva por inferência dados já preenchidos.** Em especial, **NUNCA sobrescreva telefone ou e-mail existente de um contato** — se já há valor preenchido, pergunte antes de alterar.
 
@@ -370,6 +381,7 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 | Criar/editar **formulário público de captação** (página de captura própria) | `lionchat_lead_forms_create` / `_update` | Leia `lionchat://docs/formularios-publicos` ANTES — o desenho vai em `form_data` e só entra no ar depois do `publish` (que valida o desenho e pode voltar 422 com a lista de pendências). Caixa de WhatsApp vinculada (`inbox_id`) é obrigatória pra publicar. Escrita é só de administrador |
 | **Testar um formulário** antes de publicar | `lionchat_lead_forms_test_run` | Roda o RASCUNHO no motor real e desfaz tudo no fim — zero rastro. Mande `answers: [{node_id, value}]` (até 60) pra reproduzir um caminho; a resposta traz o bloco atual + o log do percurso |
 | Conferir se um site **aceita ser exibido dentro do formulário** (bloco Página externa) | `lionchat_lead_forms_check_embed` | Body `{url}`; devolve `{status: allowed\|blocked\|unknown, reason}`. Grave o veredito em `embed_allowed` do bloco. Admin-only |
+| Ver **tudo que uma pessoa preencheu** (nosso formulário, anúncio do Meta, Webhook Universal, fluxo) | `lionchat_contacts_form_entries_list` / `_show` | Por CONTATO, sem paginação (teto 250 por origem, `meta.truncated`). O detalhe de Meta/webhook mostra SÓ os campos vinculados e gravados — nunca o payload cru. `show` exige `source` + `id` da mesma linha |
 | Anexar arquivo a uma mensagem | `lionchat_upload_create` primeiro, depois usar o retorno em `lionchat_conversations_messages_create` | Confira `lionchat_upload_limits` se o arquivo for grande |
 | Marcar conversa como **lida** | `lionchat_conversations_update_last_seen` | NÃO use `unread` (esse marca como NÃO-lida) |
 | Criar/gerenciar **campanha** (disparo WhatsApp/SMS) | `lionchat_campaigns_*` (criar, estatísticas) | SEMPRE rode `campaigns_estimate_audience` antes de criar e mostre a contagem. Disparo em massa = confirmação obrigatória (seção 7b) |
@@ -390,6 +402,7 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 | **Mudar o modo de distribuição do time** (Rodízio × Equilibrado) | `lionchat_teams_update` (`assignment_order`: `round_robin` \| `balanced`) | **`null` é valor válido e significa "o time não escolheu"** — a decisão herda da política da caixa, depois do `auto_assignment_config` da caixa, e por fim rodízio. NUNCA gravar `round_robin` só para "preencher": isso rebaixa em silêncio uma caixa que roda Equilibrado por política. `balanced` exige o recurso `advanced_assignment` na conta |
 | **Mudar o modo de distribuição da caixa** (Rodízio × Equilibrado) | `lionchat_inboxes_update` (`auto_assignment_config.assignment_order`) | Só vale quando a caixa NÃO tem política vinculada (com política, a política manda). O jsonb é SUBSTITUÍDO, não mesclado: releia o `auto_assignment_config` atual e reenvie as outras chaves junto, senão apaga o `assign_offline_agents` e o freio |
 | **Criar/atualizar time** | `lionchat_teams_create` / `_update` | **Preencha `description`**: desde 03/08 é ela que o AI Agente lê pra decidir o roteamento por time. Descreva QUANDO mandar pra lá, não o que o time é |
+| **Trocar um atendente por outro** ("fulano saiu, entrou ciclano") | `lionchat_agents_replace` (`POST /agents/{id}/replace`, body `agent: {email, name, role}`; `inherit_memberships` default `true`) | Faz os dois passos de uma vez: cria o novo (passa pelo limite de vagas do plano por 30 min), manda a carteira inteira (conversas, cards, tarefas, agendamentos) e exclui o antigo em segundo plano. Responde **202** com `new_agent` — o antigo some da lista quando a transferência termina (`replacing: true` em `agents_list` enquanto roda). **Confirme antes** (seção 7a: é exclusão). Recusas 422: substituir a si mesmo, agente de suporte, e-mail já membro, e o **único administrador confirmado só troca por usuário já confirmado** (convide e espere aceitar). `agents_destroy` recusa quem está ENTRANDO numa substituição viva. Admin-only |
 | **Pausar a automação no meio** (esperar atribuição/card antes da próxima ação) | ação `wait` em `lionchat_automation_rules_create` / `_update` | Segundos, teto 300. Acima disso é caso de FlowBuilder. Ver `lionchat://docs/conversation-flows` |
 | **Buscar contato/conversa/card** | `lionchat_search_*`, `lionchat_contacts_search` | **Termo com letra exige 3+ caracteres** (dígito é isento). Menos que isso volta VAZIO sem erro — não conclua que o registro não existe. Ver `lionchat://docs/api-conventions` |
 | **Migrar conversas** de uma caixa WhatsApp pra outra (ex.: QR Code → Oficial) | `lionchat_inboxes_inbox_migration_list` (prévia) → `_execute` → acompanhar status | Admin-only e IRREVERSÍVEL: sempre mostre os números da prévia e confirme (seção 7a). Grupos não vão pro canal oficial — ficam na caixa de origem |

package/dist/docs/prompts/create_flow_brainstorm.json

@@ -5,5 +5,5 @@
   "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: 'conversation_attr' (atributo da conversa) na duvida — NUNCA use 'attribute' (valor inexistente, nao salva nada)\n- match_mode: 'contains' pra keywords"
+  "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, data na ficha do contato, webhook externo)\n- O gatilho e um agendamento (criado / cancelado / remarcado / concluido)? Se sim, sao os gatilhos booking_* do Booking nativo (nao e e-Clinica)\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) — a espera tem tempo? Sem fio no timeout, o fluxo TERMINA quando o tempo estoura\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 — divide na proporcao configurada, 50/50 alterna; nao e sorteio)\n- Toda saida de bloco vai ter fio? Saida sem fio ENCERRA o fluxo (nao \"cai no proximo\")\n- Se for fluxo de grupo: quer convite no privado pra quem nao entrar no grupo? (groupInviteOnFailure + groupInviteMessage)\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: 'conversation_attr' (atributo da conversa) na duvida — NUNCA use 'attribute' (valor inexistente, nao salva nada)\n- match_mode: 'contains' pra keywords"
 }

package/dist/docs/prompts/customer_health.json

@@ -9,5 +9,5 @@
       "required": true
     }
   ],
-  "template": "Gere visão **360° do cliente** identificado por: **{{contact_identifier}}**\n\n## Passos\n\n1. **Localize o contato** (use `lionchat_contacts_search` com `q={{contact_identifier}}`):\n   - Se múltiplos resultados, mostre os top 3 e peça confirmação\n   - Se nenhum, reporte e pare\n\n2. **Detalhes do contato** (use `lionchat_contacts_show`):\n   - Nome, email, telefone, identifier\n   - custom_attributes (importante! pode ter dados de negócio)\n   - Empresa vinculada (se houver)\n   - Data de criação no LionChat\n\n3. **Histórico de conversas** (use `lionchat_contacts_list_1` — GET /contacts/{id}/conversations — passando o `id` do contato):\n   - Total de conversas com esse cliente\n   - Status atual: quantas abertas, resolvidas, pendentes\n   - Últimas 5 conversas (com data e display_id)\n\n4. **Conversa mais recente** (use `lionchat_conversations_messages_list` da última conversa):\n   - Pegue as últimas 10 mensagens pra contexto\n   - Identifique tom (cordial, irritado, satisfeito)\n   - Status atual e último agente atribuído\n\n5. **Cards Kanban vinculados** (use `lionchat_kanban_items_filter` por conversation_display_ids):\n   - Em quais funis está\n   - Etapas atuais\n   - Valor total no pipeline\n\n6. **CSAT histórico** (use `lionchat_csat_list` filtrando por contact_id se possível, senão por conversas dele):\n   - Notas recebidas, feedbacks\n   - Tendência (melhorando/piorando)\n\n7. **Engajamento** (calcule a partir dos dados):\n   - Frequência de interação (conversas/mês)\n   - Tempo desde última conversa (sinal de churn?)\n   - Taxa de resposta dele (incoming vs outgoing)\n\n## Apresentação\n\n```markdown\n# 👤 Cliente: [Nome] — Visão 360°\n\n## 📇 Identificação\n- **Email:** ...\n- **Telefone:** ...\n- **Empresa:** ...\n- **Cadastrado em:** DD/MM/YYYY (X meses atrás)\n- **Custom:** [campos relevantes do custom_attributes]\n\n## 📊 Status\n- **Health Score:** 🟢 Saudável / 🟡 Atenção / 🔴 Risco\n- **Última interação:** DD/MM/YYYY (X dias atrás)\n- **Conversas totais:** N | Abertas: M | Resolvidas: K\n- **CSAT médio:** X⭐ (baseado em N respostas)\n\n## 💰 Pipeline (Kanban)\n- **Funil [X]:** Etapa Y — R$ Z (parado há W dias)\n- **Funil [X2]:** Etapa Y2 — R$ Z2\n\n## 💬 Última Conversa (#display_id)\n- **Data:** DD/MM HH:MM\n- **Status:** Aberta/Resolvida\n- **Agente:** Nome\n- **Resumo (2-3 linhas):** O que aconteceu na última interação\n- **Tom percebido:** Cordial / Frustrado / Satisfeito\n\n## ⚠️ Sinais de Alerta\n[Lista sinais detectados:]\n- Sem interação há >30 dias\n- Última CSAT foi 2⭐\n- Card parado em \"Negociação\" há 21 dias\n- Cliente comentou \"vou avaliar concorrentes\"\n\n## 💡 Próximos Passos Sugeridos\n[2-3 ações concretas:]\n1. Ligar pra entender por que parou de responder\n2. Mover card pra etapa \"Em risco\"\n3. Enviar pesquisa de feedback\n```\n\n## Health Score (como calcular)\n\n- 🟢 **Saudável:** última interação <30d + CSAT ≥4 + sem sinais negativos\n- 🟡 **Atenção:** última interação 30-90d OU CSAT 3-3.9 OU card parado >14d\n- 🔴 **Risco:** última interação >90d OU CSAT <3 OU múltiplos cards parados OU mensagens frustradas recentes\n\n## Importante\n\n- Seja honesto no Health Score. Não infle: 🟢 só se realmente saudável.\n- **Não invente sinais.** Só liste o que viu nos dados.\n- Se cliente é novo (<30 dias), avise: \"Pouco histórico, score preliminar\".\n- Se múltiplos contatos com o mesmo nome, peça pra desambiguar antes de continuar.\n- Datas em PT-BR (DD/MM/YYYY)."
+  "template": "Gere visão **360° do cliente** identificado por: **{{contact_identifier}}**\n\n## Passos\n\n1. **Localize o contato** (use `lionchat_contacts_search` com `q={{contact_identifier}}`):\n   - Se múltiplos resultados, mostre os top 3 e peça confirmação\n   - Se nenhum, reporte e pare\n\n2. **Detalhes do contato** (use `lionchat_contacts_show`):\n   - Nome, email, telefone, identifier\n   - custom_attributes (importante! pode ter dados de negócio)\n   - Empresa vinculada (se houver)\n   - Data de criação no LionChat\n\n3. **Histórico de conversas** (use `lionchat_contacts_list_1` — GET /contacts/{id}/conversations — passando o `id` do contato):\n   - Total de conversas com esse cliente\n   - Status atual: quantas abertas, resolvidas, pendentes\n   - Últimas 5 conversas (com data e display_id)\n\n4. **Conversa mais recente** (use `lionchat_conversations_messages_list` da última conversa):\n   - Pegue as últimas 10 mensagens pra contexto\n   - Mensagem com `content_attributes.deleted: true` foi APAGADA pelo cliente (não cite o texto como se estivesse de pé); `edited: true` = o `content` já é a versão editada\n   - Identifique tom (cordial, irritado, satisfeito)\n   - Status atual e último agente atribuído\n\n5. **Cards Kanban vinculados** (use `lionchat_kanban_items_filter` por conversation_display_ids):\n   - Em quais funis está\n   - Etapas atuais\n   - Valor total no pipeline\n\n6. **CSAT histórico** (use `lionchat_csat_list` filtrando por contact_id se possível, senão por conversas dele):\n   - Notas recebidas, feedbacks\n   - Tendência (melhorando/piorando)\n\n7. **Preenchimentos e agendamentos**:\n   - Histórico de formulários (use `lionchat_contacts_form_entries_list` — nosso formulário, anúncio do Meta, Webhook Universal e fluxo, numa lista só; `_show` abre o detalhe)\n   - Agendamentos: leia pela TAREFA da Agenda (`lionchat_tasks_list` filtrando tarefas com booking) — `bookings.status` NÃO diz se o agendamento aconteceu (fica `confirmed` mesmo depois de concluído/cancelado pela Agenda)\n\n8. **Engajamento** (calcule a partir dos dados):\n   - Frequência de interação (conversas/mês)\n   - Tempo desde última conversa (sinal de churn?)\n   - Taxa de resposta dele (incoming vs outgoing)\n\n## Apresentação\n\n```markdown\n# 👤 Cliente: [Nome] — Visão 360°\n\n## 📇 Identificação\n- **Email:** ...\n- **Telefone:** ...\n- **Empresa:** ...\n- **Cadastrado em:** DD/MM/YYYY (X meses atrás)\n- **Custom:** [campos relevantes do custom_attributes]\n\n## 📊 Status\n- **Health Score:** 🟢 Saudável / 🟡 Atenção / 🔴 Risco\n- **Última interação:** DD/MM/YYYY (X dias atrás)\n- **Conversas totais:** N | Abertas: M | Resolvidas: K\n- **CSAT médio:** X⭐ (baseado em N respostas)\n\n## 💰 Pipeline (Kanban)\n- **Funil [X]:** Etapa Y — R$ Z (parado há W dias)\n- **Funil [X2]:** Etapa Y2 — R$ Z2\n\n## 💬 Última Conversa (#display_id)\n- **Data:** DD/MM HH:MM\n- **Status:** Aberta/Resolvida\n- **Agente:** Nome\n- **Resumo (2-3 linhas):** O que aconteceu na última interação\n- **Tom percebido:** Cordial / Frustrado / Satisfeito\n\n## ⚠️ Sinais de Alerta\n[Lista sinais detectados:]\n- Sem interação há >30 dias\n- Última CSAT foi 2⭐\n- Card parado em \"Negociação\" há 21 dias\n- Cliente comentou \"vou avaliar concorrentes\"\n\n## 💡 Próximos Passos Sugeridos\n[2-3 ações concretas:]\n1. Ligar pra entender por que parou de responder\n2. Mover card pra etapa \"Em risco\"\n3. Enviar pesquisa de feedback\n```\n\n## Health Score (como calcular)\n\n- 🟢 **Saudável:** última interação <30d + CSAT ≥4 + sem sinais negativos\n- 🟡 **Atenção:** última interação 30-90d OU CSAT 3-3.9 OU card parado >14d\n- 🔴 **Risco:** última interação >90d OU CSAT <3 OU múltiplos cards parados OU mensagens frustradas recentes\n\n## Importante\n\n- Seja honesto no Health Score. Não infle: 🟢 só se realmente saudável.\n- **Não invente sinais.** Só liste o que viu nos dados.\n- Se cliente é novo (<30 dias), avise: \"Pouco histórico, score preliminar\".\n- Se múltiplos contatos com o mesmo nome, peça pra desambiguar antes de continuar.\n- Datas em PT-BR (DD/MM/YYYY)."
 }

package/dist/docs/prompts/productivity_report.json

@@ -9,5 +9,5 @@
       "required": false
     }
   ],
-  "template": "Gere um **Relatório de Produtividade da Equipe** dos últimos {{period_days|7}} dias.\n\n## Passos a executar\n\n1. **Calcule o período:** since = {{period_days|7}} dias atrás (Unix timestamp em segundos), until = agora\n\n2. **Resumo geral da conta** (use `lionchat_reports_summary` com type='account', business_hours=true):\n   - Total de conversas, taxa de resolução, tempo médio de primeira resposta e resolução\n   - Compare com período anterior (campo `previous` da resposta)\n\n3. **Performance por agente** (use `lionchat_reports_list` com type='agent', mesmo since/until):\n   - Liste cada agente com: conversas atendidas, avg_first_response_time, avg_resolution_time\n   - ATENÇÃO: o relatório por agente NÃO traz CSAT médio nem status online. Pegue o CSAT por agente separadamente: `lionchat_csat_list` filtrando por `user_ids` (id do agente) no mesmo período e calcule a média das notas dele.\n   - Identifique TOP 3 (por volume + qualidade combinados)\n   - Identifique 3 com maior tempo de resposta (potenciais gargalos)\n\n4. **CSAT** (use `lionchat_csat_metrics` com mesmo período):\n   - Média geral, distribuição (5⭐, 4⭐, ...)\n   - Taxa de resposta CSAT\n\n5. **SLA** (use `lionchat_sla_metrics` se disponível):\n   - Hit rate, breach count\n\n## Como apresentar\n\nFormate em **markdown** com:\n\n```markdown\n# 📊 Relatório de Produtividade — Últimos {{period_days|7}} dias\n\n## Visão Geral\n| Métrica | Esta semana | Semana anterior | Variação |\n|---|---|---|---|\n| Conversas | X | Y | +/-Z% |\n| Tempo médio 1ª resposta | X min | Y min | +/-Z% |\n| Tempo médio resolução | X h | Y h | +/-Z% |\n| Taxa de resolução | X% | Y% | +/-Z% |\n\n## Top 3 Agentes\n1. **Nome** — X conversas, Y min 1ª resposta, CSAT Z⭐\n2. ...\n3. ...\n\n## Pontos de Atenção\n- Agente XYZ com tempo de resposta 3x acima da média\n- Inbox WhatsApp com volume crescendo\n\n## CSAT\n- Média: X⭐ (anterior: Y⭐)\n- Taxa de resposta: Z%\n\n## SLA\n- Hits: X% (meta 95%)\n- Breaches: Y conversas\n```\n\n## Conversões importantes\n\n- TODOS os tempos retornados estão em **segundos**. Converta:\n  - < 60s → mostre em segundos\n  - 60-3600s → mostre em minutos (`X min`)\n  - 3600-86400s → mostre em horas (`X h Y min`)\n  - \\> 86400s → mostre em dias\n- Datas: use formato brasileiro (DD/MM ou DD/MM HH:MM)\n- Taxas (CSAT, SLA hit rate): mostre como %\n\n## Importante\n\n- Se não tiver dados suficientes (período sem atividade), diga claramente em vez de inventar números\n- Se algum agente tem 0 conversas, OMITA da listagem em vez de mostrar zerado (não inflar lista)\n- Use emojis com moderação (📊 ⭐ 🚨) — máximo 1 por seção"
+  "template": "Gere um **Relatório de Produtividade da Equipe** dos últimos {{period_days|7}} dias.\n\n## Passos a executar\n\n1. **Calcule o período:** since = {{period_days|7}} dias atrás (Unix timestamp em segundos), until = agora. Leia `timezone` em `lionchat_account_show` e mande `timezone_offset` (em horas, derivado desse fuso) nas chamadas de relatório — não assuma -3 (MS/MT/AM são -4 e há cliente fora do Brasil).\n\n2. **Resumo geral da conta** (use `lionchat_reports_summary` com type='account', business_hours=true):\n   - Total de conversas, taxa de resolução, tempo médio de primeira resposta e resolução\n   - Compare com período anterior (campo `previous` da resposta)\n\n3. **Performance por agente** (use `lionchat_reports_list` com type='agent', mesmo since/until):\n   - Liste cada agente com: conversas atendidas, avg_first_response_time, avg_resolution_time\n   - ATENÇÃO: o relatório por agente NÃO traz CSAT médio nem status online. Pegue o CSAT por agente separadamente: `lionchat_csat_list` filtrando por `user_ids` (id do agente) no mesmo período e calcule a média das notas dele.\n   - Identifique TOP 3 (por volume + qualidade combinados)\n   - Identifique 3 com maior tempo de resposta (potenciais gargalos)\n\n4. **CSAT** (use `lionchat_csat_metrics` com mesmo período):\n   - Média geral, distribuição (5⭐, 4⭐, ...)\n   - Taxa de resposta CSAT\n\n5. **SLA** (use `lionchat_sla_metrics` se disponível):\n   - Hit rate, breach count\n   - Nota: o prazo é conferido a cada 5 min, espalhado em até 2 min — um estouro pode aparecer até ~7 min depois do horário-limite. Não conclua que o SLA não está rodando por isso.\n\n## Como apresentar\n\nFormate em **markdown** com:\n\n```markdown\n# 📊 Relatório de Produtividade — Últimos {{period_days|7}} dias\n\n## Visão Geral\n| Métrica | Esta semana | Semana anterior | Variação |\n|---|---|---|---|\n| Conversas | X | Y | +/-Z% |\n| Tempo médio 1ª resposta | X min | Y min | +/-Z% |\n| Tempo médio resolução | X h | Y h | +/-Z% |\n| Taxa de resolução | X% | Y% | +/-Z% |\n\n## Top 3 Agentes\n1. **Nome** — X conversas, Y min 1ª resposta, CSAT Z⭐\n2. ...\n3. ...\n\n## Pontos de Atenção\n- Agente XYZ com tempo de resposta 3x acima da média\n- Inbox WhatsApp com volume crescendo\n\n## CSAT\n- Média: X⭐ (anterior: Y⭐)\n- Taxa de resposta: Z%\n\n## SLA\n- Hits: X% (meta 95%)\n- Breaches: Y conversas\n```\n\n## Conversões importantes\n\n- TODOS os tempos retornados estão em **segundos**. Converta:\n  - < 60s → mostre em segundos\n  - 60-3600s → mostre em minutos (`X min`)\n  - 3600-86400s → mostre em horas (`X h Y min`)\n  - \\> 86400s → mostre em dias\n- Datas: use formato brasileiro (DD/MM ou DD/MM HH:MM)\n- Taxas (CSAT, SLA hit rate): mostre como %\n\n## Importante\n\n- Se não tiver dados suficientes (período sem atividade), diga claramente em vez de inventar números\n- Se algum agente tem 0 conversas, OMITA da listagem em vez de mostrar zerado (não inflar lista)\n- Use emojis com moderação (📊 ⭐ 🚨) — máximo 1 por seção"
 }

package/dist/docs/prompts/quality_audit.json

@@ -24,5 +24,5 @@
       "required": false
     }
   ],
-  "template": "Faça uma auditoria de qualidade do atendimento nos últimos {{period_days|7}} dias.\n\nFiltros opcionais:\n- Agente: {{agent_id|todos}}\n- Inbox: {{inbox_id|todas}}\n\nAmostrar {{sample_size|20}} conversas RESOLVIDAS aleatoriamente desse período.\n\nPra cada conversa analisar:\n\n### Métricas Quantitativas\n- Tempo da primeira resposta (em minutos)\n- Tempo total de resolução\n- Número de mensagens trocadas\n- CSAT (se houver)\n- Foi reaberta depois? (indicador de problema mal resolvido)\n\n### Análise Qualitativa\n- Tom adequado? (formal/informal alinhado ao canal)\n- Cliente foi cumprimentado adequadamente?\n- Problema foi entendido na primeira interação?\n- Resposta foi clara e resolveu o problema?\n- Houve follow-up ou despedida adequada?\n- Erros gramaticais ou de português?\n\n### Red Flags a destacar\n- Tempo de primeira resposta > 30 min em horário comercial\n- Mais de 10 mensagens pra resolver questão simples\n- Resolução sem confirmação do cliente\n- Mensagens automáticas/copy-paste óbvios sem personalização\n- Tom inadequado (rude, robótico, condescendente)\n\n### Output\n\n## Sumário\n- Conversas auditadas: X\n- Qualidade Geral (1-10): Y\n- Tempo médio de primeira resposta\n- Taxa de reabertura\n\n## Top Problemas Encontrados\n(3-5 padrões recorrentes, com exemplos)\n\n## Top Boas Práticas Identificadas\n(2-3 exemplos pra replicar)\n\n## Recomendações\n- Treinamento focado em: ...\n- Templates de resposta padronizados pra: ...\n- Automações sugeridas: ...\n\nNão expor nomes de agentes em críticas públicas — apenas IDs em report interno."
+  "template": "Faça uma auditoria de qualidade do atendimento nos últimos {{period_days|7}} dias.\n\nFiltros opcionais:\n- Agente: {{agent_id|todos}}\n- Inbox: {{inbox_id|todas}}\n\nAmostrar {{sample_size|20}} conversas RESOLVIDAS aleatoriamente desse período.\n\nPra cada conversa analisar (pule mensagens com `content_attributes.deleted: true` — texto apagado pelo cliente — e sinalize conversas cujo último envio está com `status: failed`):\n\n### Métricas Quantitativas\n- Tempo da primeira resposta (em minutos)\n- Tempo total de resolução\n- Número de mensagens trocadas\n- CSAT (se houver)\n- Foi reaberta depois? (indicador de problema mal resolvido)\n\n### Análise Qualitativa\n- Tom adequado? (formal/informal alinhado ao canal)\n- Cliente foi cumprimentado adequadamente?\n- Problema foi entendido na primeira interação?\n- Resposta foi clara e resolveu o problema?\n- Houve follow-up ou despedida adequada?\n- Erros gramaticais ou de português?\n\n### Red Flags a destacar\n- Tempo de primeira resposta > 30 min em horário comercial\n- Mais de 10 mensagens pra resolver questão simples\n- Resolução sem confirmação do cliente\n- Mensagens automáticas/copy-paste óbvios sem personalização\n- Tom inadequado (rude, robótico, condescendente)\n\n### Output\n\n## Sumário\n- Conversas auditadas: X\n- Qualidade Geral (1-10): Y\n- Tempo médio de primeira resposta\n- Taxa de reabertura\n\n## Top Problemas Encontrados\n(3-5 padrões recorrentes, com exemplos)\n\n## Top Boas Práticas Identificadas\n(2-3 exemplos pra replicar)\n\n## Recomendações\n- Treinamento focado em: ...\n- Templates de resposta padronizados pra: ...\n- Automações sugeridas: ...\n\nNão expor nomes de agentes em críticas públicas — apenas IDs em report interno."
 }

package/dist/docs/prompts/stuck_leads.json

@@ -14,5 +14,5 @@
       "required": false
     }
   ],
-  "template": "Encontre **leads parados no Kanban há mais de {{days_stuck|7}} dias** e gere um plano de ação.\n\n## Passos\n\n1. **Lista funis ativos** (use `lionchat_funnels_list`):\n   - Se {{funnel_id}} foi passado, filtra só ele\n   - Senão, lista todos não-arquivados\n\n2. **Para cada funil, lista cards** (use `lionchat_kanban_items_list` ou `lionchat_kanban_items_filter`):\n   - Filtre por `stage_entered_at` < {{days_stuck|7}} dias atrás\n   - Ordene por `item_details.value` desc (maiores valores primeiro)\n   - Pegue top 20 (não inunde o usuário)\n\n3. **Para cada card relevante, busque contexto** (se houver `conversation_display_id`):\n   - Use `lionchat_conversations_show` pra pegar última atividade\n   - Verifique se conversa ainda está ativa\n\n4. **Categorize por gravidade**:\n   - 🔴 CRÍTICO: parado >14 dias E valor > R$ 5.000\n   - 🟡 ATENÇÃO: parado >7 dias E valor > R$ 1.000\n   - 🟢 MONITORAR: parado >7 dias E valor < R$ 1.000\n\n## Apresentação\n\n```markdown\n# 🚨 Leads Parados — Kanban\n\n**Critério:** parados há mais de {{days_stuck|7}} dias.\n**Encontrados:** N cards.\n\n## 🔴 Críticos (urgente)\n\n### Lead: [Nome do contato] — R$ X.XXX\n- **Funil:** Nome do funil\n- **Etapa:** Nome da etapa (parado há X dias)\n- **Última conversa:** Y dias atrás\n- **Ação sugerida:** Reabrir conversa / Ligar / Mover pra Perdido\n\n## 🟡 Atenção\n...\n\n## 🟢 Monitorar\n...\n\n## Resumo\n- Total parado: N cards (R$ X em valor combinado)\n- Tempo médio parado: Y dias\n- Etapa com mais parados: [nome]\n```\n\n## Ações sugeridas (escolha com base no contexto)\n\n- **Última conversa <7 dias:** Reabra a conversa e dê follow-up\n- **Última conversa 7-30 dias:** Envie mensagem de reengajamento\n- **Última conversa >30 dias:** Considere mover pra etapa \"Perdido\" (não vale manter no funil)\n- **Sem conversa nenhuma:** Crie conversa de outreach\n- **Valor alto + parado >14 dias:** Sinalize pra você (o usuário) ligar pessoalmente\n\n## Importante\n\n- Não execute ações automaticamente — apenas SUGIRA. O usuário decide.\n- Se a quantidade for grande (>50 cards), peça permissão antes de listar todos.\n- Use valores reais (não invente). Se um card não tem `value`, mostre \"sem valor\".\n- Datas em formato brasileiro (DD/MM/YYYY)."
+  "template": "Encontre **leads parados no Kanban há mais de {{days_stuck|7}} dias** e gere um plano de ação.\n\n## Passos\n\n1. **Lista funis ativos** (use `lionchat_funnels_list`):\n   - Se {{funnel_id}} foi passado, filtra só ele\n   - Senão, lista todos não-arquivados\n\n2. **Para cada funil, lista cards** (use `lionchat_kanban_items_list` ou `lionchat_kanban_items_filter`):\n   - Filtre por `stage_entered_at` < {{days_stuck|7}} dias atrás\n   - Ordene por `item_details.value` desc (maiores valores primeiro)\n   - Pegue top 20 (não inunde o usuário)\n\n3. **Para cada card relevante, busque contexto** (se houver `conversation_display_id`):\n   - Use `lionchat_conversations_show` pra pegar última atividade\n   - Verifique se conversa ainda está ativa\n\n4. **Categorize por gravidade**:\n   - 🔴 CRÍTICO: parado >14 dias E valor > R$ 5.000\n   - 🟡 ATENÇÃO: parado >7 dias E valor > R$ 1.000\n   - 🟢 MONITORAR: parado >7 dias E valor < R$ 1.000\n\n## Apresentação\n\n```markdown\n# 🚨 Leads Parados — Kanban\n\n**Critério:** parados há mais de {{days_stuck|7}} dias.\n**Encontrados:** N cards.\n\n## 🔴 Críticos (urgente)\n\n### Lead: [Nome do contato] — R$ X.XXX\n- **Funil:** Nome do funil\n- **Etapa:** Nome da etapa (parado há X dias)\n- **Última conversa:** Y dias atrás\n- **Ação sugerida:** Reabrir conversa / Ligar / Mover pra Perdido\n\n## 🟡 Atenção\n...\n\n## 🟢 Monitorar\n...\n\n## Resumo\n- Total parado: N cards (R$ X em valor combinado)\n- Tempo médio parado: Y dias\n- Etapa com mais parados: [nome]\n```\n\n## Ações sugeridas (escolha com base no contexto)\n\n- **Última conversa <7 dias:** Reabra a conversa e dê follow-up\n- **Última conversa 7-30 dias:** Envie mensagem de reengajamento\n- **Última conversa >30 dias:** Considere mover pra etapa \"Perdido\" (não vale manter no funil) — cite o slug REAL da etapa lido em `lionchat_funnels_show`, nunca um nome chutado\n- **Sem conversa nenhuma:** Crie conversa de outreach\n- **Valor alto + parado >14 dias:** Sinalize pra você (o usuário) ligar pessoalmente\n\n## Importante\n\n- Não execute ações automaticamente — apenas SUGIRA. O usuário decide.\n- Card \"invisível\" por estar numa etapa que o funil não tem NÃO existe mais (desde 19/08/2026 o card é redirecionado na gravação). Se o cliente reclamar de lead sumido, a causa é outra: arquivado ou em outro funil.\n- Se a quantidade for grande (>50 cards), peça permissão antes de listar todos.\n- Use valores reais (não invente). Se um card não tem `value`, mostre \"sem valor\".\n- Datas em formato brasileiro (DD/MM/YYYY)."
 }

package/dist/docs/prompts/team_load_balance.json

@@ -14,5 +14,5 @@
       "required": false
     }
   ],
-  "template": "Analise a carga de trabalho da equipe no período: {{period|week}}.\n\n{{team_id|Para todos os times.}}\nFiltrar por team_id={{team_id}} se especificado.\n\nDados a coletar pra cada agente:\n1. Conversas atribuídas (open + pending)\n2. Conversas resolvidas no período\n3. Tempo médio de primeira resposta\n4. Tempo médio de resolução\n5. % de conversas com CSAT (se houver) — NÃO vem do relatório por agente; pegue via `lionchat_csat_list` filtrando por `user_ids` (id do agente) no período\n6. Status atual: online / offline / busy — NÃO vem do relatório por agente; pegue via `lionchat_agent_availability_list`\n\nApresentar:\n\n## Visão Geral\n- Total de conversas ativas\n- Agentes online vs offline\n- Conversas sem atribuição (backlog)\n\n## Distribuição por Agente (tabela)\n| Agente | Ativas | Resolvidas | T. Resposta | T. Resolução | Status |\n\n## Identificar:\n- **Sobrecarregados**: > 1.5x média de conversas ativas → risco de queda na qualidade\n- **Subutilizados**: < 0.5x média → podem absorver mais\n- **Agentes offline com conversas pendentes**: redistribuir urgente\n- **Conversas órfãs**: sem assignee há > 1h → atribuir agora\n\n## Recomendações de ação\n- Lista de conversas pra reatribuir (com de → para)\n- Sugestão de revisão de assignment policy se houver desbalanceamento crônico\n- Conversas que talvez devam ser fechadas (sem resposta do cliente há > 7 dias)\n\nFinalizar perguntando se o usuário quer aplicar as redistribuições sugeridas."
+  "template": "Analise a carga de trabalho da equipe no período: {{period|week}}.\n\n{{team_id|Para todos os times.}}\nFiltrar por team_id={{team_id}} se especificado.\n\nDados a coletar pra cada agente:\n1. Conversas atribuídas (open + pending)\n2. Conversas resolvidas no período\n3. Tempo médio de primeira resposta\n4. Tempo médio de resolução\n5. % de conversas com CSAT (se houver) — NÃO vem do relatório por agente; pegue via `lionchat_csat_list` filtrando por `user_ids` (id do agente) no período\n6. Status atual: online / offline / busy — NÃO vem do relatório por agente; pegue via `lionchat_agent_availability_list`\n\nIgnore agentes com `replacing: true` em `lionchat_agents_list` (estão saindo — uma substituição está transferindo a carteira deles). A lista já exclui o agente de suporte da plataforma: ele não conta como membro da equipe.\n\nApresentar:\n\n## Visão Geral\n- Total de conversas ativas\n- Agentes online vs offline\n- Conversas sem atribuição (backlog)\n\n## Distribuição por Agente (tabela)\n| Agente | Ativas | Resolvidas | T. Resposta | T. Resolução | Status |\n\n## Identificar:\n- **Sobrecarregados**: > 1.5x média de conversas ativas → risco de queda na qualidade\n- **Subutilizados**: < 0.5x média → podem absorver mais\n- **Agentes offline com conversas pendentes**: redistribuir urgente\n- **Conversas órfãs**: sem assignee há > 1h → atribuir agora\n\n## Recomendações de ação\n- Lista de conversas pra reatribuir (com de → para)\n- Sugestão de revisão de assignment policy se houver desbalanceamento crônico\n- Se a causa do desbalanceamento for \"fulano saiu da empresa\", ofereça `lionchat_agents_replace` (troca o agente por outro e leva a carteira inteira) em vez de excluir + criar\n- Conversas que talvez devam ser fechadas (sem resposta do cliente há > 7 dias)\n\nFinalizar perguntando se o usuário quer aplicar as redistribuições sugeridas."
 }

package/dist/docs/prompts/weekly_recap.json

@@ -3,5 +3,5 @@
   "title": "Resumo Semanal Executivo",
   "description": "Resumo executivo de tudo que aconteceu na semana: atendimento, vendas (Kanban), IA, gargalos. Pensado pra quem precisa de visão rápida pra decidir.",
   "arguments": [],
-  "template": "Gere um **Resumo Executivo da Semana** — visão rápida pra tomar decisões.\n\n## Passos\n\n1. **Calcule período:** since = 7 dias atrás, until = agora\n\n2. **Atendimento** (use `lionchat_reports_summary`, business_hours=true):\n   - Total de conversas, resolvidas, abertas, pendentes\n   - Comparativo com semana anterior\n   - Tempo médio de resposta e resolução\n\n3. **Pipeline Kanban** (use `lionchat_funnels_list` + `lionchat_kanban_items_counts` por funil):\n   - Para cada funil: total de cards, valor total no funil, cards entrados na semana, cards movidos pra \"Fechado\"\n   - Calcular taxa de conversão (fechados / total entrados)\n\n4. **IA** (use `lionchat_captain_assistants_list`):\n   - Quantos assistentes ativos\n   - Conversas atendidas pela IA (campo `active_conversations_count`)\n\n5. **CSAT** (use `lionchat_csat_metrics`):\n   - Média da semana, comparativo com anterior\n\n6. **SLA** (use `lionchat_sla_metrics`):\n   - Hits e breaches\n\n7. **Top 3 Inboxes** (use `lionchat_reports_list_2`):\n   - Quais canais mais movimentaram\n\n## Apresentação\n\n```markdown\n# 📅 Resumo da Semana — DD/MM a DD/MM\n\n## 🎯 Destaque da Semana\n[Uma frase com o ponto mais importante: \"Crescemos 20% em conversas mas CSAT caiu 0.3⭐\" ou \"Funil Vendas com R$ 50K parados na etapa Proposta\"]\n\n## 📞 Atendimento\n- **N conversas** (vs N anterior, +/- X%)\n- **N resolvidas** (taxa: X%)\n- **Tempo médio 1ª resposta:** X min\n- **CSAT:** X⭐ (anterior: Y⭐)\n\n## 💰 Vendas (Pipeline)\n- **Funil [Nome]:** N cards (R$ XK total)\n  - Entraram: N | Fechados: M | Conversão: Z%\n  - Em risco (parados >7d): K cards\n\n## 🤖 IA\n- **N agentes ativos**\n- **N conversas atendidas** pela IA esta semana\n- Conversas resolvidas pela IA sem handoff: M (estimativa)\n\n## ⚠️ Pontos de Atenção\n- [3 alertas concretos, ex:]\n  - SLA: X conversas estouraram\n  - Funil Y com gargalo na etapa Z\n  - Agente W com tempo médio 2x acima da equipe\n\n## 💡 Recomendações\n[2-3 ações concretas pra próxima semana]\n```\n\n## Importante\n\n- **Seja conciso.** Resumo executivo = 1 página, não 5. Cortar > inflar.\n- **Compare sempre com semana anterior** (campo `previous` dos endpoints).\n- **Destaque tendências, não números crus.** \"Crescemos 20%\" > \"De 100 pra 120\".\n- **3 atenções, 3 recomendações.** Se quiser mais, peça permissão.\n- Use emojis (📅 📞 💰 🤖 ⚠️ 💡) — 1 por seção pra escaneabilidade rápida.\n- Datas em PT-BR (DD/MM/YYYY).\n- Valores em R$ (formato brasileiro: R$ 1.234,56)."
+  "template": "Gere um **Resumo Executivo da Semana** — visão rápida pra tomar decisões.\n\n## Passos\n\n1. **Calcule período:** since = 7 dias atrás, until = agora. Leia `timezone` em `lionchat_account_show` e mande `timezone_offset` (em horas, derivado desse fuso) em toda chamada de relatório — não assuma -3.\n\n2. **Relatório personalizado salvo?** (use `lionchat_custom_dashboards_list`): se a conta tem um relatório montado, leia os blocos dele com `lionchat_custom_dashboards_widget_data` passando `time_range: last_7_days` (e o `timezone_offset` da conta) em vez de remontar os números a partir de dez ferramentas.\n\n3. **Atendimento** (use `lionchat_reports_summary`, business_hours=true):\n   - Total de conversas, resolvidas, abertas, pendentes\n   - Comparativo com semana anterior\n   - Tempo médio de resposta e resolução\n\n4. **Pipeline Kanban** (use `lionchat_funnels_list` + `lionchat_kanban_items_counts` por funil):\n   - Para cada funil: total de cards e valor total no funil — `kanban_items_counts` é a FOTO atual, não \"da semana\"\n   - \"Cards entrados na semana\": `lionchat_custom_dashboards_preview_widget` com `widget_type: stage_entries` (conta card DISTINTO que ENTROU na etapa; `funnel_stages` subconta ~25%)\n   - \"Movidos pra Fechado\" e faturamento: `preview_widget` com `widget_type: funnel_stages` + `status: won` + `date_basis: closed` (+ `measure: value` pra somar o valor)\n   - Calcular taxa de conversão (fechados / total entrados)\n\n5. **IA** (use `lionchat_captain_assistants_list`):\n   - Quantos assistentes ativos\n   - Conversas atendidas pela IA (campo `active_conversations_count`)\n\n6. **CSAT** (use `lionchat_csat_metrics`):\n   - Média da semana, comparativo com anterior\n\n7. **SLA** (use `lionchat_sla_metrics`):\n   - Hits e breaches\n\n8. **Top 3 Inboxes** (use `lionchat_reports_list_2`):\n   - Quais canais mais movimentaram\n\n## Apresentação\n\n```markdown\n# 📅 Resumo da Semana — DD/MM a DD/MM\n\n## 🎯 Destaque da Semana\n[Uma frase com o ponto mais importante: \"Crescemos 20% em conversas mas CSAT caiu 0.3⭐\" ou \"Funil Vendas com R$ 50K parados na etapa Proposta\"]\n\n## 📞 Atendimento\n- **N conversas** (vs N anterior, +/- X%)\n- **N resolvidas** (taxa: X%)\n- **Tempo médio 1ª resposta:** X min\n- **CSAT:** X⭐ (anterior: Y⭐)\n\n## 💰 Vendas (Pipeline)\n- **Funil [Nome]:** N cards (R$ XK total)\n  - Entraram: N | Fechados: M | Conversão: Z%\n  - Em risco (parados >7d): K cards\n\n## 🤖 IA\n- **N agentes ativos**\n- **N conversas atendidas** pela IA esta semana\n- Conversas resolvidas pela IA sem handoff: M (estimativa)\n\n## ⚠️ Pontos de Atenção\n- [3 alertas concretos, ex:]\n  - SLA: X conversas estouraram\n  - Funil Y com gargalo na etapa Z\n  - Agente W com tempo médio 2x acima da equipe\n\n## 💡 Recomendações\n[2-3 ações concretas pra próxima semana]\n```\n\n## Importante\n\n- **Seja conciso.** Resumo executivo = 1 página, não 5. Cortar > inflar.\n- **Compare sempre com semana anterior** (campo `previous` dos endpoints).\n- **Destaque tendências, não números crus.** \"Crescemos 20%\" > \"De 100 pra 120\".\n- **3 atenções, 3 recomendações.** Se quiser mais, peça permissão.\n- Use emojis (📅 📞 💰 🤖 ⚠️ 💡) — 1 por seção pra escaneabilidade rápida.\n- Datas em PT-BR (DD/MM/YYYY).\n- Valores em R$ (formato brasileiro: R$ 1.234,56)."
 }

package/dist/docs/prompts/whatsapp_template_usage.json

@@ -14,5 +14,5 @@
       "required": false
     }
   ],
-  "template": "Analise o uso de templates WhatsApp Business nos últimos {{period_days|30}} dias.\n\nInbox: {{inbox_id|todas as inboxes WhatsApp Cloud}}\n\nDados a levantar:\n\n## 1. Inventário de Templates\n- Total de templates aprovados (status: APPROVED)\n- Pendentes de aprovação (PENDING)\n- Rejeitados (REJECTED) — listar motivos\n- Templates por categoria (UTILITY, MARKETING, AUTHENTICATION)\n- Templates por idioma\n\n## 2. Uso no Período\nPra cada template usado:\n- Nome do template\n- Quantas vezes foi enviado\n- Quantas conversas geraram resposta dentro de 24h\n- Taxa de resposta (% que responderam)\n- Taxa de conversão (se for marketing — virou venda/lead qualificado?)\n\n## 3. Templates Inativos\nListar templates aprovados HÁ MAIS DE 30 DIAS que NÃO foram usados no período.\n- Por quê? Esquecidos? Substituídos por novo?\n- Sugestão: arquivar / atualizar / promover uso\n\n## 4. Performance dos Top Templates\nTop 5 mais enviados — analisar:\n- Texto do template\n- Taxa de resposta\n- Tempo médio até resposta\n- Tem variáveis personalizadas? ({{nome}}, etc)\n- Categoria correta? (errar categoria = risco de banimento)\n\n## 5. Red Flags\n- Templates marketing sendo usados em janela 24h (deveriam ser utility)\n- Templates rejeitados não removidos\n- Templates aprovados há > 90 dias e nunca usados\n- Templates duplicados (mesma intenção, várias versões)\n\n## Recomendações\n- Templates a criar (gap identificado)\n- Templates a remover (desuso ou redundância)\n- Templates a otimizar (baixa conversão)\n- Sugestão de A/B test entre 2 versões de um mesmo template\n\nFinalizar com sugestão de criar nova campanha usando o template com melhor performance."
+  "template": "Analise o uso de templates WhatsApp Business nos últimos {{period_days|30}} dias.\n\nInbox: {{inbox_id|todas as inboxes WhatsApp Cloud}}\n\nDados a levantar:\n\n## 1. Inventário de Templates\n- Total de templates aprovados (status: APPROVED)\n- Pendentes de aprovação (PENDING)\n- Rejeitados (REJECTED) — listar motivos\n- Templates por categoria (UTILITY, MARKETING, AUTHENTICATION)\n- Templates por idioma\n\n## 2. Uso no Período\nPra cada template usado:\n- Nome do template\n- Quantas vezes foi enviado\n- Quantas conversas geraram resposta dentro de 24h\n- Taxa de resposta (% que responderam)\n- Taxa de conversão (se for marketing — virou venda/lead qualificado?)\n\n## 3. Templates Inativos\nListar templates aprovados HÁ MAIS DE 30 DIAS que NÃO foram usados no período.\n- Por quê? Esquecidos? Substituídos por novo?\n- Sugestão: arquivar / atualizar / promover uso\n\n## 4. Performance dos Top Templates\nTop 5 mais enviados — analisar:\n- Texto do template\n- Taxa de resposta\n- Tempo médio até resposta\n- Tem variáveis personalizadas? ({{nome}}, etc)\n- Categoria correta? (errar categoria = risco de banimento)\n\n## 5. Red Flags\n- Templates marketing sendo usados em janela 24h (deveriam ser utility)\n- Templates rejeitados não removidos\n- Templates aprovados há > 90 dias e nunca usados\n- Templates duplicados (mesma intenção, várias versões)\n- Mensagens com `additional_attributes.template_param_fallback` preenchido = clientes que receberam \".\" no lugar da variável (posição vazia não falha mais — sai como ponto)\n- Falhas classificadas como `account_locked` (erro 131031) NÃO são do template — é a conta comercial trancada na Meta\n\n## Recomendações\n- Templates a criar (gap identificado)\n- Templates a remover (desuso ou redundância)\n- Templates a otimizar (baixa conversão)\n- Sugestão de A/B test entre 2 versões de um mesmo template\n\nFinalizar com sugestão de criar nova campanha usando o template com melhor performance."
 }

package/dist/docs/resources/api-conventions.md

@@ -462,6 +462,25 @@ O `field_mapping` do webhook personalizado aceita caminhos com índice de array:
 mesmo caminho captura valores diferentes. Campo `flow_id` na criação liga o webhook a um flow
 (webhook embutido — ver resource de fluxos).
 
+**Destino "atributo da CONVERSA" no `field_mapping` (2026-08-21 — entra com o próximo deploy do
+app depois de 21/08/2026):** além de `contact_attr_<chave>`, o valor de um campo pode ser
+`conversation_attr_<chave>` — vale no Webhook Universal, no webhook embutido de flow E no formulário
+do Meta Lead Ads (mesmo mapeador). O atributo é gravado na conversa que a automação/fluxo mapeado
+ABRIR para aquele lead (sem automação/fluxo não nasce conversa e o valor é descartado). Serve pro
+que muda a cada atendimento (produto comprado agora, valor, formulário de hoje); no contato a 2ª
+compra apaga a 1ª.
+
+Regras do gravador (valem pra Webhook Universal, Meta Lead e os 9 gateways de pagamento):
+- **Chave reservada é recusada**: as `captain_*` (caderno da IA) e as de sistema `imported_from`,
+  `import_digits`, `mail_subject`, `type`, `in_reply_to`, `initiated_by`, `auto_reply`,
+  `original_channel_type`, `conversation_language`, `agent_reply_time_window`, `conference_sid`,
+  `call_status`, `tiktok_capabilities`, `captain_media_asset_id`. Nunca mapeie pra elas —
+  `imported_from` sobrescrita fazia a conversa SUMIR das telas.
+- **Converte pelo TIPO do atributo** (data em formato brasileiro, decimal com vírgula ou ponto,
+  sim/não) e **descarta** o que não entende — texto num atributo de Número não é gravado (e não dá
+  erro: aparece só no log do servidor). Confira o tipo em `custom_attributes_list` antes de mapear.
+- **Silencioso**: atributo gravado por integração NÃO dispara automação, flow nem webhook de saída.
+
 ### Import de histórico do WhatsApp Cloud (2026-06)
 
 Caixas WhatsApp Cloud API podem importar o histórico de conversas via QR Code. Tools sob

package/dist/docs/resources/best-practices.md

@@ -559,12 +559,18 @@ opcional `variable_mapping` junto.
 
 1. **Tira o modelo do alcance do AI Agente.** Basta UMA variável sem mapping para o modelo inteiro
    deixar de ser oferecido no follow-up automático fora da janela de 24h.
-2. **Faz o envio manual falhar** com o erro `#132000` da Meta (número de parâmetros não bate).
+2. **Faz a mensagem sair com um PONTO no lugar da variável.** Desde 04/08/2026 posição sem valor
+   não derruba mais o envio (antes era `#132000`): o sistema preenche `.` e entrega — "Olá ., sua
+   consulta é dia ." chega assim pro cliente, marcado como sucesso. Rastro:
+   `additional_attributes.template_param_fallback` na mensagem (lista das posições preenchidas com
+   o piso). Numa campanha isso vira dezenas de clientes recebendo ponto (caso real 21/08: 65
+   pessoas).
 
 Vale para os dois formatos de marcador: posicional (`{{1}}`) e nomeado (`{{nome_cliente}}`).
 
-> Ao registrar modelo por API, **mapeie todas as variáveis do corpo** — ou preencha na hora do envio
-> via `processed_params`. Modelo com variável órfã é modelo que a IA não usa e que o disparo derruba.
+> Ao registrar modelo por API, **mapeie todas as variáveis do corpo** — ou preencha TODAS as
+> posições em `processed_params` na hora do envio/campanha, e confira antes de criar a campanha que
+> nenhuma está vazia. Modelo com variável órfã é modelo que a IA não usa e que entrega ponto.
 
 Confira o que ficou de fora lendo o modelo com `lionchat_inboxes_whatsapp_templates_list` e
 comparando os `{{...}}` do texto do BODY com as chaves do `variable_mapping`.

package/dist/docs/resources/conversation-flows.md

@@ -282,6 +282,18 @@ valor**. A conversa mantém a origem com que nasceu e só ganha o que ainda não
 notificação e a Agenda não rodam. Se o seu fluxo depende de um desses, ele não vai acontecer
 quando houver reuso.
 
+**Caixa de rede social só é "contactável" se a pessoa já falou por ela (desde 19/08/2026).**
+`lionchat_contacts_list_3` (`/contacts/{id}/contactable_inboxes`) lista Facebook, Instagram,
+Telegram, Line, TikTok e X **apenas quando o contato já tem crachá naquela caixa** — nesses canais
+não existe "começar conversa pelo telefone" (a Meta recusa). Se a caixa social não aparece na lista,
+não tente `conversations_create` nela: a conversa nasceria e nunca entregaria. WhatsApp (oficial e
+QR Code), SMS e e-mail continuam contactáveis pelo telefone/e-mail da ficha.
+
+**Telefone com ou sem o 9º dígito na caixa OFICIAL (desde 19/08/2026):** criar conversa pra um
+contato cuja ficha está sem o 9 (ou com) REUSA o endereço que a caixa já tem pra essa pessoa, em vez
+de abrir um segundo — era isso que partia a conversa em duas (lembrete numa, resposta do paciente
+em outra). O `source_id` devolvido pode vir no outro formato do que você mandou; é o mesmo cliente.
+
 ## Estado relacional
 
 ```
@@ -523,6 +535,17 @@ ficar muda (2026-06-05).
 | `message_created` | Nova mensagem (incoming ou outgoing) |
 | `first_reply_created` | Primeira resposta humana |
 
+### Gatilhos de Agendamento (Booking nativo) — 2026-08-20
+
+O Booking do LionChat (Agenda → aba Booking, link público, IA) também dispara flow pelo node
+`start`: `booking_created`, `booking_cancelled`, `booking_rescheduled`, `booking_completed`.
+Config opcional `{ booking_event_type_ids: ["44"], agent_ids: [], create_conversation: false }`
+(vazio = todos; `create_conversation: true` cria a conversa na 1ª caixa do flow para quem nunca
+conversou). Variáveis `{{booking.*}}` (data, hora, tipo, agente, links de remarcar/cancelar,
+horário anterior no remarcado). Detalhe completo e regras no `lionchat://docs/flowbuilder-design-guide`
+(seção "Gatilhos de AGENDAMENTO"). **Não confundir com os lembretes da e-Clínica** (integração
+separada). Também NÃO são eventos de `automation_rule`.
+
 **Os gatilhos de Formulário público (`lead_form_completed`, `lead_form_milestone`,
 `lead_form_abandoned`) NÃO entram nessa tabela** — são gatilhos de **flow**, não eventos de
 automação. Não adianta criar `automation_rule` com esses nomes em `event_name`; o caminho é o node

package/dist/docs/resources/data-model.md

@@ -364,24 +364,44 @@ AccountTask (agenda interna)
 ├── conversation_id / contact_id / linked_kanban_item_id (FK opcionais)
 └── assignees (has_many → User, via account_task_assignments)
 
-BookingEventType (template de agendamento)
+BookingEventType (template de agendamento — tools `booking_event_types_*`; colunas de
+db/schema.rb, tabela booking_event_types)
+├── id (PK) / account_id (FK) / user_id (FK → agente padrão)
+├── title (ex: "Demo 30min") / description / slug (endereço público próprio)
+├── duration_minutes / slot_granularity_minutes / buffer_minutes
+├── min_notice_hours / max_advance_days / max_per_day / available_from / available_until
+├── task_type (meeting/video_call — `video_call` gera Meet)
+├── timezone (IANA — o fuso dos horários é SEMPRE o do tipo, nunca o do navegador)
+├── color (hex `#RRGGBB`, opcional — cor dos compromissos desse tipo no calendário; vazio = cor do
+│   agente; 2026-08-19)
+├── active / ask_email / ask_description
+├── confirmation_* (mensagem de confirmação própria: enabled, inbox_id, channel_type,
+│   template_name, blocks)
+└── booking_availabilities (has_many — dias/horários; `booking_availabilities_attributes` no create)
+
+Booking (agendamento confirmado — tabela bookings)
 ├── id (PK)
-├── account_id (FK)
-├── name (ex: "Demo 30min")
-├── duration_minutes
-├── availability_rules (jsonb)
-└── description
-
-Booking (agendamento confirmado)
-├── id (PK)
-├── account_id (FK)
-├── booking_event_type_id (FK)
-├── user_id (FK, agente que vai atender)
-├── attendee_name / attendee_email / attendee_phone
-├── start_time / end_time (ISO 8601)
-├── status (scheduled/cancelled/completed)
-└── meeting_url (Google Calendar / Zoom / etc)
-```
+├── account_id (FK) / booking_event_type_id (FK) / account_task_id (FK 1:1 → AccountTask)
+├── contact_id (FK) / guest_name / guest_email / guest_phone / guest_description
+├── scheduled_at / duration_minutes
+├── status (confirmed/cancelled/completed) — **NÃO acompanha a Agenda**: concluir ou cancelar pela
+│   tela da Agenda (o caminho normal da equipe) deixa o booking em `confirmed`. A situação real é
+│   `account_tasks.status` (pending/completed/cancelled/snoozed) da tarefa vinculada — é ela que o
+│   relatório de Agendamentos e os gatilhos `booking_*` do FlowBuilder leem
+├── cancelled_at / cancellation_reason / confirmation_sent_at / utm_params
+└── (o agente responsável e o `meeting_url` moram na TAREFA: `account_tasks.user_id` e
+    `account_tasks.meeting_url`)
+```
+
+**Duração sob medida (2026-08-19):** ao marcar pelo painel/API (`lionchat_tasks_create` com
+`booking_event_type_id`) pode-se mandar `duration_minutes` diferente do tipo (5 a 1440; fora da
+faixa o sistema usa a do tipo). A lista de horários livres aceita o mesmo parâmetro
+(`lionchat_booking_event_types_slots?date=AAAA-MM-DD&duration_minutes=60`) e **os horários mudam**
+— 60 min num tipo de 30 some com os encaixes que não cabem. Sempre peça os slots com a MESMA duração
+que vai gravar. A página pública e a IA não têm essa opção (duração do tipo, sempre).
+
+**Cor por tipo (2026-08-19):** `booking_event_types.color` (hex `#RRGGBB`) pinta os compromissos
+daquele tipo no calendário; vazio = cor do agente. A tarefa devolve `booking_color` já resolvido.
 
 **Atributos de sistema do Booking no CONTATO (novo 2026-07-06):** ao confirmar um agendamento,
 8 custom attributes protegidos são gravados no contato — usáveis como variável
@@ -400,13 +420,19 @@ Booking (agendamento confirmado)
 
 ## e-Clínicas (Efficient) — integração de clínicas
 
-13 eventos de webhook, cada um mapeável a automação OU flow na tela Integrações > e-Clínica:
+15 eventos de webhook, cada um mapeável a automação OU flow na tela Integrações > e-Clínica
+(o mapeamento é SÓ pela tela — não há ferramenta MCP que escreva `event_mapping`):
 `cliente_novo`, `agendamento_novo`, `falta`, `pagamento` (os 4 da doc oficial) +
 `agendamento_atendido`, `agendamento_alterado`, `agendamento_desmarcado`,
 `agendamento_transferido`, `cliente_baixa_pagamento`, `cliente_alteracao`,
-`cliente_inclusao_pagamento`, `controle_laboratorio_novo`, `controle_laboratorio_alterado`
+`cliente_inclusao_pagamento`, `controle_laboratorio_novo`, `controle_laboratorio_alterado`,
+`agendamento_aguardando`, `odontograma_aprovado`
 (capturados ao vivo, não documentados pelo e-Clínica).
 
+Os 2 últimos são do perfil ODONTOLÓGICO (2026-08-20): `agendamento_aguardando` = a recepção marcou a
+chegada do paciente na clínica (grava a hora da chegada e `eclinica_status_agendamento = aguardando`);
+`odontograma_aprovado` = plano de tratamento aprovado (grava o cabeçalho do odontograma).
+
 Atributos de sistema no CONTATO (prefixo `eclinica_`, protegidos, usáveis como variável):
 
 | Chave | Tipo | Conteúdo |
@@ -417,8 +443,8 @@ Atributos de sistema no CONTATO (prefixo `eclinica_`, protegidos, usáveis como
 | `eclinica_data_consulta` | date | Data da consulta, ISO |
 | `eclinica_hora_consulta` | **time** | Hora da consulta 24h `"HH:MM"` (novo 2026-07-06) |
 | `eclinica_hora_final` | **time** | Hora final da consulta (novo 2026-07-27) |
-| `eclinica_status_agendamento` | text | agendado / no_show / atendido / desmarcado |
-| `eclinica_situacao` | text | Situação crua da agenda (age_situacao do webhook) |
+| `eclinica_status_agendamento` | text | `agendado` / `aguardando` (paciente chegou) / `no_show` / `atendido` / `desmarcado`. Vem do TIPO do evento, nunca da letra da situação. **Estado terminal do MESMO agendamento não volta pra `agendado`** (2026-08-20): a e-Clínica manda `agendamento_alterado` a cada edição da consulta, inclusive depois da chegada/atendimento, e isso NÃO reabre o status. Consulta com `eclinica_idagenda` DIFERENTE nasce `agendado` |
+| `eclinica_situacao` | text | Situação do agendamento no painel, **POR EXTENSO** (2026-08-21, legenda oficial da e-Clínica): AGUARDANDO, NA CADEIRA, PASSAR FINANCEIRO, AGENDAR RETORNO, ATENDIDO, CONFIRMADO, CONFIRMADO PELO LINK, CONFIRMADO PELA API, FALTA, DESMARCADO, CANCELADO PELO LINK, CANCELADO PELA API. Antes guardava a letra crua (`A`, `C`…). Código nunca visto aparece como veio |
 | `eclinica_compromisso` | text | Tipo da consulta — TEXTO LIVRE da recepção (ex: Consulta, Retorno) |
 | `eclinica_agendatipo` | text | Tipo de Agendamento — NOME da lista fixa do painel, resolvido por unidade (novo 2026-07-28). **Filtrar sempre pelo NOME, nunca pelo número: os números colidem entre filiais** |
 | `eclinica_agendatipo_id` | text | Tipo de Agendamento — número cru (não comparável entre filiais) |
@@ -430,6 +456,17 @@ Atributos de sistema no CONTATO (prefixo `eclinica_`, protegidos, usáveis como
 | `eclinica_ultimo_pagamento` | text | Valor do último pagamento |
 | `eclinica_ultimo_pagamento_data` | date | Data do último pagamento/baixa (novo 2026-07-06) |
 | `eclinica_ultimo_pagamento_descricao` | text | Descrição da baixa (ex: CONSULTA INICIAL) |
+| `eclinica_ultima_chegada_idagenda` | text | Agendamento em que o paciente chegou pela última vez (2026-08-20) |
+| `eclinica_ultima_chegada_data` | date | Data da última chegada do paciente na clínica |
+| `eclinica_ultima_chegada_hora` | **time** | Hora em que a recepção marcou a chegada (`age_horaguardando`, ex `15:06`) |
+| `eclinica_odontograma_id` | text | ID do último odontograma/plano de tratamento aprovado (2026-08-20) |
+| `eclinica_odontograma_aprovado_em` | date | Dia da aprovação, já no fuso da conta (o webhook manda em UTC) |
+| `eclinica_odontograma_inicio` | date | Data de início do tratamento (`odo_datainicio`) |
+| `eclinica_odontograma_situacao` | text | Código de situação como vem da e-Clínica (ex: `T`) |
+| `eclinica_odontograma_valor` | text | Valor do plano — **pode vir `0.00`** quando a clínica não preenche |
+| `eclinica_odontograma_profissional` | text | NOME do profissional do odontograma |
+| `eclinica_odontograma_convenio_id` | text | Convênio do odontograma (número) |
+| `eclinica_marcador_nome` | text | Marca que a clínica digita no fim do nome do paciente no e-Clínica (ex: `*`, `***`) — retirada do nome e guardada aqui (2026-08-20). Significado é da clínica |
 | `eclinica_laboratorio_data_prevista` | date | Previsão de entrega da medicação (novo 2026-07-23) |
 | `eclinica_laboratorio_data_moldagem` | date | Data do pedido da medicação |
 | `eclinica_laboratorio_data_entrega` | date | Data em que a medicação CHEGOU na unidade — é a data que dispara o aviso de retirada do flow |
@@ -441,6 +478,23 @@ Atributos de sistema no CONTATO (prefixo `eclinica_`, protegidos, usáveis como
 | `eclinica_ultima_cobranca_vencimento` | date | Vencimento da última cobrança |
 | `eclinica_ultima_cobranca_descricao` | text | Descrição da última cobrança |
 
+**Regras de atualização que enganam na leitura (2026-08-20/21):**
+
+- `eclinica_situacao` e `eclinica_cor` são **esparsas**: evento de agenda que vem SEM o campo
+  **apaga a chave** (vazio = "a recepção ainda não marcou", não "sem dado"). `agendamento_novo`
+  nunca traz situação — logo depois de marcar, a situação fica vazia de propósito.
+  `agendamento_atendido` e `agendamento_desmarcado` **atualizam** a situação (ATENDIDO, DESMARCADO);
+  antes de 21/08 a ficha ficava "NA CADEIRA" depois do atendimento (conserto de 21/08/2026 — entra
+  com o próximo deploy do app depois de 21/08/2026).
+- Códigos com mais de uma letra pro mesmo estado: `O`/`OK` = CONFIRMADO, `D`/`W` = DESMARCADO.
+  Código fora da legenda fica gravado como veio (nunca vazio, nunca palpite).
+- `agendamento_aguardando` (paciente chegou) grava a chegada por cima do agendamento, mas **não
+  agenda nem cancela lembrete** (chegada não é consulta nova) e **não apaga** cor/situação quando
+  vem sem elas.
+- `eclinica_ultima_chegada_*`, `eclinica_ultimo_pagamento*` e `eclinica_odontograma_*` guardam o
+  ÚLTIMO evento; paciente com 3 consultas tem sempre a última na ficha (não há histórico no contato —
+  use `lionchat_eclinica_reminder_history_list` e o log de eventos da tela).
+
 **Lembretes automáticos (Integrações > e-Clínica > Lembretes).** Cada linha tem um **tipo de
 evento** que decide de qual data a contagem parte: `agendamento` (data da consulta, padrão),
 `controle_laboratorio_novo` (previsão de entrega da medicação) e `cliente_inclusao_pagamento`
@@ -507,7 +561,8 @@ LeadForm (Formulário público de captação — feature flag lead_forms, por co
 ├── account_id (FK)
 ├── name / slug (8 chars, gerado na criação e imutável) / display_mode (cards|chat) / active
 ├── form_data (jsonb: o desenho do construtor) — published_data (a FOTO publicada, que a página usa)
-├── settings (jsonb: primary_color, theme, abandon_minutes, button_label) / published_at
+├── settings (jsonb: primary_color, theme, abandon_minutes, button_label, resume, chat_avatar,
+│   public_title — título que o LEAD vê, 2026-08-21) / published_at
 └── counts: views / responses / completed (contadores) + lead_form_responses (has_many)
 
 LeadFormResponse (um preenchimento do formulário)
@@ -520,10 +575,28 @@ LeadFormResponse (um preenchimento do formulário)
 CustomWebhookIntegration (Webhook Universal — entrada)
 ├── account_id (FK)
 ├── name / token (URL única) / active
-├── field_mapping (jsonb — suporta caminhos com índice de array: messages.0.content)
+├── field_mapping (jsonb — caminho do payload → destino: campo nativo, `contact_attr_<k>`,
+│   `conversation_attr_<k>` (2026-08-21 — entra com o próximo deploy do app depois de 21/08/2026),
+│   `cadastral_<k>`, `social_<k>`; aceita índice de array: messages.0.content)
 ├── event_automation_mapping (jsonb)
 └── flow_id (FK opcional → Flow; presente = webhook EMBUTIDO de flow, oculto da listagem standalone)
 
+Gateways de pagamento (GuruWebhook, HotmartWebhook, KiwifyWebhook, EduzzWebhook, TictoWebhook,
+MonetizzeWebhook, GreennWebhook, ContaAzulIntegration, OmieIntegration — tools
+`lionchat_ecommerce_webhooks_*`, `conta_azul_integrations_*`, `omie_integrations_*`)
+├── event_automation_mapping (jsonb) — uma entrada por evento do gateway:
+│   { "<evento>": { automation_id, flow_id, first_purchase_only,
+│                   conversation_attribute_keys: ["purchase_price", "product_name", ...] } }
+│   (Conta Azul/Omie usam `event_mapping`, por categoria). `conversation_attribute_keys`
+│   (2026-08-21 — entra com o próximo deploy do app depois de 21/08/2026) = quais campos da compra
+│   gravar TAMBÉM na conversa que a automação/fluxo abrir; chaves válidas = catálogo dos atributos
+│   de pagamento: product_name, offer_name, invoice_url, purchase_price, payment_method,
+│   purchase_email, pix_code, pix_qr_code_url, pix_expiration_date, ticket_hash_url, event_name,
+│   event_date, charged_times, subscription_cycle, subscription_status, customer_document,
+│   transaction_id, payment_installments, payment_source. Chave fora do catálogo é ignorada.
+└── Leia o mapeamento atual antes de gravar: o `update` SUBSTITUI o jsonb INTEIRO (não mescla) —
+    mande todos os eventos de volta, senão os outros somem.
+
 LiontrackJourneyStage (regras de fase da Jornada do Lead — feature flag liontrack)
 ├── account_id (FK)
 ├── stage (nome da fase, ex: Topo/Meio/Fundo/Compra)
@@ -548,6 +621,17 @@ ContactDocument (aba Documentos do contato, 2026-06-11)
 └── ações: preview, download, renomear, favoritar, excluir (conversas são só-leitura)
 ```
 
+**Histórico de preenchimentos por CONTATO (2026-08-21 — entra com o próximo deploy do app depois
+de 21/08/2026):** `GET /contacts/{id}/form_entries` (aba "Preenchimentos" da ficha; tools
+`lionchat_contacts_form_entries_list` / `_show`) junta, em ordem de data, o que a pessoa preencheu
+em nosso formulário, no formulário nativo do Meta, no Webhook Universal e no webhook de flow (origem
+`flow`, com o nome do fluxo) — cada item `{source, id, title, status, at, count, conversation}` e
+`/form_entries/{source}/{id}` abre o detalhe. Como cada preenchimento SOBRESCREVE os atributos do
+contato, a ficha só mostra o último — esta lista guarda todos. Origens de fora exibem SÓ os campos
+vinculados a atributos daqui e realmente gravados (nada do payload cru). Ao mesclar contatos, as
+origens vão pro contato vencedor. Os eventos do Meta Lead **não são mais expurgados após 90 dias**
+(decisão do dono, 21/08).
+
 ### Google Contatos (integração nativa)
 
 Salva contatos do LionChat no **Google Contatos** da conta Google conectada pelo admin (etiqueta "LionChat"), fazendo o celular/WhatsApp exibirem o nome do cliente. Conexão é **uma por conta**, feita **somente pela interface** (Configurações → Integrações → Google Contatos → "Conectar conta Google" — é OAuth no navegador, **não há tool MCP** para conectar). Comportamento: contato novo com telefone sobe automático (~1 min); botão "Enviar contatos existentes" manda a base antiga (vira "Ressincronizar contatos" depois — idempotente, nunca duplica); rename aqui propaga pro Google só em contatos criados pelo sistema; nunca apaga nem altera a agenda pessoal do cliente. Quando o usuário perguntar "dá pra salvar os contatos no celular/Google?", oriente esse caminho de tela.

package/dist/docs/resources/filtros-e-relatorios.md

@@ -36,6 +36,10 @@ E/OU é encadeado condição a condição (sem parênteses).
 Atributo personalizado: informe `custom_attribute_type` na condição — `'conversation_attribute'`
 (atributo da conversa) ou `'contact_attribute'`. Sem ele o escopo pode sair errado.
 
+- `chat_type` em `conversations_filter` funciona desde 19/08/2026 (antes respondia 500). `group` =
+  conversa de grupo de WhatsApp; `individual` cobre também canal, transmissão e status. Com
+  `not_equal_to`, conversa sem contato vinculado NÃO some do resultado.
+
 ### Data relativa — "Hoje", "Ontem", "últimos X dias" (novo 2026-08-01)
 
 Não calcule data no seu lado pra perguntar "quantas conversas entraram hoje". Existem operadores
@@ -245,7 +249,51 @@ payload=[
 **R6 — Cards parados (sem tarefa) com atributo do contato:**
 `kanban_items_filter funnel_id=37 task_filter=no_task contact_custom_attribute_filters="[{\"attribute_key\":\"ja_investe\",\"filter_operator\":\"equal_to\",\"values\":[\"ja_invisto\"]}]"`
 
+**R7 — Pergunta de relatório que NENHUMA ferramenta responde pronta** (relatório personalizado
+montado na hora, sem salvar nada). Ex.: *"quantos cards foram ganhos em cada etapa do funil 37 nos
+últimos 30 dias?"*
+
+```json
+custom_dashboards_preview_widget
+  widget_type=funnel_stages  chart_type=bar  funnel_id=37
+  date_basis=closed  status=won  time_range=last_30_days  timezone_offset=-3
+```
+Resposta: `{shape:"categories", categories:[{label:"Negociação", value:12}, ...]}` — **na ordem das
+etapas do funil**, não por valor. Trocar `date_basis` muda a pergunta: `created` = "entraram no
+funil", `moved` = "entraram na etapa", `closed` = "foram fechados".
+
+**R8 — Tabela de produtividade por operador, com etiqueta e taxa de conversão:**
+
+```json
+custom_dashboards_preview_widget
+  widget_type=agent_report  chart_type=table  dimension=agent
+  time_range=custom  from=2026-08-01  to=2026-08-15  timezone_offset=-3
+  columns=[
+    {"metric":"leads"},
+    {"metric":"atendidos"},
+    {"metric":"label_count","label_id":5,"as":"Agendados"},
+    {"metric":"conversao","numerator":[5],"denominator":"leads","as":"% agendamento"}
+  ]
+```
+> ⚠️ `numerator` é **lista de IDs de etiqueta** (`[5]`), nunca nome de métrica. Mandar
+> `["label_count"]` faz a coluna de conversão **sumir em silêncio**.
+> ⚠️ `time_range=custom` aceita no máximo **92 dias** e vale em qualquer tipo de bloco (desde
+> 19/08/2026). Pedir "esse ano" volta 422 com a explicação. Para relatório diário use
+> `today`/`yesterday` em vez de datas fixas, que envelhecem.
+> ⚠️ O `total` da tabela **não é a soma das linhas** — cada métrica tem contagem própria.
+
+**R9 — Salvar isso como relatório na tela do cliente:** teste com o R8, mostre o número, confirme
+com o usuário e só então:
+```json
+custom_dashboards_create  confirm=true
+  name="Produtividade da equipe"
+  widgets=[{"id":"prod-1", ...mesmo desenho do R8...}]
+```
+Para **alterar** depois: leia com `custom_dashboards_list`, mexa no array e devolva-o **completo** —
+`widgets` substitui a lista inteira, e preservar o `id` de cada bloco é o que mantém o vínculo.
+
 **Erros clássicos a evitar:** `includes` em labels (não existe — use equal_to); operador de
 número/data em texto; array-de-objetos em query (padrão B exige JSON-string); esquecer
 `custom_attribute_type` quando contato e conversa têm atributo de mesmo nome; esperar paginação
-no kanban_items_filter (não tem — estreite o filtro).
+no kanban_items_filter (não tem — estreite o filtro); montar um `custom_dashboards_update` em cima
+de uma listagem que veio cortada (apaga os blocos que não chegaram).