@lionchat/mcp-server 1.21.0 → 1.23.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,210 @@
+# 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`.
+
+Marcar Compareceu/Faltou também **não conclui a tarefa**: ela segue `pending` (e contando nas
+pendências) até alguém concluir. É de propósito — concluir um compromisso de Booking encerra os lembretes
+e as mensagens pós-atendimento dele e dispara o gatilho de fluxo "agendamento concluído". **Nunca conclua
+a tarefa só porque a presença foi marcada.**
+
+Para responder "o que aconteceu com este compromisso?" use o campo **`selo`** da tarefa (17/09), que já
+junta os dois eixos e a remarcação: `cancelled` > `no_show` / `attended` > `completed` > `snoozed` >
+`rescheduled` > `pending`. É o mesmo rótulo que o painel mostra ao lado da tarefa (Faltou, Compareceu,
+Remarcada...). É só de leitura.
+
+### Responsável de compromisso de Booking é FIXO
+
+O compromisso marcado por um tipo de evento (Booking) cai SEMPRE na agenda do profissional configurado
+nele. Na criação, `assignee_ids` nunca valeu; desde 17/09 também é **ignorado na edição**
+(`lionchat_tasks_update` / `_update_1`): a resposta é 200, o resto da edição vale e o responsável continua
+o mesmo. Para mudar quem atende, altere o profissional do tipo de evento (`booking_event_types_update`).
+
+### Ver como está o dia antes de marcar
+
+`lionchat_agent_availability_day` (17/09) devolve UM dia de até 6 pessoas: o expediente de cada uma e os
+intervalos já ocupados, em "HH:MM" do fuso pedido. O intervalo ocupado de qualquer pessoa da conta vem
+sempre (é o que permite marcar com um colega); o título do compromisso só vem para quem já o veria no
+calendário, e compromisso privado de outra pessoa nunca vem com título. Para Booking, os horários válidos
+continuam sendo os de `booking_event_types_slots` — essa ferramenta é para compromisso COMUM.
+
+---
+
+## 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

@@ -397,7 +397,9 @@ oficial, com WABA) sai pra Meta como evento de MENSAGEM (`action_source: busines
 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:** `lionchat_inboxes_capi_dataset_link` (POST `/inboxes/{id}/capi_dataset`).
+- **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`.
@@ -922,3 +924,30 @@ 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).
+
+## Entrar num grupo por convite (17/09/2026)
+
+Só em caixa de WhatsApp QR Code (`Channel::Waha`). São DUAS tools e a ordem importa.
+
+1. `lionchat_inboxes_waha_groups_list_3` (join_info) — SÓ LEITURA: diz qual é o grupo (`Name`,
+   `ParticipantCount`, `IsJoinApprovalRequired`). **Chame sempre primeiro** e confirme com a pessoa
+   em qual grupo ela vai entrar. Entrar é ação que muda o WhatsApp do cliente.
+2. `lionchat_inboxes_waha_groups_create_6` (join) — entra, como participante comum.
+
+As duas aceitam o código cru, o link inteiro (`https://chat.whatsapp.com/CODIGO`) ou um texto com o
+link no meio — não precisa extrair o código antes.
+
+**Recusa esperada:** 422 com `reason: groups_disabled` quando a caixa está com "Aceitar grupos"
+desligado. Não insista nem tente contornar: sem essa chave o WhatsApp nem entrega as mensagens do
+grupo, então o número entraria num grupo que nunca apareceria no painel. O caminho é o cliente ligar
+a opção nas configurações da caixa e tentar de novo.
+
+A resposta do join_info vem no formato cru do motor, em PascalCase (`Name`, não `name`).

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.

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.
@@ -384,7 +404,31 @@ 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)
-└── assignees (has_many → User, via account_task_assignments)
+├── 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)
+├── selo (SÓ LEITURA, calculado — 17/09): o rótulo ÚNICO que a tela mostra ao lado da tarefa, juntando
+│   `status` + `attendance` + remarcação: cancelled > no_show / attended > completed > snoozed >
+│   rescheduled > pending. `rescheduled` = data trocada pelo painel/fluxo/IA (`reschedule_source`) OU pelo
+│   cliente no link do agendamento. Para dizer "o que aconteceu com este compromisso", LEIA `selo` —
+│   `status: pending` sozinho NÃO significa "nada aconteceu" (a pessoa pode ter faltado)
+├── 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). Compromisso NASCIDO DE BOOKING
+    (`booking_id` presente) tem responsável FIXO = o agente configurado no tipo de evento:
+    `assignee_ids` enviado no update é IGNORADO (200, o resto da edição vale — 17/09)
+
+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)
@@ -397,6 +441,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
@@ -567,6 +613,21 @@ da consulta) — em vez de herdar sempre o horário da consulta. Há ainda um fi
 ("Só quando") por atributo `eclinica_*` do contato. Nada disso é editável pelo MCP: só pelo painel.
 Pra auditar o que foi/será disparado, use `lionchat_eclinica_reminder_history_list`.
 
