@lionchat/mcp-server 1.20.0 → 1.22.0

package/dist/docs/instructions.md

@@ -422,6 +422,7 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 | **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 |
 | Qualquer coisa de Ligação WP (Wavoip) | **INTEGRAÇÃO REMOVIDA em 12/08/2026** — não há tool nem tela | A Wavoip saiu do produto: a aba "Ligação WP" **não existe mais**. NUNCA orientar o usuário a "Configurações da caixa → Ligação WP". Para voz em caixa QR Code, o caminho hoje é o **LionCalls**. As ligações antigas seguem no histórico (`provider: "wavoip"`); as gravações delas ficavam no servidor da Wavoip e vão sumir — ao tentar ouvir, o painel mostra "Esta gravação não está mais disponível", e isso é esperado, não é defeito. |
 | Restringir agendas que a IA oferece | `lionchat_captain_assistants_update` (`config.booking_event_type_ids: [Int]`) | binding de agenda por cenário NÃO é settable via API |
+| **Programa de sessões** de um contato ("em que sessão ele está", ajustar total, encerrar/reabrir) | `lionchat_agenda_treatments_list` (por `contact_id`) / `_show` / `_update` | NÃO existe create: o programa nasce junto do agendamento (na TELA chama-se "programa"; na API segue `treatment`). Marcar TODAS de uma vez: `plano_sugerido` + `marcar_todas` de um tipo com `sessions_enabled` (`tasks_create` modo booking, `treatment: {...}` por pessoa; "marcar próxima" = `agenda_treatment_id` + `treatment_session_number`). Faltar CONSOME a sessão. Ver `lionchat://docs/agenda-multiplas-unidades` §7 |
 | Configurar o Copiloto (modelo/temperatura/prompt base) | `lionchat_copilot_settings_update` | admin-only; copiloto tem motor próprio (padrão temp 0.3) |
 | **Resetar/testar do zero a IA** numa conversa | `lionchat_conversations_captain_history_reset` (POST, sem body) | Cria pílula de marco na conversa; a partir dali TODA leitura autônoma da IA (respostas, resumo, follow-up) considera só mensagens pós-marco. Não apaga nada; o atendente segue vendo tudo. Enterprise-only |
 
@@ -441,6 +442,7 @@ Quando precisar de detalhes profundos, leia um destes documents via `resources/r
 - `lionchat://docs/api-conventions` — Auth, paginação, filtros, errors, rate limits
 - `lionchat://docs/conversation-flows` — Ciclo de vida de uma conversa (criação, auto-assignment, IA, resolução)
 - `lionchat://docs/kanban-deep-dive` — Estrutura completa do Kanban (Funnel/Stage/Item/pipeline)
+- `lionchat://docs/agenda-multiplas-unidades` — **Agenda por unidade**: o que `agenda_id` nulo significa, tipos de compromisso da conta, Booking ligado a unidade, página pública (cancelar/remarcar/confirmar), Google **uma conexão por agenda** e **programa de sessões** (N sessões de um tipo; faltar consome; marcar próxima e marcar todas)
 - `lionchat://docs/best-practices` — Como economizar tokens, evitar rate limit, ordem de operações
 - `lionchat://docs/troubleshooting` — Códigos HTTP, erros comuns, debugging
 - `lionchat://docs/flowbuilder-design-guide` — **OBRIGATÓRIO** antes de criar/editar fluxo: schema de nodes, handles expostos por tipo, layout/positioning, erros comuns, checklist

package/dist/docs/resources/agenda-multiplas-unidades.md

