@lionchat/mcp-server 1.15.0 → 1.17.0

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`)
 

package/dist/docs/resources/reports-guide.md

@@ -153,6 +153,7 @@ conversa antiga que NÃO aparece no relatório de hoje (régua antiga por criaç
 | "retrospectiva do ano" | `lionchat_reports_list_15` |
 | "satisfação", "CSAT", "nota dos clientes" | `lionchat_csat_metrics` |
 | "SLA", "cumprimento de prazo" (se a conta tiver Enterprise) | `lionchat_sla_metrics` |
+| "quantos agendamentos", "taxa de comparecimento", "agendamentos por tipo/atendente" | `lionchat_booking_reports` (ver "Agendamentos" no fim deste guia) |
 
 ---
 
@@ -330,6 +331,11 @@ Retorna:
 
 **Filtros aceitos (expostos na tool desde 2026-07-24):** `inbox_id`, `team_id`, `sla_policy_id`, `label_list[]`, `assigned_agent_id`, `since`/`until` (unix segundos).
 
+Latência de detecção: o prazo é conferido a cada 5 min, e desde 21/08/2026 (entra com o próximo
+deploy do app depois de 21/08/2026) as conferências saem espalhadas em até 2 min dentro do ciclo —
+um estouro pode aparecer em `sla_list`/`sla_metrics` até ~7 min depois do horário-limite. Não é
+defeito; não conclua "o SLA não está rodando" por isso.
+
 ## Padrões de interpretação
 
 ### Comparando períodos
@@ -555,7 +561,7 @@ nenhum `reports_*` responde; aqui é `funnel_stages` + `date_basis: closed` + `s
 
 Não é consulta livre: escolha um `widget_type` e preencha **só os campos daquele tipo**.
 
-### Os 7 tipos de bloco
+### Os 9 tipos de bloco
 
 | Tipo | Campos | Recurso exigido |
 |---|---|---|
@@ -563,13 +569,26 @@ Não é consulta livre: escolha um `widget_type` e preencha **só os campos daqu
 | `entity_ranking` | `dimension` (agent/inbox/team/label) · `metric` (conversations, resolutions, avg_first_response_time, avg_resolution_time) · `time_range` | — |
 | `csat_summary` | `time_range` | — |
 | `sla_summary` | `time_range` | `sla` (Enterprise) |
-| `funnel_stages` | `funnel_id` · `date_basis` (created/moved/closed/any) · `status` (all/open/won/lost) · `time_range` | `kanban_board` |
+| `funnel_stages` | `funnel_id` · `date_basis` (created/moved/closed/any) · `status` (all/open/won/lost) · `measure` (count padrão / value = soma do valor dos cards) · `time_range` | `kanban_board` |
+| `stage_entries` | `funnel_id` · `measure` (count/value) · `time_range` — quantos cards DISTINTOS ENTRARAM em cada etapa no período (histórico desde 12/07/2026) | `kanban_board` |
+| `calls_report` | `dimension` (agent/inbox) · `scope_type` (só `inbox`, opcional — recorte por caixa, desde 27/08/2026) + `scope_id` · `time_range` — ligações / atendidas / não atendidas / não concluídas / tempo total / tempo médio | — |
 | `lead_origin` | `time_range` | `liontrack` |
 | `agent_report` | `dimension` (agent/team/inbox) · `scope_type`+`scope_id` · `columns[]` · `time_range` | — |
 