+**Um aviso por CONSULTA (desde 2026-09-17).** A regra antiga "um lembrete por dia" saiu: paciente com duas
+consultas no mesmo dia — ou duas pessoas no mesmo celular (mãe e filho) — recebe um lembrete para CADA
+consulta, cada um com o seu nome, horário, profissional e link. Eles não saem juntos: sai o da consulta
+mais cedo e, ~10 minutos depois (na rodada seguinte), o da próxima. No histórico
+(`lionchat_eclinica_reminder_history_list`) isso aparece assim: o que espera a vez fica `pending` com
+`fire_at` no passado por alguns minutos (normal); `skip_reason = outra_consulta_no_mesmo_dia` só existe em
+linhas ANTIGAS (até 17/09); e `fail_reason = fluxo_ainda_em_andamento_com_este_contato` significa que o
+fluxo do aviso anterior ainda estava em andamento com aquele contato (típico de fluxo que aguarda o
+paciente clicar num botão) — pode ser reenviado com `lionchat_eclinica_reminder_history_reprocess`.
+O fluxo do lembrete recebe também `{{cliente_id}}` (código do paciente DAQUELA consulta na e-Clínica) e
+`{{agendatipo}}`; na automação, `{{agendamento.cliente_id}}` e `{{agendamento.agendatipo}}`. Ao consultar a
+agenda do paciente dentro do fluxo, use `{{cliente_id}}` do lembrete — a ficha do contato é uma por
+TELEFONE e guarda só o último paciente. Quem quiser "só um lembrete por dia" monta no próprio fluxo
+(condição num atributo da conversa com `{{data_consulta}}` + ação que grava o dia depois de enviar).
+
 ## Relatórios e Métricas
 
 ```
@@ -767,7 +828,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

@@ -288,7 +288,7 @@ No editor visual esses destinos só aparecem quando a validação bate (computed
 - `validation: 'options'` → `option_<valor>` para cada valor em `acceptedOptions` (ex: `option_1`, `option_2`, `option_sim`) + `timeout` + `retries_exhausted`
 - `validation: 'varied_options'` → `option_<group_id>` para cada grupo em `optionGroups` (ex: `option_sim`, `option_nao`) + `timeout` + `retries_exhausted`
 
-**`timeout` vs `retries_exhausted` (DISTINTOS):** `timeout` = cliente ficou em silencio (estourou `waitTime`). `retries_exhausted` = cliente respondeu, mas errou a validacao mais que `maxRetries` vezes. Ligue cada um ao caminho desejado. Se `retries_exhausted` nao tiver edge, ha fallback p/ o edge de `timeout`; sem nenhum dos dois, o flow encerra ao esgotar as tentativas.
+**`timeout` vs `retries_exhausted` (DISTINTOS):** `timeout` = cliente ficou em silencio (estourou `waitTime`). `retries_exhausted` = cliente respondeu, mas errou a validacao mais que `maxRetries` vezes (`maxRetries` = quantas vezes a `invalidMessage` e enviada; a resposta errada seguinte esgota — com `maxRetries: 1` o cliente recebe o erro uma vez e sai no 2o erro). Ligue cada um ao caminho desejado. Se `retries_exhausted` nao tiver edge, ha fallback p/ o edge de `timeout`; sem nenhum dos dois, o flow encerra ao esgotar as tentativas.
 
 **Timeout dispara de verdade — e SEM fio ENCERRA (desde 20/08/2026):** `waitTime` + `waitUnit`
 agendam o estouro. Com fio no handle `timeout`, o flow segue por ele. **Sem fio, a sessão é
@@ -385,6 +385,25 @@ só pra destravar, ela pode sair.
 | `pagetrack_visited` / `pagetrack_event` | LionTrack |
 | `sla_check` | status do SLA da conversa (usa `value` = código fixo; ver abaixo) |
 
+**CAIXA DA CONVERSA e TIPO DE CAIXA (novo 17/09/2026):** duas condições da aba Conversas que perguntam
+ONDE a conversa está. Nasceram para o **Fluxo de Ações** (que roda em qualquer caixa), mas valem em
+qualquer tipo de flow. Não têm operador novo: só `equal` e `not_equal`, e o valor vai numa **LISTA**
+(`values`) — com lista, `equal` significa "é ALGUMA destas" e `not_equal` "não é NENHUMA destas".
+
+- **Caixa da conversa:** `{ "id": 1, "field": "{{inbox.id}}", "operator": "equal", "value": "", "values": ["342", "204"], "valueType": "inbox" }`
+  — cada item de `values` é o **id da caixa como STRING**.
+- **Tipo de caixa:** `{ "id": 1, "field": "{{inbox.channel_type}}", "operator": "equal", "value": "", "values": ["Channel::Waha"], "valueType": "channel_type" }`
+  — cada item é o **nome técnico do canal**: `Channel::Waha` (WhatsApp QR Code), `Channel::Whatsapp`
+  (WhatsApp API Oficial), `Channel::WebWidget`, `Channel::Api`, `Channel::Email`,
+  `Channel::FacebookPage` (Facebook/Instagram), `Channel::TwilioSms`, `Channel::Sms`,
+  `Channel::Telegram`, `Channel::Line`.
+
+O `valueType` é OBRIGATÓRIO nas duas: é ele que faz a tela abrir o seletor certo (lista de caixas /
+lista de tipos). Sem ele a regra roda no motor e a tela não desenha campo nenhum para ela. Gravar o
+valor em `value` em vez de `values` é a mesma família do defeito de 02/09 descrito abaixo: o motor
+compara certo e a tela abre o seletor VAZIO. `{{inbox.name}}` existe como variável mas **não** é
+condição: comparar por nome quebra quando o cliente renomeia a caixa.
+
 > **ATENÇÃO — onde o VALOR vai (defeito real de 02/09/2026, conta 137):** no nó **Condição**, uma regra de atributo
 > (`valueType: "attr_config"`) com operador `equal`, `not_equal`, `contains` ou `not_contains` guarda o valor em
 > **`values: ["..."]` (lista)** e deixa `value: ""`. A TELA lê SÓ a lista: regra gravada com `value: "paid_ad"` e
@@ -531,6 +550,7 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 | `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; `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 |
@@ -843,7 +863,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
@@ -852,6 +872,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
@@ -1020,17 +1044,43 @@ de conexão e viram bola de neve visual. Ao gerar `position`:
 
 ---
 
-## 2-B. Dois tipos de flow: `conversation` vs `ai_tool`
+## 2-B. Três tipos de flow: `conversation`, `ai_tool` e `action`
 
 O campo `flow_type` (definido na criação, IMUTÁVEL depois) decide a natureza do flow:
 
-| | `conversation` (default) | `ai_tool` |
-|---|---|---|
-| Como dispara | Por evento de inbox (trigger no node `start`) | Invocado pelo AI Agente (Captain) como ferramenta |
-| Inboxes | usa `inbox_ids` | **PROIBIDO** ter inboxes (validação barra) |
-| 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` |
+| | `conversation` (default) | `ai_tool` | `action` (17/09/2026) |
+|---|---|---|---|
+| Como dispara | Por evento de inbox (trigger no node `start`) | Invocado pelo AI Agente (Captain) como ferramenta | Pelo MESMO trigger do `conversation`, mas em QUALQUER inbox |
+| Inboxes | usa `inbox_ids` | **PROIBIDO** ter inboxes (validação barra) | **PROIBIDO** ter inboxes (roda em todas) |
+| 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` | **não manda mensagem nenhuma** |
+| Nodes permitidos | todos | `start`, `end`, `api`, `condition`, `set_variable`, `ai`, `note`, `randomizer`, `action`, `send_message` | todos MENOS `send_message`, `wait_response`, `update_group` e `end` |
+
+**`action` (na tela: "Fluxo de Ações")** é para regra que vale na empresa inteira e não depende da
+caixa: "conversa que receber a etiqueta urgente vai pra equipe de suporte", "card que entrar na
+etapa Fechado grava a data no contato". Antes exigia repetir o mesmo flow em cada inbox.
+
+Criar: `flows_create` com `flow_type: 'action'`, SEM `inbox_ids` e SEM `conversation_mode`
+(o backend fixa `individual`; mandar `group` é ignorado). Aceita os MESMOS gatilhos do
+`conversation` no node `start` e usa o mesmo `flow_data`. Roda LADO A LADO com os flows de mensagem
+(não entra no aviso de conflito de gatilho) e vale também em conversa de grupo.
+
+**NUNCA** pôr `send_message` / `wait_response` / `update_group` num flow `action` — a validação
+recusa o save inteiro com `contains node types not allowed in action flow`. Se o cliente precisa
+falar com a pessoa, o flow é `conversation`.
+
+Três regras que andam com o tipo `action` (17/09/2026):
+- **`start_flow` (bloco Ações > Sistema)**: o flow de ações pode ser alvo a partir de QUALQUER flow,
+  sem casar caixa. Já um flow `conversation` alvo que NÃO atenda a caixa da conversa é RECUSADO em
+  runtime (passo com erro `inbox_mismatch` no histórico) — antes rodava no lugar errado em silêncio.
+- **Macro**: a ação `start_flow` da macro (`macros_*`) aceita **só** `flow_type: 'action'`.
+- **Condições**: `{{inbox.id}}` e `{{inbox.channel_type}}` (novo) dão "Caixa da conversa" e "Tipo de
+  caixa" na aba Conversas — como o flow de ações roda em todas as caixas, é assim que ele pergunta
+  onde está antes de agir. `channel_type` grava o valor técnico (`Channel::Waha` etc.).
+- **AINDA NÃO FUNCIONA**: disparar flow `action` por webhook de integração (gateways de pagamento,
+  Webhook Universal, Meta Lead, e-Clínica) ou por gatilho de formulário. Esses caminhos criam a
+  conversa usando a CAIXA do flow, e o flow de ações não tem caixa — ele é selecionado e descartado
+  (`no_inbox_linked` no log). Não prometa isso ao cliente até a decisão de produto.
 | 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`.