@@ -0,0 +1,185 @@
+# Agenda — unidades, tipos de compromisso e Google por agenda
+
+Guia da Agenda depois das frentes de 13/09 e 15/09/2026. Leia antes de mexer em agendas, tipos de
+compromisso, Booking ligado a unidade, conexão Google ou programa de sessões.
+
+---
+
+## 1. Uma agenda é um LUGAR, nunca uma pessoa
+
+Uma **agenda** é uma unidade: a matriz, uma filial, um consultório. Ela tem nome, fuso, cor, quem
+enxerga e **conta Google próprios**. Não confunda com o calendário de uma pessoa — quem tem
+calendário pessoal é o atendente, e ele aparece dentro da agenda.
+
+**Toda conta tem UMA agenda.** Ter mais de uma exige o recurso `multiple_agendas` ligado na conta
+(Super Admin), e o número de Extras Manuais define o teto — **zero ali significa ILIMITADO**, igual
+a Voz, Coex e Contratos. Sem o recurso, `agendas_create` é recusado.
+
+### `agenda_id` NULO significa "a agenda principal"
+
+Essa é a regra mais importante deste documento, e vale em **quatro** lugares: `account_tasks`,
+`booking_event_types`, `google_calendar_connections` e nos filtros.
+
+Nulo **não** quer dizer "sem agenda": quer dizer "a principal". É o que todo registro anterior à
+funcionalidade tem, e é por isso que ligar múltiplas agendas não exige retrocarga nenhuma — nada
+precisa ser migrado, nada muda de lugar.
+
+**Ao filtrar a agenda principal, inclua os nulos.** Filtrar `agenda_id = <id da principal>` sozinho
+esconde todo o histórico da conta.
+
+---
+
+## 2. Tipos de compromisso
+
+São **7 de fábrica**, no código: `task`, `follow_up`, `call`, `meeting`, `video_call`, `deadline`,
+`custom`. Não existem `consulta`, `retorno` nem `procedimento` — foram removidos em 13/09; mandar
+um desses em `task_type` dá 422.
+
+Além dos 7, a empresa **cria os dela** com o nome que usa ("Consulta", "Ondas de Choque", "Visita
+ao imóvel"), em `account_task_types`.
+
+- `key` é derivada do nome e **nunca muda**. É ela que fica gravada em `account_tasks.task_type`.
+  Renomear o tipo troca só o que aparece na tela; o histórico fica inteiro.
+- `icon` é uma **lista fechada de 12**. Qualquer outro valor é recusado pelo servidor — nome fora da
+  lista produz uma classe que nunca foi gerada e o ícone **some da tela, sem erro**.
+- Excluir um tipo **em uso** não apaga: **desativa** (`deactivated: true` na resposta). Os
+  compromissos antigos continuam com nome e ícone.
+
+⚠️ **O tipo que a conta cria conta como agendamento para a IA.** É o que impede o agente de IA de
+concluir que ainda não agendou e marcar o cliente **duas vezes**. Não existe interruptor para
+desligar isso — a chave saiu do `permit` de propósito.
+
+---
+
+## 3. Booking → agenda
+
+Cada tipo de evento do Booking tem `agenda_id`: é a unidade em que o agendamento feito pelo cliente
+vai nascer. Nulo = principal.
+
+Sem isso (até 13/09) **todo agendamento feito por Booking caía na agenda principal**, mesmo quando o
+profissional atendia na filial — e quem trocasse para a agenda da filial não via o agendamento.
+
+`agenda_id` de outra conta é recusado pelo modelo. A FK garante que a agenda existe; ela não garante
+que é sua.
+
+---
+
+## 4. Página pública (cancelar, remarcar, confirmar presença)
+
+O tipo de evento controla o que o cliente pode fazer:
+
+| Campo | Padrão | O que faz |
+|---|---|---|
+| `allow_cancel` | `true` | cliente pode cancelar |
+| `allow_reschedule` | `true` | cliente pode remarcar |
+| `ask_attendance_confirmation` | **`false`** | mostra "Sim, vou comparecer" |
+| `cancel_min_notice_hours` | vazio | antecedência mínima para cancelar |
+| `reschedule_min_notice_hours` | vazio | antecedência mínima para remarcar |
+| `reschedule_max_advance_days` | vazio | até quando pode remarcar |
+| `max_reschedules` | vazio | quantas vezes pode remarcar |
+
+**Vazio ou zero = sem limite** (falha aberta, de propósito: uma regra em branco nunca deve trancar o
+cliente para fora).
+
+### Variáveis da mensagem de abertura
+
+`{{nome}} {{titulo}} {{tipo}} {{agente}} {{data}} {{horario}} {{dia_semana}} {{duracao}}
+{{telefone}} {{email}} {{link_cancelar}} {{link_remarcar}} {{link_confirmar}}`
+
+As chaves são **em português nos dois idiomas** — elas são o identificador, não a tradução.
+Variável desconhecida **sai crua** para o cliente ("Olá {{name}}, ...").
+
+`{{link_confirmar}}` só é útil com `ask_attendance_confirmation` ligado.
+
+### Presença é CARIMBO, não status
+
+`attendance` (`attended` / `no_show`) é um campo separado de `status`. Marcar falta **não devolve o
+horário** para a agenda — decisão do dono. Não use `attendance` para deduzir se o compromisso está
+ativo; para isso existe `status`.
+
+---
+
+## 5. Google Calendar é UMA CONEXÃO POR AGENDA
+
+A regra já mudou duas vezes; hoje é: **uma conta Google por agenda**. Cada unidade liga a conta
+Google dela — inclusive a **mesma pessoa** com contas Google diferentes, uma por unidade.
+
+- `google_calendar_agendas` devolve uma linha por agenda com o estado de cada uma.
+- `agendas_list` / `agendas_show` trazem `google: { connected, email, state }` em cada agenda — dá para saber qual conta Google está ligada a qual unidade sem chamar o Google (o estado sai do banco). [13/09]
+- Agenda **sem** Google conectado simplesmente **não sincroniza** — ela não cai no Google da matriz.
+  O contrário mandaria o compromisso de uma unidade para o calendário de outra.
+- Os sub-calendários compartilhados com agentes pertencem à conexão daquela unidade.
+
+---
+
+## 6. Quem enxerga uma agenda
+
+- Agenda **sem** pessoas e **sem** equipes: todo mundo da conta enxerga.
+- Marcando pessoas e/ou equipes: só elas. Quem entrar na equipe ganha acesso sozinho.
+- **Administrador enxerga todas**, sempre.
+- `member_user_ids` e `member_team_ids` **substituem a lista inteira** (idioma do `InboxMember`).
+
+A listagem de compromissos já vem recortada pelas agendas que o usuário enxerga, **mesmo sem mandar
+`agenda_id`**. Ler ou editar compromisso de uma agenda que a pessoa não enxerga devolve 404.
+
+---
+
+## 7. Programa de sessões (15/09)
+
+Um **programa** é um pacote de N sessões do mesmo tipo de evento para um contato ("10 sessões de ondas
+de choque a cada 30 dias", "8 encontros de mentoria", "4 sessões de onboarding").
+
+⚠️ **Na TELA o nome é "programa"** (bloco "Programas", botão "Encerrar programa") — decisão do dono em
+15/09, porque nem sempre é saúde. No CÓDIGO e na API tudo continua `treatment`/`agenda_treatments`: as
+ferramentas, os campos e a tabela não mudaram. Ao falar com o cliente, diga **programa**; ao chamar a
+API, use os nomes de sempre. Cada encontro continua se chamando **sessão** nos dois lados. Só a primeira sessão nasce marcada; as outras ficam "a marcar" e a
+ficha do contato mostra em que pé está: quantas foram feitas, quantos por cento, quando é a próxima
+e se está atrasada.
+
+- **Liga-se no tipo de evento**: `sessions_enabled` + `sessions_default_count` (2 a 60) +
+  `sessions_interval_value`/`sessions_interval_unit` (`days`/`weeks`/`months`). Tipo sem isso não
+  cria programa nunca.
+- **O programa NASCE junto do agendamento** — não existe `create`. Todo agendamento de um tipo com
+  sessões (painel, link público ou IA) cria o programa do contato ou **engrossa** o que já está em
+  andamento como a próxima sessão livre. Um programa ativo por contato + tipo.
+- **Plano por pessoa**: no `tasks_create` em modo booking, `treatment: {sessions, interval_value,
+  interval_unit}` vence o padrão do tipo. É validado ANTES da reserva (422 sem agendar nada).
+- **"Marcar próxima"**: `tasks_create` com `agenda_treatment_id` + `treatment_session_number`. Sessão já
+  marcada dá 422; programa de outra ficha dá 422.
+- **Sessão k = compromisso VIVO (não cancelado) de número k.** Cancelar devolve a sessão; remarcar
+  mantém o número; **faltar consome** (decisão do dono — a falta gasta a sessão). "Usadas" = compareceu
+  + faltou. Nada disso é cache: o resumo é derivado das tarefas na leitura.
+- **Cheio** = todas as N marcadas e nenhuma usada ainda. Agendamento novo pelo painel/IA num
+  programa cheio vira **sessão extra** (N+1, até 60); pelo link público não vira nada (o
+  agendamento nasce solto, sem programa).
+- **Concluído** = usadas ≥ N. O `status` do programa só vira `completed` na próxima reserva daquele
+  tipo (aí abre um ciclo novo); `closed` é encerramento pela equipe (`close_reason: manual`) ou pela
+  junção de contatos (`mesclagem` — o programa do perdedor que colide com um do vencedor).
+- **Atrasado** = em andamento, próxima sessão com data prevista já passada e nenhuma sessão viva com
+  data futura. A previsão é a última data conhecida + intervalo × distância.
+- **Marcar TODAS as sessões que faltam** (15/09): `lionchat_agenda_treatments_plano_sugerido` devolve o dia e a
+  hora sugeridos por sessão (data prevista; sem vaga, anda para a frente e marca `deslocada`), e
+  `lionchat_agenda_treatments_marcar_todas` marca o que for confirmado. **Não é transação única**: sucesso parcial é
+  200 com `falhas` nomeadas, e o que entrou na agenda fica. Com confirmação ligada no tipo, o cliente recebe UMA
+  mensagem por sessão — avise isso antes de marcar em lote.
+- Ferramentas: `lionchat_agenda_treatments_list` (por `contact_id`, resumo pronto por programa),
+  `_show`, `_update` (`planned_sessions` nunca abaixo da maior sessão já marcada; `status`
+  `closed`/`active`). O compromisso devolve `tratamento: {id, sessao, total, titulo}` quando pertence a
+  um. Compromisso de agenda que o usuário não enxerga aparece na sessão como `oculta: true`.
+- O relatório de Agendamentos tem o bloco `treatments` (vale o período escolhido: programas, sessões do período e quem parou no meio — ver `reports-guide`).
+
+---
+
+## 8. Erros comuns
+
+| Sintoma | Causa |
+|---|---|
+| 422 'Ha sessoes marcadas alem dessa quantidade' ao reduzir `planned_sessions` | já existe sessão marcada acima do novo total; cancele-a antes |
+| 422 'Ja existe um tratamento em andamento deste tipo para este contato' (texto do servidor) ao reabrir | um programa ativo por contato + tipo; encerre o outro primeiro |
+| Agendamento novo não entrou no programa | tipo sem `sessions_enabled`, ou programa CHEIO agendado pelo link público (sessão extra só pelo painel/IA) |
+| 422 ao criar compromisso com `task_type: "consulta"` | os tipos clínicos saíram; use a `key` que `account_task_types_list` devolve |
+| Ícone do tipo não aparece | valor fora da lista fechada de 12 |
+| Agendamento do Booking caiu na unidade errada | `agenda_id` do tipo de evento não foi definido (nulo = principal) |
+| Compromisso da filial no Google da matriz | não acontece mais; se aparecer, a conexão daquela agenda está com `agenda_id` errado |
+| `agendas_create` recusado | recurso `multiple_agendas` desligado ou teto de Extras Manuais atingido |
+| Histórico sumiu ao filtrar a principal | faltou incluir os compromissos com `agenda_id` **nulo** |

package/dist/docs/resources/assinatura-eletronica.md

@@ -50,8 +50,10 @@ Participante: `pending` → `viewed` → `verified` (confirmou o código) → `s
   leitura de um modelo continuam abertas a qualquer membro. Cancelar contrato e apagar modelo: só administrador.
 - **Trava sagrada**: campo do modelo sem valor na ficha bloqueia o envio. Preencher a ficha primeiro.
 - **Validade** (`roles_layout.validity_days`, padrão 7) conta do ENVIO; `{{document.deadline}}` imprime a data no
-  texto; passou = `expired` (cron de hora em hora). **Lembrete** (`reminder_days`, padrão 2, 0 = off): quem não
-  assinou recebe o link de novo a cada N dias.
+  texto; passou = `expired` (cron de hora em hora). **Lembrete NÃO é mais função do sistema** (14/09): o campo
+  `reminder_days` e a tarefa diária das 10h foram REMOVIDOS. Quem lembra é um fluxo do cliente, com o texto e a
+  caixa dele — gatilho "Link de assinatura enviado para uma pessoa" (`signature_delivered`, um disparo por
+  pessoa), bloco Esperar em dias e a condição "Situação do contrato". Nunca sugerir `reminder_days`.
 - **Conversor de Word** é um serviço separado (docx-converter). Fora do ar = `422 conversor_indisponivel` na prévia e no envio de modelo Word — é o serviço, não o arquivo; repetir em instantes. Modelos `text` e `file` não passam por ele.
 - **Fila única de conversão do Word**: uma conversão por vez em toda a instalação (todas as contas); pela tela espera-se até 10 s, automação/macro/fluxo/formulário até 2 s.
   Passou disso o envio/prévia volta `422 fila_cheia` — é só repetir em instantes (o modelo está bom).

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

@@ -390,6 +390,42 @@ integração conectada na conta (senão é pulado em silêncio — confira as li
 (o que iniciou o fluxo ou o mais recente da conversa); sem card, o registro NÃO aparece nas telas de
 eventos do Funil (só no histórico do fluxo). Formato completo no `flowbuilder-design-guide`.
 
+### Meta CAPI — lead que chegou por ANÚNCIO DE WHATSAPP (2026-09-10)
+
+Quem chegou pelo botão de WhatsApp de um anúncio (a conversa carrega `ctwa_clid` e a caixa é a
+oficial, com WABA) sai pra Meta como evento de MENSAGEM (`action_source: business_messaging`) — e a
+Meta só aceita isso num **dataset vinculado à WABA**, nunca no pixel do site (recusa 2804132). Até
+10/09 100% desses eventos caíam no plano B (saíam como site) sem ninguém ver. Regras pro MCP:
+
+- **Vincular a caixa primeiro:** normalmente NÃO é preciso — o vínculo é automático (na criação da caixa
+  e por varredura a cada 10 min). Se `capi_dataset_id` estiver vazio, `lionchat_inboxes_capi_dataset_link`
+  (POST `/inboxes/{id}/capi_dataset`) força na hora.
+  Idempotente, vale para todos os números da mesma WABA, usa a chave da PRÓPRIA caixa (a do pixel não
+  serve). O id fica em `provider_config.capi_dataset_id` (visível em `lionchat_inboxes_show` para admin).
+  Sem o vínculo os eventos de anúncio saem como site com `fallback_reason: lionchat:dataset_nao_configurado`.
+- **Nome do evento em mensagem = SÓ 14:** `LeadSubmitted`, `QualifiedLead`, `ViewContent`, `AddToCart`, `InitiateCheckout`, `Purchase`, `OrderCreated`, `OrderShipped`, `OrderDelivered`, `OrderCanceled`, `OrderReturned`, `CartAbandoned`, `RatingProvided`, `ReviewProvided`.
+  O evento de SITE continua com o nome que o cliente quiser. A escolha de WhatsApp mora em
+  `messaging_name` (etapa e `won` do `meta_events_config`, tool `lionchat_funnels_meta_events_config`),
+  em `messaging_event_names.meta` (bloco `send_conversion` do fluxo) e em `messaging_event_name`
+  (disparo manual `lionchat_kanban_items_meta_capi_fire`). Tri-estado: chave AUSENTE = automático
+  (Lead/Contact → LeadSubmitted, Purchase → Purchase, InitiateCheckout → InitiateCheckout; sem sugestão
+  o lead de anúncio sai como site com motivo), `''` = não enviar como WhatsApp, um dos 14 = escolha.
+  Nome fora dos 14 é descartado no funil e dá 422 no disparo manual. `lost` (Perdido) é sempre site —
+  não existe evento de "perdido" em mensagens. O nome interno do cliente vai em `custom_data.internal_event`.
+- **Diagnóstico "por que a venda não contou como conversão de WhatsApp?":**
+  `lionchat_funnels_meta_capi_events_list` com `degraded=true` e ler `fallback_reason` + `action_source`.
+  Motivos nossos: `lionchat:dataset_nao_configurado` (falta o vínculo), `lionchat:caixa_token_recusado`
+  (a Meta recusou a chave da caixa — reconectar a caixa), `lionchat:caixa_nao_encontrada`,
+  `lionchat:caixa_sem_token`, `lionchat:dataset_id_invalido`, `lionchat:desligado_pelo_cliente`,
+  `lionchat:nome_sem_equivalente_whatsapp`; da Meta: `"<subcode>: <mensagem>"` (ex.: 2804087 = clique
+  do anúncio inválido/expirado).
+- Recusa ao vincular (422 com `subcode`, ex.: 2804116 / "whatsapp_business_manage_events"): a chave da
+  caixa não tem a permissão — reconectar a caixa pelo Cadastro Incorporado da Meta; nunca pedir o token
+  do pixel para isso. Um 401/403 da caixa NUNCA desliga o pixel da conta (site, formulário e agenda
+  continuam) — o evento de anúncio apenas sai como site com o motivo.
+- NUNCA prometer que eventos antigos voltam: o plano B marca como enviado (não há retry) e a Meta só
+  aceita evento com até 7 dias.
+
 ### Meta Lead — token de anúncios de OUTRO app (2026-09-01)
 
 `lionchat_meta_lead_validate_token` pode voltar `app_verified: false` com `expires_at` nulo: é token
@@ -693,7 +729,7 @@ automática. Ver a seção de variáveis de conta acima.
 
 - **Tipo de atributo `time` (Hora 24h):** ao criar custom attribute com `attribute_display_type: "time"` (ou o numérico `9`), o valor canônico é `"HH:MM"` 24h e o fuso mora na definição (`attribute_timezone`, IANA, default `America/Sao_Paulo`). Uso principal: alimentar o campo Horário do node `wait` (modo date, `waitTimeMode: "variable"`).
 - **Tipo de atributo `datetime` (Data e Hora, novo 2026-07-18):** `attribute_display_type: "datetime"` (ou numérico `10`), com `attribute_timezone` (default `America/Sao_Paulo`). Guarda data+hora juntas em ISO com offset (`"2026-07-18T14:55:00-03:00"`); exibe `"DD/MM/AAAA - HH:MM"`. Um porteiro no backend aceita e converte vários formatos de entrada (ISO/UTC/BR/AM-PM/unix). **ATENÇÃO ao montar flows:** o tipo `datetime` NÃO é selecionável no Gatilho de Data nem nos campos Data/Horário do node `wait` — esses continuam exigindo `date`(5) pra data e `time`(9) pra hora, SEPARADOS. O `datetime` é, por ora, tipo de armazenamento/exibição (sidebar + mensagens humanas), não fonte de entrada de fluxo. Em condição, atributo `datetime` é tratado como string (compara o ISO cru).
-- **Timeout de flow `ai_tool` com node `api`:** sobe sozinho de 20s pro teto de 45s quando ainda está no padrão — não precisa configurar nada; só evite setar `execution_timeout_ms` custom se quiser manter o auto-ajuste.
+- **Timeout de flow `ai_tool` com node `api`:** sobe sozinho de 20s pro teto de 45s quando ainda está no padrão e, desde 10/09/2026, DESCE de volta pro teto quando o último node `api` é apagado (antes o valor gravado ficava acima do teto e o flow não salvava mais — o 422 vinha como "configuração incompleta" sem nenhum bloco vermelho). Não precisa configurar nada; só evite setar `execution_timeout_ms` custom se quiser manter o auto-ajuste. Valor acima do teto enviado por API/MCP continua recusado.
 - **Teste do node `api`:** o resultado do último teste fica salvo no servidor (pin, TTL 30 dias) — sobrevive a trocar de navegador/máquina. Isso é recurso do editor humano; não há tool MCP pra isso.
 
 ## Status codes a respeitar
@@ -888,3 +924,11 @@ administrador."* — a recusa é `before_action`, então NADA do resto do update
 Ao atualizar o próprio usuário: mande times e caixas à vontade; **não mande `role` nem
 `custom_role_id`** — se mandar, a chamada inteira falha e as outras alterações se perdem também.
 Para trocar o cargo de alguém, use a conta de OUTRO administrador.
+
+## Cargo personalizado: descrição CURTA (16/09/2026)
+
+Em `custom_roles_create` / `custom_roles_update`, a `description` é **uma frase de até 60 caracteres**
+(ex.: *"Tudo, menos conversas das caixas em que não foi adicionado."*). **Não liste as permissões
+na descrição** — a tela já as mostra na coluna "Permissões". Uma descrição de 180 caracteres
+escondeu o cargo recém-criado na lista de Funções personalizadas da conta 1 (a tela foi corrigida
+para cortar o texto com reticências, mas a descrição longa continua ilegível ali).

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

@@ -439,7 +439,7 @@ POST .../conversations/{id}/toggle_status
 
 | Ação | Tool / endpoint | Efeito |
 |---|---|---|
-| Marcar como **lida** | `update_last_seen` (POST `.../update_last_seen`) | Atualiza `agent_last_seen_at`; em canal WAHA dispara check azul no WhatsApp |
+| Marcar como **lida** | `update_last_seen` (POST `.../update_last_seen`) | Atualiza `agent_last_seen_at` e, em canal WhatsApp (QR Code ou oficial), dispara o check azul — **só quando há mensagem do cliente ainda não lida** (12/09); sem entrante nova a chamada cai na trava de 1 h e devolve o carimbo já gravado |
 | Marcar como **não-lida** | `conversations_unread` (POST `.../unread`) | Recua o `last_seen` pra antes da última mensagem do cliente — conversa volta a aparecer como não-lida |
 
 Ambas são **ações de escrita** (POST). `unread` é o oposto de `update_last_seen`, não uma consulta.
@@ -704,6 +704,7 @@ Todos os formatos abaixo foram conferidos linha a linha em `app/services/action_
 | `assign_agent` | `[70]` — o agente precisa ser membro da caixa. `["nil"]` desatribui |
 | `assign_team` | `[3]`. `["nil"]` desatribui |
 | `assign_captain_assistant` | `[17]` ou `[{"assistant_id": 17, "proactive": true}]` — `proactive` false = a IA assume mas nao fala na hora |
+| `deactivate_captain` | `[]` — desliga o AI Agente da conversa (novo 10/09/2026; a macro também tem) |
 | `send_email_to_team` | `[{"team_ids": [1], "message": "texto"}]` |
 | `send_webhook_event` | `["https://..."]` |
 | `send_attachment` | `[blob_ids]` — so funciona se a regra ja tiver arquivo anexado; nao da pra montar so por API |
@@ -713,7 +714,7 @@ Todos os formatos abaixo foram conferidos linha a linha em `app/services/action_
 | `mute_conversation` | `[]` |
 | `snooze_conversation` | `[]` |
 | `resolve_conversation` / `open_conversation` / `pending_conversation` | `[]` |
-| `update_contact_attribute` / `update_conversation_attribute` | `[{"attribute_key": "chave", "value": "texto ou {{contact.phone_number}}"}]` |
+| `update_contact_attribute` / `update_conversation_attribute` | `[{"attribute_key": "chave", "value": "texto ou {{contact.phone_number}}"}]` — chave PROTEGIDA é recusada na execução e fica só no log (10/09/2026): prefixos `waha_whatsapp_`, `whatsapp_`, `origin_`, `ctwa_`, `meta_lead_`, `lt_` e atributos de sistema como `utm_*`/`gclid`. Vale pra macro e automação |
 | `create_kanban_item` | `[{"funnel_id": 31, "funnel_stage": "prospeccao", "allow_duplicates": false}]` |
 | `move_kanban_item_to_stage` | `[{"funnel_id": 31, "funnel_stage": "qualificacao"}]` |
 | `assign_agent_to_kanban_item` | `[{"funnel_id": 31, "agent_id": 70, "mode": "add"}]` — `mode` aceita `add` (padrao) ou `remove_all` |

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

@@ -150,8 +150,28 @@ Company
 ├── account_id (FK)
 ├── name
 └── domain
+
+AttributeChange (histórico de alterações de atributo — 2026-09-11)
+├── id (PK)
+├── account_id (FK)
+├── contact_id (FK, opcional) / conversation_id (FK, opcional)
+├── target_type + target_id ('Contact' | 'Conversation')
+├── field (name | email | phone_number | date_of_birth | gender | cadastral.* | address.* | custom.<chave>)
+├── old_value / new_value (jsonb)
+├── actor_type + actor_id + actor_label (User | Captain::Assistant | Flow | AutomationRule | LeadForm | Integration | System)
+├── source (panel | api | mcp:npm | mcp:remote | flow | automation | ai | form | integration:<nome> | merge | system)
+├── merged_from_contact_id (linha que veio de ficha mesclada)
+└── created_at
 ```
 
+**Histórico de alterações (`attribute_changes`, 2026-09-11):** uma linha por campo que mudou (contato ou
+conversa), com valor antes/depois, quem mudou e por onde. Mudança feita pelo MCP sai com `source`
+`mcp:npm`/`mcp:remote` e o usuário do token como ator. Criação não gera linha; importação de planilha
+não gera; chaves protegidas (rastreio `utm_*`/`gclid`, `waha_*`, `eclinica_*`, e toda definição
+`system: true`) ficam fora. Leitura: `GET contacts/{id}/attribute_changes` e
+`GET conversations/{id}/attribute_changes` (50/página; filtros `field`, `source`); telefone, e-mail,
+nascimento e documentos vêm mascarados (`masked: true`) para quem não é administrador. Retenção 180 dias.
+
 **`additional_attributes` vs `custom_attributes` no Contato:**
 - `additional_attributes` (jsonb): campos do sistema porém **EDITÁVEIS via API** (`permitted_params` permite `additional_attributes: {}`). Guarda chaves padrão como `city`, `company`, `country_code` — que são as chaves filtráveis em `lib/filters/filter_keys.yml` (tipo `additional_attributes`). NÃO é não-editável.
 - `custom_attributes` (jsonb): dado de negócio livre, definido pelo cliente via Atributos Customizados.
@@ -196,12 +216,23 @@ Funnel
 ├── stages (jsonb: hash com slug_etapa => { name, color, position, description, checklist_templates })
 ├── settings (jsonb: { agents: [], goals: [], automations: [{trigger_type, action, action_config, enabled}] })
 ├── global_custom_attributes (jsonb array)
-├── meta_events_config (jsonb: won/lost/stages → Meta Pixel/CAPI events)
+├── meta_events_config (jsonb: won/lost/stages → Meta Pixel/CAPI events; cada bloco: enabled, name,
+│     is_standard, value_strategy, value_fixed, currency, messaging_name — este último é o evento de
+│     ANÚNCIO DE WHATSAPP, tri-estado: ausente = automático, '' = não enviar, um dos 14 nomes da Meta;
+│     só em stages e won, nunca em lost)
 ├── archived (bool)
 ├── active (bool)
 ├── position (int, ordem entre funis)
 └── created_at
 
+MetaCapiEvent (meta_capi_events — cada envio de conversão pro Meta)
+├── event_name (nome INTERNO, o que o cliente escolheu), event_id (idempotência), status (pending/sent/failed/duplicate)
+├── trigger_type, kanban_item_id, contact_id, conversation_id, funnel_id, meta_pixel_integration_id
+├── inbox_id (2026-09-10: a caixa oficial de onde saiu a WABA — o envio de anúncio de WhatsApp usa o dataset e a chave DESSA caixa)
+├── fallback_reason (2026-09-10: preenchido quando um evento de anúncio de WhatsApp saiu como SITE — plano B; NULL = não degradou)
+├── payload_sent (jsonb: data[0].action_source = website | business_messaging; data[0].event_name = o nome que FOI pra Meta)
+└── response_body (jsonb: resposta da Meta; `fallback_from` = a recusa original quando houve plano B)
+
 KanbanItem
 ├── id (PK)
 ├── account_id (FK)
@@ -341,6 +372,17 @@ Macro
 └── visibility (personal/global)
 ```
 
+**Macro — ações e freios (10/09/2026).** `actions` aceita 40 nomes: todos os das automações (mesmos
+`action_params`, ver a tabela em conversation-flows.md) mais os que só a macro tem — `mark_unread` (`[]`),
+`add_contact_label`/`remove_contact_label` (`[titulos]`, etiqueta do CONTATO), `distribute_agents`
+(`[agent_ids]`, rodízio de verdade), `update_card_attribute` (`[{funnel_id, attribute_key, value}]`),
+`add_card_checklist` (`[{funnel_id, checklist_template_ids}]`), `add_card_offer` (`[{funnel_id, offer_ids}]`)
+e `send_conversion` (`[{destinations, event_names, value}]` — só administrador ou cargo com
+`marketing_integrations_manage` consegue SALVAR a macro; executar segue livre; teto de 50 conversões por
+execução). Atributo protegido em `update_*_attribute` é recusado na execução (só no log). Executar
+(`lionchat_macros_execute`): até 100 conversas por chamada, a mesma conversa em 5 s é pulada em silêncio,
+30 execuções por minuto por usuário (429). A mensagem de `send_canned_response` sai assinada por quem executou.
+
 ## Agenda / Tarefas / Booking
 
 ```
@@ -362,8 +404,25 @@ AccountTask (agenda interna)
 ├── meeting_url (string, sala de reunião call/meeting)
 ├── guest_emails (jsonb array, convidados extras — máx 20)
 ├── conversation_id / contact_id / linked_kanban_item_id (FK opcionais)
+├── booked_by (polimórfico User/Contact/Captain::Assistant) / booked_by_name / booking_source
+│   (painel|link|ia|sistema|fluxo) — QUEM agendou e por onde (14/09)
+├── attendance (enum attended=0 / no_show=1, NULO = nada registrado — CARIMBO, não muda status)
+│   / attendance_by (polimórfico) / attendance_source — quem marcou Compareceu/Faltou (14/09)
+├── agenda_treatment_id (FK → AgendaTreatment, nullify) / treatment_session_number (1..N) — a sessão
+│   que este compromisso é; índice único parcial por tratamento+número entre os NÃO cancelados (15/09)
 └── assignees (has_many → User, via account_task_assignments)
 
+AgendaTreatment (tratamento em sessões — tools `agenda_treatments_*`; tabela agenda_treatments; 15/09)
+├── id (PK) / account_id (FK) / contact_id (FK) / booking_event_type_id (FK, nullify)
+├── event_type_title (cópia do nome do tipo — sobrevive à exclusão do tipo)
+├── planned_sessions (2..60) / interval_value (1..365) / interval_unit (days|weeks|months)
+├── status (active|completed|closed) / close_reason (manual|mesclagem) / closed_at
+├── source (painel|link|ia|sistema|fluxo) / created_by_id (FK → User, só quando foi gente)
+├── índice único parcial (account_id, contact_id, booking_event_type_id) WHERE status='active'
+│   — UM tratamento ativo por contato + tipo
+└── account_tasks (has_many, nullify) — sessão k = tarefa VIVA de número k; usadas/percentual/atrasado/
+    concluído são DERIVADOS na leitura (nenhuma coluna de cache)
+
 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)
@@ -375,6 +434,8 @@ db/schema.rb, tabela booking_event_types)
 ├── color (hex `#RRGGBB`, opcional — cor dos compromissos desse tipo no calendário; vazio = cor do
 │   agente; 2026-08-19)
 ├── active / ask_email / ask_description