-**`time_range`:** `last_7_days`, `last_30_days`, `this_month`, `last_month` — e `custom` **só em
-`conversations_timeseries` e `agent_report`**, exigindo `from`/`to`. **A janela não pode passar de 92
-dias**, e esse teto é da janela, não de um tipo: pedir "esse ano" é recusado com a explicação.
+`stage_entries`, `calls_report`, `measure`, `today`/`yesterday` e os metadados `title`/`width`/`height`
+são commits de 21/08/2026 (entram com o próximo deploy do app depois de 21/08/2026); `custom` em
+todos os tipos está no ar desde 19/08/2026.
+
+**`time_range`:** `today`, `yesterday` (desde 21/08 — o menor período era 7 dias), `last_7_days`,
+`last_30_days`, `this_month`, `last_month` e `custom` (com `from`/`to`, **em qualquer tipo** desde
+19/08/2026). **A janela `custom` não pode passar de 92 dias** — o teto é da janela, não do tipo;
+"esse ano" é recusado com a explicação. `today`/`yesterday` resolvem no fuso do `timezone_offset`
+enviado — mande o da conta.
+
+**Metadados do bloco (irmãos de `widget_type`, fora dos params):** `title` (nome que a pessoa dá ao
+bloco, até 80 caracteres; vazio = o painel mostra o rótulo do tipo), `width` (1 a 4 colunas; padrão
+2) e `height` (`normal` | `tall`). Preencha `title` em todo bloco que você criar — quatro blocos de
+funil sem nome chegam indistinguíveis pra quem lê depois.
 
 **Colunas do `agent_report`:** `leads`, `atendidos`, `resolvidas`, `abertas`, `pendentes`, `adiadas`,
 `label_count` (exige `label_id`) e `conversao` (exige `denominator` e `numerator`, que é **lista de
@@ -586,13 +605,19 @@ IDs de etiqueta**, nunca nome de métrica).
 
 ### Armadilhas que fazem o bloco sair errado
 
-1. **`scope_type`/`scope_id` têm sentido OPOSTO por tipo.** No `conversations_timeseries` = "o
-   gráfico é só daquela entidade". No `agent_report` = "mostre só as linhas de quem é dessa
-   equipe/caixa". Confundir troca a conta inteira.
+1. **`scope_type`/`scope_id` têm sentido DIFERENTE por tipo — e, no `agent_report`, por VALOR
+   (desde 27/08/2026).** No `conversations_timeseries` = "o gráfico é só daquela entidade". No
+   `agent_report`: `team`/`agent` = "mostre só as linhas de quem é dessa equipe/agente" (contando o
+   trabalho da pessoa na conta INTEIRA); `inbox` = recorte de CAIXA (membros da caixa, contando SÓ
+   o que fizeram naquela caixa — é o desenho de "relatório por médico/unidade"). `inbox` +
+   `dimension: team` é RECUSADO com motivo. No `calls_report`, `scope_type: inbox` conta só as
+   ligações daquela caixa — **ligação sem caixa fica de fora** (VTCall ~90% e Zenvia 100% das
+   ligações não têm caixa; LionCalls e Wavoip têm em 100%). Confundir troca a conta inteira.
 2. **Campo fora da lista é descartado em silêncio.** Se um valor "não fez efeito", provavelmente o
    nome do campo está errado.
-3. **Sempre envie `timezone_offset` em HORAS** (Brasília = `-3`). Sem ele o cálculo é em UTC e o
-   número não bate com o que o cliente vê na tela.
+3. **Sempre envie `timezone_offset` em HORAS, derivado do fuso DA CONTA** (`account_show.timezone`;
+   Brasília = `-3`, Cuiabá/Campo Grande/Manaus = `-4`). Sem ele o cálculo é em UTC e o número não
+   bate com o que o cliente vê na tela.
 4. **`update` substitui a lista de blocos inteira.** Leia com `list`, altere o array, devolva
    completo — e preserve o `id` de cada bloco que já existia.
 5. **`list` não pagina.** Se a resposta vier com aviso de corte, **não** use aquela lista para montar
@@ -669,6 +694,22 @@ Colunas: Ligações · Atendidas · Não atendidas · **Não concluídas** · Te
   Não a esconda ao resumir por pessoa.
 - A tabela lista só quem teve ligação no período — atendente ausente da tabela fez zero.
 
+### Agendamentos (`lionchat_booking_reports`) — 2026-08-19
+
+`GET /api/v2/accounts/{id}/booking_reports` — a aba Relatórios > Agendamentos. Unidade = o
+AGENDAMENTO (Booking). Params: `since`/`until` (datas; padrão 30 dias pra trás E 30 pra frente,
+porque agenda tem futuro), `event_type_id`, `user_id` (responsável da tarefa), `status`
+(`pending` | `completed` | `cancelled` | `snoozed`), `group_by` (`day` | `week` | `month`).
+Resposta: `totals` (`total`, `pending`, `completed`, `cancelled`, `snoozed`, `attendance_rate`),
+`timeline`, `by_event_type`, `by_agent`, `by_origin`.
+
+- **`attendance_rate` = concluídos / (concluídos + cancelados)**, em %. Pendentes ficam FORA do
+  denominador (ainda não aconteceram). Não recalcule com o total.
+- A SITUAÇÃO vem da tarefa da Agenda (`account_tasks.status`), não de `bookings.status` — quem
+  conclui/cancela pela Agenda deixa o booking parado em "confirmado". Ler `bookings_*` direto pra
+  contar "concluídos" dá zero.
+- `snoozed` (adiado) aparece separado de `pending` de propósito.
+
 ### Faturamento (`measure`)
 
 `measure: 'value'` faz `funnel_stages`/`stage_entries` somarem o VALOR dos cards em vez de contar.
