@lionchat/mcp-server 1.14.0 → 1.16.0

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

@@ -11,7 +11,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "conversation_created" }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "conversation_created", "config": {} }] } },
     { "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" }
     ] } },
@@ -55,7 +55,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "conversation_created" }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "conversation_created", "config": {} }] } },
     { "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?" }
     ] } },
@@ -99,7 +99,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "message_received", "keywords": ["proposta","orçamento"], "match_type": "contains" }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "message_received", "config": { "keywords": ["proposta","orçamento"], "match_type": "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_attr", "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?" }] } },
@@ -150,7 +150,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "conversation_resolved" }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "conversation_resolved", "config": {} }] } },
     { "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": "conversation_attr", "saveAttrKey": "csat_score" } },
@@ -182,7 +182,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "conversation_created" }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "conversation_created", "config": {} }] } },
     { "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", "valueType": "variable" }
     ] } },
@@ -210,7 +210,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "message_received" }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "message_received", "config": {} }] } },
     { "id": "n2", "type": "ai", "position": { "x": 370, "y": 300 }, "data": {
       "label": "Classifica", "aiMode": "intent",
       "aiPrompt": "Classifique a intenção da última mensagem do cliente",
@@ -242,7 +242,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "label_added", "label_names": ["follow-up"] }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "label_added", "config": { "label_names": ["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}}"] }
@@ -269,7 +269,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "message_received" }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "message_received", "config": {} }] } },
     { "id": "n2", "type": "condition", "position": { "x": 370, "y": 300 }, "data": { "label": "Pede humano?", "conditions": [
       { "id": "c1", "label": "Sim", "field": "{{last_response}}", "operator": "contains", "value": "humano", "valueType": "variable" }
     ] } },
@@ -299,7 +299,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "message_received", "keywords": ["agendar","reunião"], "match_type": "contains" }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "message_received", "config": { "keywords": ["agendar","reunião"], "match_type": "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": {
@@ -333,7 +333,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "label_added", "label_names": ["urgente"] }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "label_added", "config": { "label_names": ["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",
@@ -364,7 +364,7 @@
 {
   "nodes": [
     { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [
-      { "type": "webhook_received", "config": { "integration_id": 123 } }
+      { "key": "webhook_received", "config": { "integration_id": 123 } }
     ] } },
     { "id": "n2", "type": "action", "position": { "x": 370, "y": 300 }, "data": { "label": "Marca origem", "items": [
       { "key": "add_conversation_label", "config": { "labels": ["compra-confirmada"] } }
@@ -417,7 +417,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "message_received", "keywords": ["orçamento"], "match_type": "contains" }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "message_received", "config": { "keywords": ["orçamento"], "match_type": "contains" } }] } },
     { "id": "n2", "type": "action", "position": { "x": 370, "y": 300 }, "data": { "label": "Marca", "items": [
       { "key": "add_conversation_label", "config": { "labels": ["pediu-orcamento"] } },
       { "key": "add_label", "config": { "labels": ["interessado-em-comprar"] } }
@@ -440,7 +440,7 @@
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "conversation_created" }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "conversation_created", "config": {} }] } },
     { "id": "n2", "type": "send_message", "position": { "x": 370, "y": 300 }, "data": { "label": "Oferece", "messageItems": [
       { "id": "m1", "type": "text", "content": "Quer receber nossas novidades por e-mail?" }
     ] } },