+├── sessions_enabled (bool) / sessions_default_count (2..60) / sessions_interval_value (1..365) /
+│   sessions_interval_unit (days|weeks|months) — tratamento em sessões: padrão do tipo (15/09)
 ├── confirmation_* (mensagem de confirmação própria: enabled, inbox_id, channel_type,
 │   template_name, blocks). Variáveis nos textos de confirmação E de lembrete (interpolador único):
 │   {{nome}} {{email}} {{telefone}} {{data}} {{horario}} {{dia_semana}} (NOVO 24/08 — dia por
@@ -436,6 +497,11 @@ daquele tipo no calendário; vazio = cor do agente. A tarefa devolve `booking_co
 `cliente_alteracao_pagamento`, `odontograma_finalizado`, `inclusao_procedimento`
 (capturados ao vivo, não documentados pelo e-Clínica).
 
+O recurso `eclinica_integration` da conta passou a ser ligado e desligado pelo PRÓPRIO cadastro da
+integração (10/09/2026, `auto_managed`): sumiu do Super Admin e não há passo manual — os blocos de
+relatório e as tools da e-Clínica valem assim que a integração existe. Contas que já tinham integração
+receberam o recurso no deploy (migração).
+
 Os 3 últimos são do perfil ODONTOLÓGICO: `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);