@@ -676,3 +717,60 @@ Combinado com `status: 'won'` + `date_basis: 'closed'`, dá o faturamento ganho
 
 **Cuidado ao escrever**: se os cards do cliente têm valor padrão (todos com o mesmo número), a soma
 não é faturamento — é o padrão multiplicado. Se todos os valores forem idênticos, desconfie e diga.
+
+## Avisos — o resumo diário nativo no WhatsApp (2026-08-27)
+
+O caso da seção anterior ("me traz o relatório todo dia") virou **funcionalidade nativa**: a aba
+**Relatórios > Avisos** manda, todo dia no horário escolhido, o resumo em texto de um relatório
+personalizado num grupo/conversa de **WhatsApp QR**, com o texto escrito pela IA da conta. Ferramentas
+`lionchat_report_alerts_*` (criar, editar, listar, excluir, enviar agora, histórico, prévia). Só
+administrador; teto de 10 por conta.
+
+### O fluxo seguro (aprendido em produção, 27/08)
+
+1. **Crie DESLIGADO** (`enabled: false`) — aviso criado ligado DENTRO da janela do dia
+   (`send_hour` até +3h, fuso da conta) dispara no próximo tick de hora, e o grupo do cliente
+   recebe sem ninguém ter validado.
+2. **Rode a prévia** (`report_alerts_preview` → token → `report_alerts_preview_status`): mesmo
+   motor do envio, sem mandar nada. Mostre o texto pra pessoa aprovar.
+3. **Só então ligue** (`report_alerts_update` com `enabled: true`).
+
+### Regras do texto (a IA do Aviso NÃO é a IA do chat)
+
+- A conferência de números **reprova qualquer número que não exista no relatório** — a IA nunca
+  calcula, soma nem inventa percentual. Reprovou = sai o texto padrão do sistema (fiel, bloco a
+  bloco). **Percentual confiável = bloco `stage_conversion` no relatório** (o motor calcula).
+- Prompt que pede pra **renomear/reorganizar seções já fez a IA trocar rótulos de números** (caso
+  real: "Novos leads: 9" com o número do bloco de atendentes). O prompt que funciona: *"mantenha os
+  títulos e TODOS os números exatamente como estão, não renomeie seções, não calcule nada, inclua
+  TODOS os blocos"*.
+- Teto do texto: 60.000 caracteres (o do WhatsApp) — relatório inteiro cabe.
+- A mensagem entra na conversa como **mensagem de sistema**: automações e fluxos ativos naquela
+  conversa reagem a ela; não conta como resposta de atendente, não mexe em SLA nem apaga o
+  "cliente aguardando".
+
+### Diagnóstico ("o grupo não recebeu")
+
+`report_alerts_deliveries` é o histórico (90 dias, texto congelado de cada envio):
+`sent` = saiu, aguardando recibo · `confirmed` = **entregue com recibo do canal** (o selo verde só
+existe com evidência) · `send_failed` = recusado (motivo em `error_message`; caixa desconectada é o
+clássico) · `skipped_late` = não saiu no horário (janela de 3h estourada; tenta amanhã) · `error` =
+falhou antes do envio. `test_mode: true` = disparo manual. Na lista, `next_send_on` diz o próximo
+envio previsto e `last_delivery_status`/`last_error` resumem o último.
+
+### Bloco `stage_conversion` — percentual entre etapas (entra com o próximo deploy pós-27/08)
+
+`widget_type: 'stage_conversion'`: conversão calculada PELO MOTOR — cards **distintos** que entraram
+nas etapas de `numerator_stage_ids` ÷ os que entraram nas de `denominator_stage_ids`, na janela
+(mesma fonte histórica do `stage_entries`). Ex. real: Consulta Agendada ÷ (Novos Leads + Agendamento
+Pendente). Card que passou por duas etapas do denominador conta UMA vez (somar deflaria a taxa).
+`chart_type: 'number'`; shape scalar (value = %, total = base; total 0 = "sem dados"). Os ids de
+etapa são as CHAVES do hash `stages` do `lionchat_funnels_show`. Janela curta pode passar de 100%
+(agendou hoje um lead que entrou ontem) — é verdade do dado, explique em vez de esconder.
+
+### Recorte por caixa nos blocos de tabela (2026-08-26, já no ar)
+
+Em `agent_report` e `calls_report`, `scope_type: 'inbox'` + `scope_id` recorta **de verdade** pela
+caixa: membros da caixa contando SÓ o que fizeram nela (era o defeito dos relatórios por médico
+saírem iguais). `'agent'`/`'team'` seguem sendo recorte de PESSOAS (trabalho na conta inteira);
+`'inbox'` + `dimension: 'team'` é recusado. E `lead_origin` passou a respeitar `time_range`.