@@ -1050,10 +1100,11 @@ no fim de uma cadeia automação→flow→automação, suspeite desse limite —
 
 Todo flow `conversation` tem um `conversation_mode`: `individual` (default — conversa 1-a-1) ou `group`
 (grupo de WhatsApp). Definido na CRIAÇÃO e **IMUTÁVEL depois** (não dá pra converter um no outro; pra trocar,
-crie outro flow). Não confundir com `flow_type` — um flow `ai_tool` não tem `conversation_mode`.
+crie outro flow). Não confundir com `flow_type` — um flow `ai_tool` não tem `conversation_mode`, e no
+`action` ele é fixado em `individual` (o campo não se aplica: o flow de ações roda nos dois).
 
-Na tela o usuário vê isso como TRÊS opções ao criar: "Mensagem" (= `conversation` + `individual`),
-"Grupo" (= `conversation` + `group`) e "IA Agente" (= `ai_tool`).
+Na tela o usuário escolhe o TIPO (Conversa / IA Agente / Ações) e, só no tipo Conversa, o modo
+(Mensagens individuais / Grupos WhatsApp).
 
 **A diferença entre individual e grupo é quais nodes/abas ficam disponíveis:**
 
@@ -1156,7 +1207,7 @@ Oferecidos no autocompletar (só quando o bloco Início tem o gatilho que os pre
 | `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}}` |
+| `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}}`/

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.

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

@@ -232,8 +232,10 @@ renderiza e não dá erro.
 - **Lista de recusa no servidor** (o valor é pulado de forma visível, sem erro): `name`, `email`,
   `phone_number`, `identifier`, `card` e chaves começando com `captain_`, `eclinica_`, `origin_`,
   `lt_`, `booking_`, `waha_`, `whatsapp_`, `ctwa_`, `meta_lead_`.
-- Contato pré-existente recebe valor **só em campo vazio** — exceto o que ESTA resposta gravou e
-  ninguém mudou depois (correção via Voltar).
+- Contato pré-existente: **dado novo vence** (regra de 11/09) — nome, e-mail, documentos e atributos
+  são sobrescritos por resposta nova (mesmo valor não regrava). Só o **telefone** fica protegido
+  (endereço da conversa): preenche vazio ou corrige o que a própria resposta gravou. O que cada
+  resposta gravou fica em `written_attributes` (detalhe da resposta).
 
 **`options`** (do `choice`): `[{ "id": "abc123", "label": "Sim", "image": "" }]`.
 

package/dist/docs/resources/glossary.md

@@ -449,7 +449,7 @@ Campos MUTÁVEIS (atualizáveis livremente por IA/integração): `marital_status
 | **LionCalls** | Voz pelo WhatsApp em caixa **QR Code**, mas pelo **motor próprio do LionChat** (credencial global, 1 sessão por caixa; flag `lioncalls_calling`, nasce desligada e é ligada conta a conta) | **NENHUMA — sem tool no MCP** | WhatsApp QR Code |
 | **WhatsApp Calling (Cloud)** | Voz pelo WhatsApp na **API oficial** (enterprise) | `whatsapp_calls_*` + enable/disable_whatsapp_calling | WhatsApp oficial |
 | **VoIP (Zenvia)** | Telefonia COMUM com softphone no navegador (ramais, ligações) | `voip_*` | Telefone |
-| **VTCall** | Telefonia por **PABX click-to-call**, config por conta + ramal por atendente; **sem softphone no navegador** — o atendente fala pelo app/ramal do VTCall | `vtcall_settings_*` (show/update/test_connection), `vtcall_ramals_*` (list/create/destroy) | Telefone (PABX do cliente) |
+| **VTCall** | Telefonia por **PABX click-to-call**, config por conta + ramal por atendente; **sem softphone no navegador** — o atendente fala pelo app/ramal do VTCall; desde 11/09/2026 a ligação discada direto no aparelho (ramal cadastrado) também entra no histórico | `vtcall_settings_*` (show/update/test_connection), `vtcall_ramals_*` (list/create/destroy) | Telefone (PABX do cliente) |
 
 Quando o usuário falar "ligação", descubra o canal ANTES de responder: caixa QR Code → **LionCalls**;
 caixa oficial → `whatsapp_calls`; telefone/ramal → Zenvia (softphone) ou VTCall (PABX).
@@ -503,7 +503,8 @@ cards daquele funil).
   pelo botão de WhatsApp de um anúncio (conversa com `ctwa_clid` numa caixa oficial). A Meta só
   aceita 14 nomes nele (`LeadSubmitted`, `QualifiedLead`, `ViewContent`, `AddToCart`, `InitiateCheckout`, `Purchase`, `OrderCreated`, `OrderShipped`, `OrderDelivered`, `OrderCanceled`, `OrderReturned`, `CartAbandoned`, `RatingProvided`, `ReviewProvided`) e só num dataset vinculado à WABA.
 - **Dataset da WABA** (`provider_config.capi_dataset_id` da caixa oficial): destino desses eventos,
-  criado/recuperado pelo botão "Vincular à Meta" (`lionchat_inboxes_capi_dataset_link`) com a chave da
+  criado/recuperado AUTOMATICAMENTE (na criação da caixa e por varredura a cada 10 min) e, como plano B,
+  pelo botão "Vincular à Meta" (`lionchat_inboxes_capi_dataset_link`) com a chave da
   própria caixa. Um por conta do WhatsApp Business; vale para todos os números dela.
 - **`messaging_name` / `messaging_event_names.meta` / `messaging_event_name`**: a escolha do evento de
   WhatsApp (funil / fluxo / disparo manual). Tri-estado: ausente = automático, `''` = não enviar como
@@ -600,6 +601,17 @@ conversa). Quem atendeu voltou a aparecer nas recebidas. Se o cliente diz que o
 funciona numa ligação de hoje, o mais provável é que o arquivo permanente ainda não exista — a
 reconferência resolve sozinha dentro de 36h.
 
+## Ligação feita direto no aparelho do VTCall (11/09/2026)
+
+Antes, só a ligação iniciada pelo botão Ligar do LionChat entrava no histórico e na coluna "Feitas" do bloco de
+ligações. Agora a ligação que o atendente disca direto no aparelho ou no app do VTCall também entra, desde que o ramal
+esteja cadastrado (`vtcall_ramals_*`). Ela aparece em `voip_calls_list` com `direction: "outbound"`, protocolo `LIG-...`
+(o do botão continua `AAMMDD-NNN`) e sem caixa. O card na conversa sai sem autor, com o nome do atendente.
+
+Cuidado ao ler "Feitas atendidas": pelo botão a central marca atendida sempre (é a perna em que o atendente atende o
+próprio ramal); pelo aparelho, só quando o cliente atende. Não compare as duas taxas como se medissem a mesma coisa.
+Ramal sem cadastro não gera registro — se o cliente diz que "liguei e não apareceu", confira os ramais primeiro.
+
 ## Assinatura eletrônica de contratos (04/09)
 
 ### `status` do contrato (`signature_envelopes`)