@@ -468,6 +534,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_link_confirmacao` | **link** | Link ecli.co para o paciente confirmar/cancelar a ÚLTIMA consulta (novo 2026-09-08; só existe quando a unidade aprendeu o padrão na aba Unidades). No LEMBRETE use a variável `{{link_confirmacao}}` do fluxo (ou `{{agendamento.link_confirmacao}}` na automação): é da consulta certa — a ficha aponta para a última, e quem tem duas marcadas receberia o link errado |
+| `eclinica_paciente_nome` | text | Nome do PACIENTE como está no cadastro da e-Clínica (novo 2026-09-09). O nome do contato pode ser o do WhatsApp (mãe que agenda o filho pelo celular dela) — por isso NUNCA use `{{contact.name}}` nas mensagens da clínica. Nos fluxos por evento: `{{ contact.custom_attribute.eclinica_paciente_nome \| default: contact.name \| primeiro_nome }}`; no LEMBRETE use a variável `{{ paciente_nome \| default: contact.name \| primeiro_nome }}` (por consulta) ou `{{agendamento.paciente_nome}}` na automação. `primeiro_nome` = primeira palavra com inicial maiúscula. |
 | `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) |
@@ -590,6 +658,11 @@ MetaLeadIntegration (Facebook Lead Ads)
 ├── facebook_page_id (FK polimórfico)
 ├── status (active/token_expired/paused)
 └── meta_lead_forms (has_many)