package/dist/docs/resources/troubleshooting.md

@@ -173,7 +173,9 @@ Feature flag específica (ex: `feature_kanban`, `feature_captain`) está OFF.
 - `"private must be boolean"` — true/false, não string
 
 ### KanbanItem
-- `"funnel_stage does not exist in funnel"` — etapa inválida pro funil
+- `"STAGE_HAS_ITEMS"` (no `funnels_update`) — você tentou remover uma etapa que ainda tem card;
+  `stages` na resposta diz quantos. Mova com `migrate_stage` antes. (Card criado em etapa
+  inexistente NÃO dá erro: é redirecionado — confira o `funnel_stage` devolvido.)
 - `"conversation_display_id must exist"` — conversa não existe ou foi deletada
 - `"position must be a positive integer"` — não pode ser negativo
 
@@ -418,6 +420,18 @@ pelo painel de suporte — só volta no botão Retomar), `cancelled` (encerrada
 Enquanto uma importação está viva, o repescador de mensagens da sessão fica fora do caminho, de
 propósito. Pausar, retomar e cancelar são ações do painel de suporte — não existem no MCP.
 
+**A mídia vem DEPOIS do texto (desde 19-20/08/2026).** O import grava as conversas só com o texto
+(779 conversas em ~3 min num caso real) e busca os arquivos em segundo plano, numa fila por caixa
+com poucas vagas na instalação inteira — pode levar horas (o dono aceitou "até 24 h, contanto que
+não atrapalhe nada"). Enquanto isso a mensagem carrega `content_attributes.media_failed` com
+`retryable: true` (bolha âmbar "mídia chegando"); quando o arquivo chega, o selo some e o anexo
+aparece; se o WhatsApp já apagou o arquivo (tudo com mais de ~2 semanas), o selo vira
+`retryable: false` (vermelho, definitivo — não há repesca). `lionchat_inboxes_waha_import_status`
+responde "ainda está chegando?": `media_pending` (arquivos na fila desta caixa; 0 = tudo pedido),
+`media_swept_at`/`media_swept_count` (varredura final que recolocou órfãos na fila). `status:
+completed` com `media_pending > 0` é normal — texto pronto, fotos a caminho. Conversa de histórico
+NÃO é repescada pelo vigia de mensagens, de propósito.
+
 ### "Editei o evento no Google Calendar e não sincronizou"
 Auto-cura desde 2026-06-09: o vigia horário re-arma o "watch" morto de conexões saudáveis
 sozinho (sem reconectar a conta). Se persistir >1h, aí sim investigar a conexão
@@ -498,6 +512,15 @@ recusado; brasileiro com 55 e 12-13 dígitos é aceito mesmo no formato antigo s
 sem erro de telefone); no import do KANBAN, telefone inválido cria o card SEM contato e SEM
 conversa, em silêncio — comportamento diferente do import de contatos.
 
+**Complementos de 19/08:** telefone PREENCHIDO e inválido **recusa a linha inteira** — o contato não
+nasce (antes ele nascia mudo, sem telefone). Coluna de telefone **vazia** continua criando o contato
+(lista de nome + e-mail é uso legítimo). **Linha totalmente vazia não é erro**: é pulada e contada em
+`blank_rows` no resultado — planilha de 300 linhas com 2 preenchidas deixa de gerar 298 "Nome é
+obrigatório". Telefone em notação científica do Excel (`9,88888E+12`) recebe mensagem própria
+("formate a coluna como texto"), não "confira o DDI". No `contacts_import_validate`, o número da
+linha no relatório é a posição REAL no arquivo (linhas vazias contam na numeração, não no total
+conferido).
+
 ## "A caixa oficial parou de disparar / de receber" — avisos automáticos da Meta (18/08)
 
 Duas famílias de chaves novas em `additional_attributes` da caixa `Channel::Whatsapp`
@@ -512,6 +535,15 @@ Duas famílias de chaves novas em `additional_attributes` da caixa `Channel::Wha
   e `reauthorization_required` vira `true` SOZINHO. Com `reauthorization_required: true` a caixa
   fica MUDA (descarta o que chega) até reconectar. A ausência dessas chaves NÃO prova que a caixa
   está conectada (caixa antiga só ganha o aviso após reinscrição).
+- **Registro do número incompleto** (20/08): `whatsapp_registration_error` (texto, a frase da
+  própria Meta — ex.: verificação em duas etapas ligada num número que veio de outra plataforma).
+  A caixa foi criada e **continua recebendo**; só o registro do número não terminou. É diferente de
+  `reauthorization_required` (esse emudece a caixa). Orientação: resolver do lado da Meta e clicar
+  em "Concluir registro" na caixa; a chave some quando o registro passa. Conectar uma caixa oficial
+  é ação de administrador e respeita o teto de caixas do plano (402 antes de abrir a janela da Meta).
+- Reconectar uma caixa em convivência pelo botão volta a pedir o histórico de 180 dias sozinho
+  (19/08); é um tiro único por onboarding — se a Meta recusar fora da janela de 24 h, não há
+  repetição.
 
 ## "O filtro de etiqueta 'não está presente' mente" — NUNCA mentiu pela API
 
@@ -521,6 +553,20 @@ Se alguma anotação antiga disser que esse filtro mente por API, está errada.
 verdade nos filtros: data FIXA com `is_greater_than`/`is_less_than` passou a cortar o dia no fuso
 da CONTA (ver resource `filtros-e-relatorios`).
 
+## "Mapeei o campo da integração pro atributo da conversa e nada foi gravado" (Meta Lead / Webhook Universal)
+
+ATENÇÃO (26/08/2026): atributo de conversa mapeado existe SÓ no Meta Lead e no Webhook Universal.
+Nos 9 gateways de pagamento a opção "salvar também na conversa" foi REMOVIDA (existiu de 21 a
+26/08) — o backend ignora `conversation_attribute_keys` se estiver gravada; os gateways gravam os
+dados da compra automaticamente no CONTATO, como sempre.
+
+Três causas, nesta ordem: (1) o evento não abriu conversa — atributo de conversa só existe na
+conversa que a automação/fluxo mapeado cria (contato sozinho não tem onde gravar); (2) a chave é
+reservada (`imported_from`, `type`, `captain_*`... — lista em `api-conventions`) e foi recusada;
+(3) o valor não é do TIPO do atributo (texto num campo de Número, data em formato estranho) e foi
+descartado — o log do servidor tem `[IntegrationAttributes] ... tipo_invalido=[...]`.
+Gravar por integração é silencioso: não espere automação nem webhook de saída reagindo ao atributo.
+
 ## Quando reportar pro suporte
 
 Reporte se:
@@ -533,3 +579,66 @@ NÃO precisa reportar:
 - 4xx (você fez algo errado)
 - Rate limit (esperado)
 - 404 de recurso deletado
+
+## Conector REMOTO "conecta e desconecta" a cada ~6 minutos (Claude Code / VS Code / Codex ligados direto)
+
+Vale SÓ para o conector remoto (`mcp.lionchat.com.br`). O conector local (npm, stdio) não tem canal de rede.
+Sintoma: `/mcp` alterna connected/disconnected a cada ~6 min; nenhuma chamada falha.
+Causa (21/08/2026): o cliente segura um canal GET esperando avisos do servidor; o Cloudflare derruba
+qualquer resposta que fique 125 s sem um byte (Proxy Read Timeout). Quem usa pela claude.ai/ChatGPT não
+abre esse canal e nunca vê isso.
+Correção (v1.15.1): o servidor manda um `ping` a cada 30 s enquanto o canal está aberto.
+Interruptor: `MCP_KEEPALIVE_INTERVAL_MS` (0 = desligado). Detalhe: `docs/plans/mcp-keepalive-cloudflare/`.
+
+## "O grupo não recebeu o resumo diário" (Avisos de relatório) — 27/08
+
+Diagnóstico em 2 passos: `lionchat_report_alerts_list` (colunas `last_delivery_status`/`last_error`
+resumem o último dia; `next_send_on` diz o próximo) e `lionchat_report_alerts_deliveries` (histórico
+de 90 dias com o TEXTO congelado de cada envio). Leitura dos status: `confirmed` = entregue COM
+recibo do canal; `sent` = saiu e o recibo ainda não veio (reconfere sozinho em ~15 min); `send_failed`
+= o canal recusou (motivo em `error_message` — caixa desconectada é o clássico: mande reconectar o
+WhatsApp QR); `skipped_late` = não saiu na janela de 3h (sistema congestionado; tenta amanhã — não é
+preciso fazer nada); `error` = falhou antes de enviar (ex.: 'conta suspensa', 'a conversa de destino
+não existe mais', 'nenhum bloco do relatório pôde ser calculado'). Aviso criado hoje DEPOIS do
+horário não dispara hoje (primeiro envio é amanhã) — não é defeito.
+
+## "A prévia do Aviso fica em pending pra sempre" — 27/08
+
+`report_alerts_preview_status` devolve `pending` enquanto o job (fila de baixa prioridade) não roda —
+normalmente 5-60 s, até ~2-3 min com a plataforma cheia. Espere 5-10 s entre leituras; NUNCA dispare
+outra prévia por impaciência (cada rodada com IA gasta a chave OpenAI da conta). O resultado expira
+5 min depois de pronto: `pending` que virou `error: token inválido` = token errado/expirado, rode a
+prévia de novo. Token tem 32 caracteres hex — confira que guardou o valor INTEIRO.
+
+## "Mandei mensagem numa conversa cheia de histórico e a Meta recusou (131047)" — 26/08
+
+Conversa que só tem mensagens IMPORTADAS de histórico NÃO tem janela de 24h aberta — para a Meta,
+aquele contato nunca escreveu pela conexão oficial (a mensagem existe no painel porque a importação a
+copiou do celular). O envio de texto livre é recusado mesmo com a fala do cliente visível na tela.
+Saída: modelo aprovado (template) ou esperar o cliente escrever de verdade pela caixa oficial.
+
+## "Adicionei etiqueta e as antigas sumiram" — CORRIGIDO em 24/08
+
+Era defeito real (o segundo bloco "Adicionar etiqueta" do mesmo fluxo apagava as do primeiro, e
+salvar status/prioridade apagava etiqueta posta por outro no meio do caminho). Hoje ADICIONAR SOMA,
+em todos os caminhos (fluxo, IA, API, ações em massa). Se um cliente relatar isso em versão antiga
+(whitelabel atrasado), é a versão — não oriente gambiarra de "reaplicar etiqueta".
+
+## "Os leads do Meta chegam só com id de campanha, sem nome" — 25/08
+
+Nome de campanha/conjunto/anúncio exige o **token de ANÚNCIOS** (é outro token, de CONTA — o login
+da página não basta). Diagnóstico: `lionchat_meta_lead_validate_token` (sem corpo testa o salvo) diz
+se o token é válido, de qual app e se alcança anúncio de verdade. Gravar/trocar:
+`lionchat_meta_lead_ads_token` — ao gravar, o servidor reprocessa retroativamente os leads que
+ficaram sem nome. E desde 25/08 o CONECTAR exige escolha: `meta_lead_create` com `page_ids` (sem
+ele TODAS as páginas do login entram — caso real de 25 páginas numa conta); pra limpar excesso
+antigo, `lionchat_meta_lead_bulk_destroy`.
+
+## "Atualizei a chave da caixa oficial pelo update e ela parou de receber" — 26/08
+
+`inboxes_update` com `channel.provider_config` SUBSTITUI o objeto inteiro: mandar só o campo
+alterado APAGA `webhook_verify_token` e a marca `source` em silêncio — a caixa para de receber
+webhook da Meta. Regra: leia a caixa antes (`inboxes_show`), reenvie o `provider_config` COMPLETO
+com o campo trocado. Os três campos da conexão manual (`phone_number_id`, `business_account_id`,
+`api_key`) são validados JUNTOS na Meta a cada gravação — 422 "Invalid Credentials" significa que
+algum dos três está errado ou a chave venceu (não salve campo a campo).