@@ -520,7 +520,7 @@
 {
   "nodes": [
     { "id": "start", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [
-      { "type": "date_trigger", "config": {
+      { "key": "date_trigger", "config": {
         "attr_key": "_date_of_birth",
         "offset_direction": "on",
         "offset_days": 0,
@@ -561,7 +561,7 @@ funciona em conta com caixa **WhatsApp QR Code (`Channel::Waha`)** — a caixa v
 ```json
 {
   "nodes": [
-    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "card_won", "funnel_ids": ["1"] }] } },
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [{ "key": "card_won", "config": { "funnel_ids": ["1"] } }] } },
     { "id": "n2", "type": "update_group", "position": { "x": 370, "y": 300 }, "data": {
       "label": "Cria grupo de onboarding",
       "groupOperation": "create",
@@ -593,15 +593,25 @@ Comuns a (quase) todas:
 
 | Operação | Chaves específicas | Retorno (`{{grupo.*}}`) |
 |---|---|---|
-| `create` | `groupName` (obrig), `groupDescription`, `groupPicture` (url), `groupInitialAdmins`, `groupParticipants` | `id`, `name`, `participants_count` |
-| `add_participants` | `groupParticipants` (obrig — ex.: `["5511999999999@c.us"]` ou lista) | `added`, `not_added`, `added_count` |
+| `create` | `groupName` (obrig), `groupDescription`, `groupPicture` (url), `groupInitialAdmins`, `groupParticipants`, `groupAttributes`; opcional `groupInviteOnFailure` + `groupInviteMessage` (com `{{link}}`) | `id`, `name`, `participants_count`, `conversation_id`, `added`, `added_count`, `not_added`, `not_added_count`, `no_whatsapp`, `invited`, `invite_status` — saída `partial` quando alguém ficou de fora |
+| `add_participants` | `groupParticipants` (obrig — ex.: `["5511999999999@c.us"]` ou lista); opcional `groupInviteOnFailure` + `groupInviteMessage` | `added`, `not_added`, `added_count`, `not_added_count`, `no_whatsapp`, `invited`, `invite_status` |
 | `send_invite` | `groupInviteTo` (obrig — telefone de destino), `groupInviteMessage` (opc) | `invite_link` |
-| `settings` | pelo menos uma de `infoAdminOnly` / `messagesAdminOnly` / `membersCanAddNewMember` (booleans) | — |
+| `settings` | pelo menos uma de `infoAdminOnly` / `messagesAdminOnly` / `membersCanAddNewMember` (booleans) | `settings_updated` (lista do que aplicou), `settings_failed` (`[{setting, reason}]`), `settings_unsupported` |
+| `send_message` | `messageItems` (mesmo contrato do bloco de mensagem: text/delay/attachment/audio/url_media) + `groupTargetId` opcional — manda os balões NA CONVERSA DO GRUPO (vazio = grupo da conversa atual). É a 17ª operação (08/08) | — (única sem variável de resposta) |
+
+Os campos `added`/`not_added`/`no_whatsapp`/`invited`/`invite_status` do `create` e `groupInviteOnFailure` são
+de 21/08/2026 (entram com o próximo deploy do app depois de 21/08/2026).
 
 **ATENÇÃO na `settings` — semântica INVERTIDA de `membersCanAddNewMember`:** `true` = **TODOS** podem adicionar
 membros. Já `infoAdminOnly: true` e `messagesAdminOnly: true` = **SÓ admin** edita infos / manda mensagem.
 Confundir os dois LIBERA o grupo achando que está trancando.
 
+**Cada permissão vale por si (2026-08-20):** o bloco aplica uma a uma; o que aplicou aparece em
+`{{grupo.settings_updated}}` mesmo quando outra falhou, e a saída só é `success` quando algo mudou E
+nada falhou. `membersCanAddNewMember` ("quem pode adicionar") depende do servidor de WhatsApp QR
+Code ser 2026.7+ — no servidor atual ela volta em `settings_unsupported` (não é erro do cliente) e
+as outras duas seguem aplicadas. Não prometa essa permissão ao cliente sem conferir o resultado.
+
 **Gatilho novo `group_participant_joined` (entrou no grupo → manda boas-vindas):** em um flow de grupo
 (`conversation_mode: "group"`), o start pode ter o item `{ "key": "group_participant_joined", "config": {
 "group_match": "any", "group_name": "", "group_ids": [] } }`. Filtro OPCIONAL de quais grupos disparam:
@@ -618,8 +628,13 @@ grupo** (o grupo é a conversa do flow).
 - No fluxo de card ganho acima, o `send_message` vai para a conversa do CONTATO (o lead), não para o grupo
   criado. Para postar DENTRO do grupo, use um flow de grupo (`conversation_mode: "group"`) — normalmente com o
   gatilho `group_participant_joined`.
-- Em `add_participants`, quem tem privacidade de grupo ligada pode não entrar mesmo com resposta de sucesso do
-  WhatsApp: confira `{{grupo.not_added}}` / `{{grupo.not_added_count}}`.
+- Em `create` e `add_participants`, quem tem privacidade de grupo ligada pode não entrar mesmo com
+  resposta de sucesso do WhatsApp: o bloco relê o grupo e manda quem faltou em `{{grupo.not_added}}`
+  (saída `partial`). Se o cliente quiser, ligue `groupInviteOnFailure` com um texto em
+  `groupInviteMessage` — o convite vai no privado (máx. 5 por execução, 1 por telefone/dia, 50/dia
+  por caixa) e cria contato + conversa pra cada um.
+- Handles do bloco: `success`, `error` e `partial` (em `create`/`add_participants`/`remove_participants` — a
+  operação rodou mas nem todo mundo entrou/saiu). `partial` sem fio segue pelo fio `success`.
 
 ---
 

package/dist/docs/resources/formularios-publicos.md

@@ -2,7 +2,8 @@
 
 Tudo sobre os Formulários Públicos do LionChat (captação estilo Typeform/Typebot): link público,
 caixa de WhatsApp vinculada, desenho dos blocos, publicação, respostas, funil, simulador e
-integração com fluxos. Atualizado em 18/08/2026 (v4.10.226).
+integração com fluxos. Atualizado em 21/08/2026 (v4.10.228 + commits de 21/08 na elvislion: título
+público, aba Preenchimentos — entram com o próximo deploy do app depois de 21/08/2026).
 
 ## O que é
 
@@ -51,16 +52,21 @@ caixa de WhatsApp vinculada e (opcionalmente) dispara um fluxo do FlowBuilder no
 | `lionchat_lead_forms_responses_show` | `GET /lead_forms/:id/responses/:rid` | Detalhe de uma resposta, com o que a pessoa respondeu |
 | `lionchat_lead_forms_test_run` | `POST /lead_forms/:lead_form_id/test_runs` | Simulador: roda o RASCUNHO no motor real, sem deixar rastro. Qualquer agente da conta |
 | `lionchat_lead_forms_check_embed` | `POST /lead_forms/check_embed` | Confere se um site aceita ser exibido em iframe (bloco Página externa). Admin-only |
+| `lionchat_contacts_form_entries_list` | `GET /contacts/:contact_id/form_entries` | Tudo que UMA PESSOA preencheu, das 4 origens (nosso formulário, Meta, Webhook Universal, Fluxo). Qualquer agente |
+| `lionchat_contacts_form_entries_show` | `GET /contacts/:contact_id/form_entries/:source/:id` | Detalhe de um preenchimento a partir do contato. Qualquer agente |
 
-**Imagens não têm ferramenta MCP.** O upload de imagem de bloco (`POST /lead_forms/:id/media`,
-máximo 5 MB, só `image/*`) existe no painel. Pela API dá pra referenciar um `image` que já foi
-subido, nunca subir um novo.
+**Imagens não sobem pelo conector.** A rota `POST /lead_forms/:id/media` (admin, multipart `file`,
+só `image/*`, máximo 5 MB, devolve `{blob_id, url}`) existe, mas upload de arquivo não passa pelo MCP
+— chamada pelo conector ela volta 422 `invalid_file_type`. Suba a imagem no editor do painel e
+referencie o `blob_id` (o `show` traz `media_urls` com todos os ids do acervo: imagem de bloco,
+imagem de opção e a foto do chat). **Imagem subida e não referenciada em até 1 hora é apagada** na
+próxima varredura (todo `update`/`publish` roda a varredura).
 
 ## Campos do formulário
 
 | Campo | Tipo | Observação |
 |---|---|---|
-| `name` | string | **Obrigatório** |
+| `name` | string | **Obrigatório.** Nome INTERNO (lista do painel). O que o lead vê na aba do navegador e no link compartilhado é `settings.public_title`; vazio, cai no `name` |
 | `display_mode` | string | `cards` (padrão) ou `chat` |
 | `active` | boolean | Formulário inativo devolve 404 na página pública |
 | `inbox_id` | integer | Caixa de WhatsApp vinculada. Obrigatória para publicar. Ver regras abaixo |
@@ -94,6 +100,14 @@ ou `null` — a caixa resolvida), e `published_inbox_id` (a caixa que está NA F
 | `button_label` | string — rótulo do botão da página pública | — |
 | `resume` | booleano — continuar de onde parou entre visitas | `true` |
 | `chat_avatar` | id numérico de blob já subido (`media`) — foto redonda ao lado dos balões, só no formato `chat`. O público recebe `chat_avatar_url` resolvida (nunca o id) | — |
+| `public_title` | string, até 100 caracteres — título que o LEAD vê (aba do navegador, link compartilhado). Vazio = usa o `name`. O endpoint público devolve `display_title` (nunca o `name` cru) | — (21/08 — entra com o próximo deploy do app depois de 21/08/2026) |
+
+**No `update`, `settings` SUBSTITUI o objeto inteiro** (assim como `form_data`): não há merge. Mande
+todas as chaves que quer manter — um `settings: {theme: "dark"}` apaga cor, avatar, título público,
+`resume` e `abandon_minutes`. E apagar `chat_avatar` custa o arquivo: a varredura de imagens roda
+logo após o salvamento e purga o que não está mais referenciado em `form_data`, na foto publicada ou
+em `settings.chat_avatar` (só upload com menos de 1 hora escapa). O mesmo vale pra `image` de bloco
+ou de opção que sair do `form_data`.
 
 ## Ciclo de vida
 
@@ -208,8 +222,16 @@ renderiza e não dá erro.
 **`options`** (do `choice`): `[{ "id": "abc123", "label": "Sim", "image": "" }]`.
 
 **`branches`** (do `condition`): lista avaliada em ordem; nenhum ramo casando cai no handle `else`.
-Operadores: `equals`, `not_equals`, `contains`, `filled`, `not_filled`, `greater_than`,
-`less_than`. Fonte `api_request` exige `path` (caminho dentro da resposta).
+Cada ramo: `{ "id": "b1", "label": "Sim", "source_node_id": "<id da pergunta/escolha/consulta/IA>",
+"operator": "equals", "value": "...", "path": "" }`. `id` é estável (a aresta `cond_<id>` aponta
+pra ele); `label` é o rótulo do fio no desenho (vazio = número). Operadores: `equals`, `not_equals`,
+`contains`, `filled`, `not_filled`, `greater_than`, `less_than` (os dois últimos só numéricos;
+`filled`/`not_filled` ignoram `value`). Fonte Escolha compara pelo **id da opção**, não pelo texto;
+resposta múltipla: `equals` exige exatamente aquela opção, `contains` = inclui. Fonte `api_request`
+exige `path` (caminho dentro da resposta, ex.: `localidade`); fonte `ai` compara o texto/categoria
+direto. **Ramificar por variável** (`{{var.*}}`): o motor aceita `source_variable: "<nome>"` no
+ramo (tem precedência sobre `source_node_id`), mas o dialog de Condição do editor **não conhece a
+chave e a descarta ao salvar o bloco pela tela** — use só em formulário mantido pela API.
 
 **`items`** (do `action`) — o formato novo, uma LISTA de ações `[{key, config}]`:
 
@@ -357,6 +379,7 @@ mesmo que exista — é proteção, não defeito.
 | Respostas por chamada do simulador | 60 |
 | Altura da Página externa | 240..1200 px |
 | Conferência de embed | 5 s por salto, até 3 redirecionamentos |
+| Lista de preenchimentos do contato | 250 por origem (lead_form / meta_lead / webhook), sem paginação; `meta.truncated` avisa |
 
 ## Simulador (`lionchat_lead_forms_test_run`)
 
@@ -366,39 +389,90 @@ exige admin. O estado do teste vive em quem chama: cada chamada reproduz o teste
 da lista de respostas.
 
 - Body: `{answers: [{node_id, value}]}` — até 60 itens; vazio = começa do início. Item cujo
-  `node_id` não é o bloco atual PARA a reprodução ali (devolve o bloco onde parou).
+  `node_id` não é o bloco atual PARA a reprodução ali (devolve o bloco onde parou). `value: null`
+  avança bloco sem resposta (`start`, `message`, `embed`).
 - Resposta 200: `{block, log, answers, variables, form}` — `block` é o mesmo envelope da página
-  pública; `log` é o caminho percorrido (`[{node_id, type, label, answer, detail}]` — o `detail`
-  mostra variável criada, ações executadas, resultado de consulta/IA e o rumo das condições).
-- 422: `{error: "invalid_value", reason}` (uma resposta reprovada na validação) ou
-  `{error: "test_run_failed", reason}`.
+  pública; `log` é o caminho percorrido (`[{node_id, type, label, answer?, detail?}]` — `detail`
+  mostra variável criada, ações executadas e o rumo das condições; `answer`/`detail` só aparecem
+  quando existem); `form.name` é o nome interno.
+- 422: `{error: "invalid_value", reason}` (uma resposta reprovada — `reason` é o código:
+  `required`, `invalid_email`, `invalid_phone`, `invalid_cpf`, `invalid_option`, `value_too_long`…)
+  ou `{error: "test_run_failed", reason}`.
+
+**O que o simulador NÃO faz (e como isso aparece):**
+
+| Bloco | No simulador |
+|---|---|
+| Consulta externa (`api_request`) e IA (`ai`) | **Não executam** (o job de efeito é desligado no modo de teste). Ao chegar neles a resposta volta `block: {node_id, type: "wait"}` e a reprodução para ali — itens seguintes são ignorados e `detail` desses blocos fica vazio. Pra testar o que vem depois, use a página pública (link identificado/aba anônima). |
+| Agendamento (`booking`) | `value: ""` segue por `no_booking` (só se o bloco não for obrigatório). Pra simular "agendou", mande o id de um agendamento **já existente** da conta — o simulador pela API não cria reserva. (No painel, o simulador embute a página real: uma reserva feita ali é de verdade e fica no banco.) |
+| Envio de arquivo (`file_upload`) obrigatório | Não tem como passar (o valor precisa ser um arquivo anexado à resposta de teste, que não existe): 422 `invalid_value`. Só com `required: false` e `value: ""`. |
+| Envio de WhatsApp, etiqueta, pixel, marco | Aparecem no `log` como reservados (`detail` lista as ações), mas nada é enviado/gravado. |
 
 ## Respostas e funil
 
-**`lionchat_lead_forms_stats`** (`days` opcional) devolve views/starts/completed/abandoned/
-completion_rate + `funnel` por bloco + `milestones`. O funil lista os blocos que a pessoa vê
-(`start`, `question`, `choice`, `message`, `booking`, `embed`, `end`), na ordem do desenho
-**publicado**.
+**`lionchat_lead_forms_stats`** (`days` opcional, default 30, máximo 90) devolve
+`views` (contador de VIDA INTEIRA do formulário — não obedece `days`), `starts`/`completed`/
+`abandoned` da janela, `completion_rate` (% inteiro = completed/starts), `funnel` por bloco e
+`milestones`. O funil lista os blocos que a pessoa vê (`start`, `question`, `choice`, `message`,
+`booking`, `embed`, `end`), na ordem do desenho **publicado**; acima de 50.000 respostas na janela
+sai parcial. **`milestones` hoje só enxerga bloco de Ações no formato antigo (`action_type:
+"milestone"`)** — marco configurado em `items` (formato atual do editor) não aparece aqui; aparece
+em `responses_show.milestones`.
 
 **`lionchat_lead_forms_responses_list`** aceita `status` (`in_progress`, `completed`,
-`abandoned`), `days` e `page`. A lista nunca traz as respostas em si — só `{id, status, contact,
-current_node_label, answered_count, created_at, completed_at}`. **`contact` pode vir
-`{id: null, name, phone, pending: true}`** — é quem ainda está preenchendo (o contato só nasce nos
-três momentos); nome e telefone saem do que a pessoa já digitou.
+`abandoned`), `days` e `page` (até 10.000). A lista nunca traz as respostas em si — só `{id, status,
+contact, current_node_label, answered_count, created_at, completed_at}` e `meta: {current_page,
+per_page: 25, total_count}`. **`contact` pode vir `{id: null, name, phone, pending: true}`** — é
+quem ainda está preenchendo (o contato só nasce nos três momentos); nome e telefone saem do que a
+pessoa já digitou. `answered_count` conta todas as chaves de `answers`, inclusive as sintéticas.
 
 **`lionchat_lead_forms_responses_show`** traz o conteúdo:
 
-- `answers`: `[{label, value_label, at, download_url?}]`. **Atenção:** o bloco de Ações grava
-  entradas SINTÉTICAS com chave `"<node_id>::<n>"` — nem toda chave de `answers` é id de bloco.
+- `status`, `contact` (mesmo shape da lista), `current_node_label`, `started_at`, `completed_at`,
+  `abandoned_at`, `created_at`.
+- `answers`: `[{label, value_label, at, download_url?}]`, ordenado por `at`. **Atenção:**
+  (1) o bloco de Ações grava entradas SINTÉTICAS com chave `"<node_id>::<n>"` e o fim degradado
+  (beco sem saída/teto de passos) grava `"_walk_ended"` — nem toda chave é id de bloco;
+  (2) no bloco de **Agendamento `value_label` é o id da reserva, não a data** (a aba Preenchimentos
+  do contato mostra a data); (3) envio de WhatsApp pulado por falta de telefone aparece como
+  entrada vazia do bloco de mensagem.
 - `conversation`: `{id, display_id}` ou `null` — a conversa aberta na caixa vinculada.
-- `milestones`: os marcos atingidos.
-- `effects`: resultado de consulta/IA — `{node_id, label, state, error, status, url_short, at}`.
-  `url_short` é esquema + host + caminho, sem a query; corpo, cabeçalhos e prompt nunca saem.
+- `milestones`: os marcos atingidos (`[{node_id, name, at}]`).
+- `effects`: resultado de consulta/IA — `{node_id, label, state: pending|done|error, error, status,
+  url_short, at}`. `url_short` é esquema + host + caminho, sem a query; corpo, cabeçalhos e prompt
+  nunca saem.
 - `utm_params`: de onde o lead veio.
 
-Motivos de erro em `effects`: `http_<código>`, `timeout`, `ssrf_blocked`, `invalid_url`,
-`result_too_large`, `stale`, `busy`, `budget_exceeded`, `no_ai_key`, `ai_error`,
-`unresolved_variable`.
+Motivos de erro em `effects.error`: `invalid_method`, `invalid_url`, `http_<código>` (`http_0` =
+falha de transporte sem código), `timeout`, `ssrf_blocked`, `result_too_large`, `stale`,
+`effect_failed` (exceção no job), `effect_runs_exceeded` (laço: 20 execuções), `budget_exceeded`,
+`no_ai_key`, `ai_error`. (Os motivos `busy` e `unresolved_variable`, citados antes, não existem no
+código.)
+
+## Preenchimentos do contato (`lionchat_contacts_form_entries_list` / `_show`) — 21/08 (entra com o próximo deploy do app depois de 21/08/2026)
+
+A aba "Preenchimentos" da ficha junta, numa lista só ordenada por data, tudo que a pessoa preencheu
+ou que entrou por ela, de QUATRO origens: nosso formulário público (`source: lead_form`),
+formulário de anúncio do Meta (`meta_lead`), Webhook Universal (`custom_webhook`) e o webhook que o
+FlowBuilder cria pro gatilho de um fluxo (`flow`, com o nome do fluxo). É a única rota que responde
+"o que esta PESSOA preencheu" — as outras são por formulário/integração, e duas delas são só de
+administrador; esta é liberada a qualquer agente.
+
+- **Lista**: `{payload: [{source, id, title, status, at, count, conversation}], meta: {total,
+  truncated}}`. `id` é o id do registro NA ORIGEM — só identifica junto com `source`. `status` é
+  `in_progress|completed|abandoned` no nosso formulário e `received` nas demais. `count` = respostas
+  (nosso) ou campos vinculados e gravados (de fora). `conversation` só existe em `lead_form`. Sem
+  paginação de propósito; teto de 250 por origem — estourou, `truncated: true`. Só entram eventos
+  do Meta/webhook com status processado.
+- **Detalhe** (`source` + `id` da mesma linha): nosso formulário devolve `answers` (`[{label,
+  value, at, download_url?, images?}]` — pergunta/resposta legíveis, na ordem; Escolha com opção
+  ilustrada traz `images`, e opção sem texto vem com `value` vazio; Agendamento mostra a DATA),
+  `written` (`[{scope: contact|conversation, label, value}]` — o que AQUELE preenchimento gravou) e
+  `utm`. Meta/webhook/fluxo devolvem SÓ `fields: [{label, value}]` — os campos que foram vinculados a
+  atributos daqui e realmente gravados, com o rótulo daqui; nunca o payload cru. `fields: []` = o
+  evento não gravou nada. Origem fora da lista ou registro de outro contato = 404.
+- A lista **não traz o `lead_form_id`** da resposta: pra chegar em `lionchat_lead_forms_responses_show`
+  a partir dela, ache o formulário pelo `title` em `lionchat_lead_forms_list`.
 
 ## Conferência de iframe (`lionchat_lead_forms_check_embed`)
 
@@ -497,3 +571,11 @@ agendar (com `required: true` essa saída deixa de existir). O tipo de evento ve
 - **Não há tool de rewind**: o "Voltar e corrigir" é da página pública (o lead corrige a própria
   resposta; telefone corrigido reencaminha a mensagem pro número certo). Pela API de dashboard,
   respostas são somente leitura.
+- **`settings` no `update` também SUBSTITUI o objeto inteiro** — e sem `chat_avatar` o arquivo da
+  foto é apagado pela varredura. Leia com `show`, altere e mande completo.
+- **Imagem que some do `form_data` é apagada de verdade** logo após o salvamento (só sobrevive se
+  ainda estiver na foto publicada ou tiver menos de 1 hora).
+- **O simulador não roda consulta nem IA**: parou em `block.type: "wait"` = chegou num desses
+  blocos. Teste o trecho seguinte pela página pública.
+- **`stats.views` é de vida inteira** (ignora `days`); `stats.milestones` não vê marco em `items`.
+- **`name` é interno; `settings.public_title` é o que o lead vê** (vazio = cai no `name`).

package/dist/docs/resources/glossary.md

@@ -74,6 +74,15 @@ Glossário completo de termos, status codes, enums e conceitos da plataforma. Us
   de WhatsApp — oficial e QR Code). A bolha mostra o selo "Encaminhada"
 - `content_attributes.frequently_forwarded`: `true` = encaminhada MUITAS vezes (o "encaminhada com
   frequência" do WhatsApp). Útil pra responder "essa mensagem foi encaminhada?" sem chutar
+- `content_attributes.edited`: `true` = o CLIENTE editou a mensagem no WhatsApp (`edited_at` traz
+  quando). O `content` já é o texto novo; a versão anterior não fica guardada. Vale nos dois canais
+  de WhatsApp (QR Code desde 18/07/2026; oficial desde 21/08/2026 — entra com o próximo deploy do
+  app depois de 21/08/2026; antes a edição virava um balão VAZIO novo, contado como mensagem nova).
+- `content_attributes.deleted`: `true` = mensagem APAGADA ("apagar para todos"), pelo cliente ou
+  pela empresa no celular (convivência). O `content` vira `"⛔ Esta mensagem foi excluída"` seguido
+  do texto original (a equipe continua vendo o que foi dito); os anexos são removidos. Ao resumir
+  uma conversa, trate como apagada — não cite o texto como se ainda estivesse de pé. (No canal
+  oficial, desde 21/08/2026 — entra com o próximo deploy do app depois de 21/08/2026.)
 
 ## Attachment (Anexo)
 
@@ -296,6 +305,18 @@ comportamento intencional.
 - `role`: `agent` (atendente) ou `administrator` (admin/dono)
 - `availability`: `online`, `busy`, `offline`
 - `permissions`: array de strings com permissões granulares
+- `replacing`: `true` em `lionchat_agents_list` por até 30 min enquanto uma substituição
+  (`lionchat_agents_replace`) transfere a carteira desse agente pro novo — ele está SAINDO; não
+  atribua nada a ele
+
+### Agente de SUPORTE (SupportAccessGrant) — não é agente da conta
+
+Quem entra na conta por **acesso de suporte** (operador da plataforma) aparece como administrador,
+mas **não é membro da equipe**: `lionchat_agents_list` não o lista (escopo `regular_users`), ele
+não ocupa vaga do plano, não pode ser substituído (`agents_replace` recusa) e, desde 17/08/2026,
+a IA também o ignora — não atribui conversa a ele, não agenda mensagem no nome dele, não o menciona
+em alerta nem o conta como "disponível". Exceção deliberada: se alguém o atribuir à mão como
+responsável, ele segue valendo como responsável.
 
 ## AutomationRule (Regra de automação)
 
@@ -309,7 +330,11 @@ comportamento intencional.
 - `booking_event_type_id`: FK pro tipo de evento (ex: "Demo 30min")
 - `attendee_email`, `attendee_name`, `attendee_phone`
 - `start_time`, `end_time`: ISO 8601
-- `status`: `scheduled`, `cancelled`, `completed`
+- `status`: `confirmed`, `cancelled`, `completed` — mas **só muda quando o cancelamento/conclusão
+  vem pelo link do paciente ou pela IA**. Quem conclui/cancela pela Agenda mexe na TAREFA
+  (`account_tasks.status`: `pending`/`completed`/`cancelled`/`snoozed`), e o booking fica
+  `confirmed`. Pra saber se um agendamento aconteceu, leia a tarefa (`lionchat_tasks_show`), não o
+  booking.
 
 **A IA agenda EXCLUSIVAMENTE por agenda de Booking (15/08/2026).** Não existe mais agendamento
 avulso/direto pela IA — ela consulta as agendas liberadas, respeita os dias em que a agenda não

package/dist/docs/resources/kanban-deep-dive.md

@@ -48,6 +48,17 @@ Stages NÃO são tabela separada. São armazenadas como jsonb dentro do Funnel:
 }
 ```
 
+**Etapa que não existe no funil (desde 19/08/2026):**
+- `kanban_items_create`/`_update`/`_move` com `funnel_stage` que o funil não tem **não falha e não
+  some**: o card é REDIRECIONADO — pro destino gravado quando a etapa foi apagada, senão pra etapa
+  da mesma posição, senão pra primeira. **Confira o `funnel_stage` da resposta**: pode ser diferente
+  do que você mandou. Leia `funnels_show` antes e use o slug exato.
+- `funnels_update` que tira do `stages` uma etapa com card responde **422 `STAGE_HAS_ITEMS`** com
+  `stages: {"<slug>": <quantos cards>}`. Primeiro mova os cards com `lionchat_funnels_create_2`
+  (`POST /funnels/{id}/migrate_stage`, `from_stage`, `to_stage` ou `to_funnel_id`) e só então
+  reenvie o funil sem a etapa. Não existe parâmetro de destino no `update` de propósito.
+- Funil apagado continua sendo erro (o card não é criado).
+
 ### KanbanConfig (Configuração Global do Kanban) — CRÍTICO
 
 **Tabela separada do Funnel.** 1:1 com a conta. Guarda configurações que valem pra TODOS os funis. Tem 5 campos jsonb importantes:
@@ -245,6 +256,11 @@ Log automático de eventos do card:
 
 Tipos comuns: `created`, `stage_changed`, `agent_assigned`, `agent_removed`, `note_added`, `value_changed`, `priority_changed`, `archived`.
 
+Quem fez: `by_user_id`/`user` traz a pessoa; ação de automação ou flow vem com o nome da regra/fluxo;
+ação da IA (desde 21/08/2026 — entra com o próximo deploy do app depois de 21/08/2026) vem como
+`"IA: <nome do assistente>"` com `id` nulo — antes saía sem autor. Ao explicar um histórico de card,
+use esse campo pra dizer se foi gente, automação ou IA.
+
 ## Checklist (tarefas dentro do card)
 
 Array plano de itens. Cada item pode (opcionalmente) pertencer a um grupo via `group_id` +
@@ -580,7 +596,9 @@ Cada card pode receber atributos custom de 3 origens diferentes. **A escolha do
 ## Diagnóstico: "Card sumiu do funil"
 
 1. Está arquivado? `archived = true` em algum nível?
-2. Etapa atual existe ainda? (etapa removida do funil deixa card "órfão")
+2. Etapa atual existe ainda? Desde 19/08/2026 card em etapa inexistente é redirecionado na
+   gravação (e os 621 antigos foram movidos pra primeira etapa) — se ainda sumiu, filtre por
+   `funnel_stage` com o slug que aparece em `kanban_items_show` e compare com `funnels_show`.
 3. `position` está faltando? (cards sem position vão pro fim)
 4. Está em outro funil? (mover entre funis muda `funnel_id`)