+    → cada lead vira CONTATO com os atributos meta_lead_* (form_id/form_name, campaign_id/name,
+      adset_id/name, ad_id/name, creative_id/name, platform, account_id/name; definidos por conta como
+      atributo de contato). Filtráveis em contacts_filter como atributo personalizado; desde 10/09/2026
+      também no filtro da tela de contatos e no painel "Atributos de Campanha" da conversa
+      (meta_lead_form_name aparece como "Origem - Formulário")
 
 LeadForm (Formulário público de captação — feature flag lead_forms, por conta)
 ├── account_id (FK)
@@ -733,7 +806,7 @@ SignatureDocument (modelo)  1 ──── N  SignatureEnvelope (contrato de UMA
    body ({{variáveis}}), tags,             contact_id, conversation_id,                       status, phone/email, delivery_channel,
    roles_layout {signers, witnesses,       original_sha256, sealed_sha256,                    conversation_id (a conversa DELE),
    sender_signs, require_id_photo,         created_by (quem mandou)                           public_url, signed_at, viewed_at
-   validity_days, reminder_days}                │
+   validity_days}                               │
    progress (contagem por balde)                └── N  SignatureEvent (append-only: kind, occurred_at, ip, user_agent, detail)
 ```
 - Contrato aponta pro contato (`contact_id`, nulifica se a ficha for apagada — a prova sobrevive) e pra conversa

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

@@ -529,8 +529,9 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 | `add_card_offer` | `{ offer_id, use_custom_value?, custom_value?, funnel_id?, card_source? }` | Adiciona uma OFERTA (produto/serviço) ao card. `offer_id` de `offers_list`. `use_custom_value: true` + `custom_value` grava um valor personalizado na oferta; senão usa o valor cadastrado. O total do card recalcula sozinho (soma das ofertas). Respeita `card_source` (funnel só localiza o card) |
 | `send_webhook` | `{ url, headers?, body? }` | Dispara webhook externo |
 | `start_flow` | `{ flow_id }` | Inicia outro fluxo. **NÃO encerra o fluxo de origem** (desde 31/08): se houver bloco ligado depois dele, o fluxo SEGUE normalmente. Sendo o último do desenho, o fluxo termina ali como sempre. |
-| `send_conversion` (novo 2026-09-01; `event_names` 2026-09-02) | `{ destinations: ['meta'\|'ga4'\|'google_ads'], event_names: { meta?, google_ads?, ga4? }, event_name (reserva), value? }` | Manda o evento de conversão pro Meta (CAPI), Google Ads e/ou GA4 — o mesmo caminho do Funil, de dentro do fluxo. Aba Sistema (só flow `conversation`). Ver bloco próprio abaixo |
+| `send_conversion` (novo 2026-09-01; `event_names` 2026-09-02; `messaging_event_names` 2026-09-10) | `{ destinations: ['meta'\|'ga4'\|'google_ads'], event_names: { meta?, google_ads?, ga4? }, messaging_event_names: { meta? }, event_name (reserva), value? }` | Manda o evento de conversão pro Meta (CAPI), Google Ads e/ou GA4 — o mesmo caminho do Funil, de dentro do fluxo. Aba Sistema (só flow `conversation`). Ver bloco próprio abaixo |
 | `deactivate_flow` ou `disable_flow` | `{}` | Encerra fluxo atual |
+| `set_booking_situation` (novo 2026-09-14) | `{ situation: 'cancelled' \| 'completed' \| 'attended' \| 'no_show' \| 'confirmed' }` | Muda a situação do agendamento **que disparou o fluxo** (gatilho de agendamento do bloco Início, ou fluxo ligado na configuração do tipo de agendamento). Aba **Agenda** (só flow `conversation`, só com a Agenda ligada na conta). Disparado por outra coisa: **não faz efeito e o passo fica com erro visível** (não há como adivinhar o agendamento). Já no estado pedido = passo PULADO, sem escrita (sem evento, sem laço). `cancelled` cancela o **agendamento** (desarma lembretes, invalida o link de gerenciar). Origem gravada = `fluxo`, ator = o próprio flow. Sem `rescheduled`/`snoozed`: o bloco não mexe em data |
 | `update_attribute` | `{ attr_source: 'contact'\|'conversation'\|'card', attr_key, attr_value }` | Seta custom_attribute (ver abaixo) |
 | `assign_captain` (ou `assign_captain_assistant`) | `{ assistant_id }` | Atribui IA Captain |
 | `deactivate_captain` | `{}` | Tira a IA da conversa |
@@ -542,7 +543,7 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 **`send_conversion` — Enviar conversão (2026-09-01):**
 
 ```json
-{ "key": "send_conversion", "config": { "destinations": ["meta", "google_ads"], "event_names": { "meta": "Lead", "google_ads": "Contact" }, "event_name": "Lead", "value": "1500,50" } }
+{ "key": "send_conversion", "config": { "destinations": ["meta", "google_ads"], "event_names": { "meta": "Lead", "google_ads": "Contact" }, "messaging_event_names": { "meta": "QualifiedLead" }, "event_name": "Lead", "value": "1500,50" } }
 ```
 
 - `destinations`: array com `meta`, `ga4` e/ou `google_ads` — **OBRIGATÓRIO e não vazio** (vazio = a ação
@@ -555,6 +556,15 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
   Chave presente e em branco = aquele destino é PULADO ("sem nome de evento"); chave ausente cai em `event_name`.
   Google Ads só envia evento que tenha ação mapeada na integração; a tela lista Meta (padrão + personalizados
   da conta) e Google Ads (mapeados), GA4 é livre. Grave sempre `event_names` E `event_name` (= primeiro nome).
+- `messaging_event_names` (**desde 2026-09-10**, só a chave `meta`): o evento de **ANÚNCIO DE WHATSAPP**. Quem chegou
+  por anúncio de WhatsApp (clique para o WhatsApp, caixa oficial vinculada à Meta) sai como `business_messaging`, e
+  nesse caso a Meta só aceita 14 nomes: `LeadSubmitted`, `QualifiedLead`, `ViewContent`, `AddToCart`,
+  `InitiateCheckout`, `Purchase`, `OrderCreated`, `OrderShipped`, `OrderDelivered`, `OrderCanceled`, `OrderReturned`,
+  `CartAbandoned`, `RatingProvided`, `ReviewProvided`. Tri-estado: chave **ausente** = automático (sugestão pelo
+  evento de site: Lead/Contact → LeadSubmitted, Purchase → Purchase, InitiateCheckout → InitiateCheckout; sem sugestão
+  o lead de anúncio sai como site com `fallback_reason`); `""` = não enviar como WhatsApp (sai como site); um dos
+  14 = escolha. Nome fora da lista é ignorado (vira automático). Não afeta GA4/Google Ads. O nome interno do
+  cliente (`event_names.meta`) vai em `custom_data.internal_event`.
 - `event_name`: reserva/compatibilidade (fluxos de antes de 02/09), só letras/números/sublinhado (até 40; ex.: `Lead`, `Schedule`,
   `Purchase`); aceita variável `{{ }}`. No **Google Ads** o nome precisa estar mapeado no
   `conversion_action_map` da integração, senão é pulado.
@@ -834,7 +844,7 @@ tela do cliente (a tela lê só `percent`).
 ### 2.11 `update_group` — Gestão de Grupos (WAHA apenas)
 
 Bloco "Gestão de Grupos". Faz **UMA operação por bloco** (não mais um formulário-só com nome/foto/descrição
-juntos) — a operação vai em `data.groupOperation`. São **17 operações**, agrupadas por tema:
+juntos) — a operação vai em `data.groupOperation`. São **18 operações**, agrupadas por tema:
 
 - **Grupo:** `create` (criar), `find_by_id` (buscar por id), `find_by_name` (buscar por nome), `update_subject`
   (mudar nome), `update_description` (mudar descrição), `update_picture` (mudar foto), `settings` (3
@@ -843,6 +853,10 @@ juntos) — a operação vai em `data.groupOperation`. São **17 operações**,
 - **Admins:** `promote_admin` (promover a admin), `demote_admin` (rebaixar).
 - **Convite:** `get_invite` (pegar link/código de convite), `revoke_invite` (revogar), `send_invite` (mandar
   o convite por mensagem a um telefone).
+- **Mensagem no privado:** `send_private_message` (a 18ª, 16/09) — `groupPrivateTo` (obrig, telefone com código do
+  país, aceita `{{trigger.participant.phone}}`) + `messageItems`; manda no PRIVADO desse telefone, criando contato
+  e conversa para quem nunca conversou. Sem variável de resposta, sem `groupTargetId`, sem teto diário. É o jeito
+  de falar com quem acabou de entrar no grupo (o flow individual só roda para quem já tem conversa).
 - **Mensagem:** `send_message` (a 17ª, 08/08) — manda `messageItems` (MESMO contrato do bloco de mensagem:
   text/delay/attachment/audio/url_media; botões/template não fazem sentido em grupo) NA CONVERSA DO GRUPO
   (`groupTargetId` ou, vazio, o grupo da conversa atual; grupo inexistente = `error`). NÃO grava
@@ -1022,6 +1036,7 @@ O campo `flow_type` (definido na criação, IMUTÁVEL depois) decide a natureza
 | Campos extra | — | `tool_name` (snake_case, `[a-z][a-z0-9_]`, max 50) + `tool_description` (max 500) OBRIGATÓRIOS |
 | Retorno | manda mensagens | retorna dado estruturado ao LLM via node `end` |
 | Nodes permitidos | todos | `start`, `end`, `api`, `condition`, `set_variable`, `ai`, `note`, `randomizer`, `action`, `send_message` |
+| Aviso de espera (10/09/2026) | — | enquanto a ferramenta roda, o cliente recebe "Só um momento, estou verificando isso pra você...". Cada ferramenta escolhe o seu no node `start`: `data.toolWaitMessageEnabled` (`false` desliga; AUSENTE = ligado — só um `false` de verdade desliga, `""` ou lixo mantém ligado) e `data.toolWaitMessageText` (texto próprio, até 1000 caracteres; vazio = frase padrão). Vive no `flow_data` e viaja no snapshot de versão; ferramenta já existente não muda de comportamento |
 
 Se o cliente pediu "uma ferramenta que a IA usa pra consultar X / calcular Y", é `ai_tool`. Se pediu "quando chega mensagem, faça Z", é `conversation`. Na dúvida, `conversation`.
 
@@ -1130,15 +1145,35 @@ Dois atalhos: `{{trigger}}` devolve o contexto INTEIRO em JSON e `{{trigger.data
 sem os metadados — úteis pra jogar tudo dentro de um node `ai` ou `api`. Bloco (Hash/Array) inteiro
 sai em JSON; valor simples sai cru.
 
-**O que o histórico mostra e NÃO é variável (22/08/2026).** O passo Início do histórico de execução
-passou a exibir, em todo gatilho, o contato (nome, telefone, e-mail), a conversa (número, canal, caixa)
-e os fatos do que disparou: etiqueta, responsável/equipe (ou "removido"), card (título, funil, etapa
-anterior → etapa), política de SLA, grupo, nome do formulário e do marco, anúncio/formulário/campanha
-do Meta Lead (+ as respostas, em bloco próprio), produto/oferta/meio de pagamento do gateway, evento/
-unidade/data/hora/compromisso da e-Clínica, tecla do TopSend, e os dados do agendamento. Esses fatos
-ficam numa área só-de-log (`_trigger_facts`) — **não existem como `{{trigger.*}}`** e não entram em
-`{{trigger.data}}`. Se o cliente precisar de um deles no fluxo, use a variável de origem quando
-existir (`{{booking.*}}`, `{{form_*}}`, `{{contact.*}}`, atributos do contato gravados pela integração).
+**Os fatos do que disparou VIRARAM variáveis (08/09/2026).** Desde 22/08 o passo Início do histórico
+mostra, em todo gatilho, o contato, a conversa e os fatos do que disparou. Desde 08/09 esses fatos
+também RESOLVEM como `{{trigger.<bloco>.<campo>}}` (contexto do gatilho vence o fato na mesma chave).
+Eles continuam FORA de `{{trigger.data}}` e de `{{trigger}}` — fluxo já em produção não muda de conteúdo.
+
+Oferecidos no autocompletar (só quando o bloco Início tem o gatilho que os preenche):
+
+| Gatilhos do Início | Variáveis |
+|---|---|
+| `card_created`, `card_moved`, `card_won`, `card_lost`, `card_attribute_changed` | `{{trigger.kanban.title}}`, `{{trigger.kanban.funnel_name}}`, `{{trigger.kanban.stage_name}}`, `{{trigger.kanban.stage}}` (código da etapa) |
+| `card_moved` | `{{trigger.kanban.previous_stage_name}}`, `{{trigger.kanban.previous_stage}}` |
+| `card_won`, `card_lost` | `{{trigger.kanban.status}}` (`won`/`lost`) |
+| `label_added`, `label_removed` | `{{trigger.label.name}}` |
+| `assignee_changed` | `{{trigger.assignee.name}}` (vazio = responsável removido) |
+| `team_changed` | `{{trigger.team.name}}` (vazio = equipe removida) |
+| `sla_missed` | `{{trigger.sla.policy_name}}`, `{{trigger.sla.type}}` (`frt`/`nrt`/`rt`) |
+| `group_participant_joined`, `group_participant_left` | `{{trigger.group.name}}`, `{{trigger.group.id}}`, `{{trigger.participant.phone}}`, `{{trigger.participant.name}}` (16/09 — quem entrou/saiu; nome só se já é contato) |
+
+Resolvem mas NÃO aparecem no seletor (produtor único — só o gatilho daquela integração preenche):
+`{{trigger.attribute.name}}`/`current_value` (atributo do contato entrou no valor), `{{trigger.form.name}}`/
+`milestone`, `{{trigger.payment.gateway|event|product|offer|method|status|amount}}`,
+`{{trigger.eclinica.event|unit|date|time|compromisso|idagenda}}`, `{{trigger.lead.form|page|ad|adset|campaign|platform}}`
+(nome do anúncio, não dado de pessoa), `{{trigger.dtmf.key|campaign}}`, `{{trigger.reminder.date|time|compromisso|unit|days_before}}`,
+além de `{{trigger.kanban.id}}`/`funnel_id` (use `{{trigger.kanban_item_id}}`/`{{trigger.funnel_id}}`),
+`{{trigger.assignee.id}}`, `{{trigger.team.id}}`, `{{trigger.kanban.previous_status}}` e
+`{{trigger.group.participants_count}}`. As RESPOSTAS do lead do Meta não viram variável (só aparecem no
+histórico). Sessões anteriores a 22/08 não têm fatos gravados: essas variáveis saem vazias nelas.
+O bloco do card chama-se `kanban` — nunca `card`. Se o cliente precisar de um dado que não está aqui,
+use a variável de origem quando existir (`{{booking.*}}`, `{{form_*}}`, `{{contact.*}}`).
 
 **NÃO duplique o que já tem variável própria.** `{{contact.name}}`, `{{conversation.status}}`,
 `{{inbox.name}}` e os atributos `ctwa_*` continuam existindo e são a forma canônica. O `{{trigger.*}}`

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

@@ -597,7 +597,8 @@ Comuns a (quase) todas:
 | `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_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) |
+| `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) | — (sem variável de resposta) |
+| `send_private_message` | `groupPrivateTo` (obrig — telefone com código do país; aceita `{{trigger.participant.phone}}`) + `messageItems` — manda os balões no PRIVADO desse telefone. Quem nunca conversou ganha contato + conversa (dispara os ouvintes de conversa criada). 18ª operação (16/09), sem teto diário | — (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).
@@ -620,6 +621,13 @@ as outras duas seguem aplicadas. Não prometa essa permissão ao cliente sem con
 dígitos, aceita `1203...@g.us` ou só o número). Quando alguém entra, o `send_message` seguinte cai **no próprio
 grupo** (o grupo é a conversa do flow).
 
+**Quem entrou (16/09):** o gatilho entrega `{{trigger.participant.phone}}` (telefone com `+`) e
+`{{trigger.participant.name}}` (só quando a pessoa já é contato). Para falar **no privado** de quem entrou, use no
+flow de grupo um `update_group` com `groupOperation: "send_private_message"` e `groupPrivateTo:
+"{{trigger.participant.phone}}"`. **Não use flow individual para isso:** ele só roda para quem JÁ tem conversa
+naquela caixa — quem entra pela primeira vez (link de convite) é pulado. Limite conhecido: o flow de grupo atende
+uma entrada por vez; quem entrar enquanto os balões da pessoa anterior saem não recebe (prefira 1 balão).
+
 **Lembretes:**
 - **Teto de 20 participantes por execução** (`add_participants`/`create`) — trava ANTI-BANIMENTO, não performance.
   Adicionar em lote é o que mais rápido derruba número no WhatsApp não-oficial.