@lionchat/mcp-server 1.10.1 → 1.10.3

package/dist/docs/instructions.md

@@ -90,6 +90,25 @@ daquela caixa, mas fica FORA da distribuição automática (round-robin nunca at
 caixas das quais participa — exceção é estar atribuído a um card, que libera só aquela conversa (ver
 `lionchat://docs/kanban-deep-dive`).
 
+### Supervisor de time (TeamMember.auto_assignable) — novo 2026-07-30
+
+O TIME passou a ter os MESMOS dois papéis da caixa. Supervisor de time é membro pra TUDO — menção ao
+time, e-mail de automação, acesso ao funil do Kanban, relatório, contagem e atribuição MANUAL — mas
+fica FORA da distribuição automática do time (nem conversa, nem rodízio de card do funil).
+
+- Flag: `team_members.auto_assignable` (`false` = supervisor, `true` = agente). A coluna nasce `true`:
+  todo vínculo anterior a 30/07 é Agente.
+- Tools: `lionchat_team_members_create` / `_update`. **O contrato é DIFERENTE do da caixa, de
+  propósito:** aqui `user_ids[]` é a lista COMPLETA de membros e `supervisor_ids[]` é um SUBCONJUNTO
+  dela. Chave `supervisor_ids` **ausente = não mexe em papel nenhum** (só entra/sai membro) — assim um
+  cliente antigo que só manda `user_ids` não zera em silêncio os supervisores marcados na tela.
+- `lionchat_team_members_list` traz `is_supervisor` por agente.
+
+**As duas marcas são INDEPENDENTES (decisão do dono 30/07):** a da caixa protege da distribuição da
+CAIXA; a do time protege da distribuição do TIME. Supervisor de caixa que é agente de um time
+CONTINUA recebendo conversa por aquele time — é intencional, não é defeito. Nunca diga ao cliente que
+marcar supervisor num lugar protege no outro.
+
 ## 3. Convenções da API
 
 ### Datas
@@ -302,6 +321,7 @@ e pular evita que ela receba tudo em dobro. Quem está sendo atendido pela equip
 | Rate limit leitura | 1200/min por token |
 | Rate limit escrita | 600/min por token |
 | Loop detection | bloqueia chamada idêntica >10x em 10s |
+| Variável de Conta — tamanho do valor | 32 KB por variável (novo 01/08/2026; passou disso = HTTP 422 na conta). Vale só pra variável DECLARADA na tela; chave interna do sistema não é barrada. É por variável, não pela soma — conta com dezenas de tokens legítimos não é punida |
 
 Exceção ao teto de 300: em ação em massa de **contatos** com `select_all: true` (agir sobre todos os
 contatos do filtro) não há teto de IDs — o servidor refaz o filtro e processa em lotes no fundo. O
@@ -352,6 +372,12 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 | **Importar histórico** de caixa WhatsApp Cloud (QR) | `lionchat_inboxes_whatsapp_history_start` / `_status` / `_cancel` | Admin-only + flag `qr_history_import`; só caixa oficial. Acompanhe `state` no `_status` |
 | Ver / limpar **falhas de envio** de uma caixa | `lionchat_inboxes_failed_messages_summary` primeiro; depois `_bulk_retry` (reenviar) ou `_bulk_cancel` (descartar) | Admin-only. Reenvio em massa e cancelamento em massa são ações irreversíveis: mostre as contagens do summary e confirme (seção 7a/7b). Numa mensagem só: `lionchat_conversations_messages_create_1` (reenviar) / `lionchat_conversations_messages_cancel_retry` (cancelar) |
 | **Definir supervisor** de caixa | `lionchat_inbox_members_create` / `_update` com `supervisor_ids[]` | Supervisor vê TUDO da caixa mas fica fora do rodízio (ver abaixo) |
+| **Definir supervisor** de time | `lionchat_team_members_create` / `_update` com `supervisor_ids[]` | Contrato diferente do da caixa: `user_ids[]` é a lista COMPLETA e `supervisor_ids[]` um subconjunto dela. Omitir `supervisor_ids` não mexe em papel nenhum (seção 2) |
+| **Mudar a fila do time** (teto por atendente, janela, online/offline) | `lionchat_teams_update` (`assignment_mode`, `fair_distribution_limit`, `fair_distribution_window`) | Time tem PREFERÊNCIA sobre a caixa na distribuição. Leia a config atual antes de mudar (ver `lionchat://docs/conversation-flows`) |
+| **Criar/atualizar time** | `lionchat_teams_create` / `_update` | **Preencha `description`**: desde 03/08 é ela que o AI Agente lê pra decidir o roteamento por time. Descreva QUANDO mandar pra lá, não o que o time é |
+| **Pausar a automação no meio** (esperar atribuição/card antes da próxima ação) | ação `wait` em `lionchat_automation_rules_create` / `_update` | Segundos, teto 300. Acima disso é caso de FlowBuilder. Ver `lionchat://docs/conversation-flows` |
+| **Buscar contato/conversa/card** | `lionchat_search_*`, `lionchat_contacts_search` | **Termo com letra exige 3+ caracteres** (dígito é isento). Menos que isso volta VAZIO sem erro — não conclua que o registro não existe. Ver `lionchat://docs/api-conventions` |
+| **Migrar conversas** de uma caixa WhatsApp pra outra (ex.: QR Code → Oficial) | `lionchat_inboxes_inbox_migration_list` (prévia) → `_execute` → acompanhar status | Admin-only e IRREVERSÍVEL: sempre mostre os números da prévia e confirme (seção 7a). Grupos não vão pro canal oficial — ficam na caixa de origem |
 | Qualquer coisa de Ligação WP (Wavoip) | **NÃO HÁ TOOL** — removidas em 2026-07-16 por decisão do dono | Ligação WP é contratada e configurada **manualmente pelo cliente no painel**. O MCP não conecta, não desconecta, não entrega token de discagem nem muda config. Oriente o usuário a fazer pelo painel (Configurações da caixa → Ligação WP). |
 | 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 |
 | Configurar o Copiloto (modelo/temperatura/prompt base) | `lionchat_copilot_settings_update` | admin-only; copiloto tem motor próprio (padrão temp 0.3) |

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

@@ -379,6 +379,29 @@ falha silenciosa, sem erro na tela. Conversa se altera por `fields` (+ `labels:
 **Multi-termo com E:** `q` aceita String (espaços = AND implícito) ou Array (`q[]=joao&q[]=silva`),
 cap de 5 termos — cada termo precisa bater (cada um mantém seu OR entre campos).
 
+**PISO DE 3 LETRAS (novo 2026-08-04) — leia antes de concluir "não existe".**
+
+Termo com LETRA precisa de **3 caracteres ou mais**. Termo **só de dígitos** é isento (é assim
+que se busca pelo número da conversa ou do card, e conta nova tem todos com 1-2 dígitos).
+
+| Busca | O que acontece |
+|---|---|
+| `q=Bo` | Devolve **vazio**. Não é erro, não é 422 — vem `payload: []` |
+| `q=Bor` | Busca normal |
+| `q=42` | Busca normal (só dígitos, isento) |
+| `q=jo silva` | Vale: basta **um** termo utilizável na frase |
+| `q=zq` + `contact_filters=[...]` | Vazio. O termo curto **invalida a busca inteira**, mesmo com filtro junto |
+
+Vale nas CINCO buscas (contato, conversa, mensagem, card e artigo).
+
+**Consequência prática:** resultado vazio com termo de 1-2 letras **não significa que o registro
+não existe** — significa que a busca não rodou. Nunca responda "não encontrei esse contato" nessa
+situação. Ou complete o termo, ou pergunte o nome inteiro, ou use `/contacts/filter` com
+`filter_operator: "contains"`, que não tem esse piso.
+
+Sem `q` e só com filtros estruturados continua funcionando normalmente (contrato antigo, busca só
+por condições) — o piso só descarta termo de texto curto, não o pedido inteiro.
+
 **Busca cadastral:** CPF/CNPJ/RG/endereço/profissão entram na busca de contatos e conversas, com
 match por dígitos que ignora pontuação (`31.104.475/0001-51` == `31104475000151`; mín 3 dígitos).
 Telefone idem. Cards do Kanban são achados pelo contato/conversa vinculados.

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

@@ -131,6 +131,32 @@ Pra reativar: `paused=false`. Toggle é auditado (`audited only: [:paused]`).
 
 O `config` DEVE ser enviado como **objeto** (ex.: `config: { disabled_tools: [...] }`), NUNCA como string/texto. Se vier em formato errado, o backend retorna **422** (não salva ignorando em silêncio). O update do `config` é **merge parcial** — mandar só o subset que muda (ex.: só `disabled_tools`) preserva os demais campos.
 
+## AI Agente roteando por TIME (novo 2026-08-03)
+
+O AI Agente ganhou 3 ferramentas de time: **Listar Times**, **Mover para Time** e **Tirar do Time**.
+Antes ele só conseguia atribuir uma PESSOA; trocar de time exigia automação ou bloco de fluxo, com
+o time escolhido de antemão por quem montou a regra.
+
+**A descrição do time virou peça funcional.** É lendo `teams.description` que a IA decide para onde
+mandar a conversa. Time sem descrição obriga a chumbar o nome no cenário — que é justamente o que
+essas ferramentas vieram resolver.
+
+> **Ao criar ou atualizar time (`lionchat_teams_create` / `_update`), preencha `description`
+> dizendo QUANDO mandar para lá.** Ex.: `"Financeiro — cobrança, boleto, nota fiscal, reembolso,
+> segunda via"`. Não é enfeite de tela: é o que a IA lê.
+
+Travas que valem conhecer (não dá pra desligar):
+
+| Trava | Efeito |
+|---|---|
+| Conta sem nenhum time | As 3 ferramentas nem aparecem para o agente |
+| Alguém está atendendo (`assignee_id` preenchido) | Mover e Tirar **não agem**. Evita a IA arrancar a conversa da mão do atendente |
+| Nome do time no cenário | Resolve por nome exato; não achando, tenta CONTÉM. Se der mais de um candidato, devolve a lista e **não adivinha** |
+| Mover de time | **Não** faz handoff sozinho. Se a intenção é o humano assumir, o cenário precisa mandar chamar o handoff no mesmo turno |
+
+`list_teams` é ferramenta de descoberta: fica escondida da tela de ferramentas e só carrega se
+"Mover para Time" estiver ativa. Não tente ligá-la ou desligá-la sozinha em `config.disabled_tools`.
+
 ## Limite do prompt e cache OpenAI (2026-05-22)
 
 - `config.instructions` (system prompt do agente) aceita até **20.000 caracteres** (antes 10k). Acima de 15k, o frontend mostra aviso "lost in the middle" — prefira colocar instruções críticas no início ou final.
@@ -247,6 +273,24 @@ pula o follow-up). Tipos:
   (não empurra pra frente — evita disparo em massa na abertura); a cadência segue nos passos seguintes.
   `start == end` = janela inválida (ignorada). Ideal pra não incomodar cliente de madrugada.
 
+## Follow-up fora da janela de 24h usa TEMPLATE (novo 2026-07-30)
+
+Em caixa **WhatsApp oficial**, passadas 24h da última mensagem do cliente, a Meta recusa qualquer texto
+escrito pela IA. Até 30/07 o follow-up nem perguntava: escrevia, o canal recusava e sobrava um balão
+vermelho com o erro enganoso "Template not found or invalid template name" (392 balões assim num único
+dia numa conta). Agora o gerador de follow-up recebe os modelos aprovados da caixa ANTES de escrever e
+escolhe um deles quando a janela está fechada.
+
+O que isso significa na prática, pra explicar ao cliente:
+- **Conta em caixa oficial que quer follow-up depois de 24h PRECISA ter template aprovado na Meta.**
+  Sem nenhum template, não há como falar fora da janela — não é limitação da plataforma, é regra da Meta.
+- **Mandar template não reabre a janela.** Só a resposta do cliente reabre. Um follow-up por template
+  pode ser respondido — e é a resposta dele que libera texto livre de novo.
+- **Trava anti-repetição:** modelo já enviado naquele ciclo de follow-up sai da lista. Numa conta com um
+  único template (normalmente o mesmo da campanha), sem essa trava o cliente receberia minutos depois o
+  mesmo texto que acabou de ler.
+- Dentro da janela nada muda: o follow-up continua sendo texto livre, escrito pela IA.
+
 ## Desligar a IA quando um humano assume (2026-07)
 
 `config.feature_pause_on_human_reply` (bool, padrão false). Ligado, a IA **se desliga sozinha** na
@@ -379,6 +423,17 @@ o `exclusion` (e o `audience_mode`) vão TOP-LEVEL; ao CRIAR/EDITAR a campanha e
 `{assignee_id, priority, labels}`: `contact_labels: []` (aplica etiqueta ao CONTATO que recebeu) e
 `attribute_changes: [{scope:'contact'|'conversation', key, value}]` (grava/sobrescreve atributo de quem recebeu).
 
+**Público por PLANILHA (novo 2026-07-31):** o painel passou a aceitar CSV/XLS como público do disparo,
+nas três abas de campanha. **Não existe tipo novo de público** — a importação marca os contatos da
+planilha com uma **etiqueta de contato** e/ou um **atributo de contato**, e a campanha usa os tipos que
+já existiam (`ContactLabel` / `ContactAttribute`).
+
+Ou seja: **dá pra reproduzir pela API.** Importe os contatos aplicando uma marca própria da lista (ex.:
+etiqueta `lista-black-friday`) e monte o `audience` com `{"type": "ContactLabel", "id": <id>}`. Se o
+cliente pedir "disparar pra essa planilha", esse é o caminho. A marcação em lote é feita em silêncio
+(sem callback nem evento), então importar uma lista grande **não acorda automação nem fluxo** — foi
+desenhada assim de propósito, pra não repetir a tempestade de eventos de 29/07.
+
 SEMPRE rode `campaigns_estimate_audience` com o MESMO audience + audience_mode + exclusion antes de
 criar a campanha e mostre a contagem ao usuário — estimativa e disparo usam o mesmo motor (não divergem).
 
@@ -399,6 +454,12 @@ Pra dados fixos que se repetem (slogans, endereços, horários):
 - Resolve em: mensagens, respostas prontas, campanhas e automações. NÃO resolve nas instruções do AI Agente (base/cenário) — ali só `contact.*` e `conversation.*`.
 - `secret` nunca aparece em template (sai vazio); só resolve em nós API Request do FlowBuilder.
 - Atualiza UMA vez, propaga pra todo lugar.
+- **Teto de 32 KB por variável (novo 01/08/2026).** Valor maior que isso é recusado com HTTP 422. É por
+  VARIÁVEL, não pela soma — conta com dezenas de tokens legítimos (uma delas tem 23 tokens de
+  integração) não é punida. A maior variável legítima medida na plataforma tem 348 bytes, então o teto
+  dá ~90x de folga: cabe qualquer token, URL, endereço ou texto de configuração; **não** cabe base de
+  dados, JSON gigante nem script. Se o cliente quiser guardar algo desse tamanho, o lugar é um arquivo
+  ou uma integração, não uma Variável de Conta.
 
 Nunca hard-code esses dados em respostas geradas.
 
@@ -467,6 +528,20 @@ opcional `variable_mapping` junto.
 - Só entram no mapping as que devem auto-preencher; as demais `{{N}}` continuam manuais.
 - O `variable_mapping` é salvo localmente (NÃO vai pra Meta) e usado no momento do envio.
 
+**Variável sem mapping tem preço (2026-08-04).** Placeholder que ninguém disse como preencher:
+
+1. **Tira o modelo do alcance do AI Agente.** Basta UMA variável sem mapping para o modelo inteiro
+   deixar de ser oferecido no follow-up automático fora da janela de 24h.
+2. **Faz o envio manual falhar** com o erro `#132000` da Meta (número de parâmetros não bate).
+
+Vale para os dois formatos de marcador: posicional (`{{1}}`) e nomeado (`{{nome_cliente}}`).
+
+> Ao registrar modelo por API, **mapeie todas as variáveis do corpo** — ou preencha na hora do envio
+> via `processed_params`. Modelo com variável órfã é modelo que a IA não usa e que o disparo derruba.
+
+Confira o que ficou de fora lendo o modelo com `lionchat_inboxes_whatsapp_templates_list` e
+comparando os `{{...}}` do texto do BODY com as chaves do `variable_mapping`.
+
 Exemplo — `{{1}}` vira o primeiro nome do contato:
 
 ```json

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

@@ -131,6 +131,42 @@ Regra prática:
 Quem entra no rodízio: só `inbox_members` com `auto_assignable: true` (supervisor de caixa fica de
 fora) e, se "distribuir para agentes offline" estiver desligado, só quem está online.
 
+### A fila do TIME tem preferência sobre a da caixa (novo 2026-07-31)
+
+Existe um TERCEIRO nível de distribuição, e ele vem ANTES dos dois de cima. A regra, por conversa:
+
+> **conversa está num time que distribui → manda o TIME (quem entra e qual o teto).
+> Senão → cai pra caixa/política, exatamente como antes.**
+
+Decisão do dono: **time tem preferência, caixa é reserva.** O time decide QUEM e QUANTO; a
+caixa/política continua decidindo a ORDEM da fila, as exclusões e a capacidade por atendente.
+
+Campos do time (tools `lionchat_teams_create` / `_update`):
+
+| Campo | O que faz | Padrão |
+|---|---|---|
+| `allow_auto_assign` | liga/desliga a distribuição do time | `true` |
+| `assignment_mode` | `online_only` (só quem está online) ou `include_offline` (todo mundo do time) | `online_only` |
+| `fair_distribution_limit` | teto de conversas por atendente na janela | `10` |
+| `fair_distribution_window` | tamanho da janela, **em segundos** | `600` |
+
+Quem entra no bolo do time: membros com `auto_assignable: true` (supervisor de time fica de fora)
+**que também sejam membros da caixa** — quem não é da caixa nunca entra, senão a conversa cairia com
+alguém que nem enxerga aquela caixa.
+
+Antes de 31/07 o time sorteava UMA vez, no instante em que a conversa caía nele; não achando ninguém
+disponível, desistia PARA SEMPRE e a conversa ficava aberta sem dono. Agora a mesma varredura que já
+existia para a caixa reprocessa a fila do time. Se o cliente reclamar de "conversas com time e sem
+dono" de antes dessa data, a causa é essa — e já está corrigida.
+
+**LEIA o valor do time antes de responder** — a resposta de `lionchat_teams_list` / `_show` traz os
+quatro campos. Como em toda configuração, nunca recite o padrão de fábrica como se fosse o que o
+cliente configurou: cite o número que a API devolveu.
+
+> Nota de compatibilidade: `fair_distribution_limit` e `fair_distribution_window` só passaram a sair
+> na resposta em **03/08/2026**. Se vierem ausentes, a instalação é anterior a essa data — nesse caso
+> não afirme o valor, mande conferir em Configurações → Times → editar o time.
+
 **LEIA o valor da conta antes de responder — NUNCA recite um número de cabeça.** Os valores reais
 vêm na resposta da API:
 - `has_assignment_policy` (resposta da caixa) diz QUAL dos dois caminhos vale ali. `true` = política
@@ -219,6 +255,33 @@ Conversa resolvida que recebe nova mensagem do cliente:
 - Default: cria NOVA conversa (mantém histórico)
 - Se locked: reabre a mesma conversa (`status` volta a 0)
 
+### 10. Criar conversa por API — REGRA NOVA (2026-08-04)
+
+**Nunca nasce conversa nova se o contato já tem uma ABERTA naquela caixa.** Vale para todo caminho
+iniciado por nós: `lionchat_conversations_create`, campanha, flow, booking, integração.
+
+| Situação do contato naquela caixa | O que `conversations_create` devolve |
+|---|---|
+| Tem conversa **aberta / pendente / adiada / silenciada** | A **conversa existente**, com o mesmo `id`. Não cria |
+| Só tem conversa **resolvida** | Cria conversa NOVA (invariante do produto: "fechou = abre nova") |
+| Caixa com `lock_to_single_conversation` LIGADO | **Sempre** a existente, mesmo resolvida — reabre |
+| Caixa de **e-mail** | Sempre cria nova (o assunto da thread vem da conversa; reusar mandaria o e-mail com o assunto velho) |
+
+**Como saber se reusou:** compare o `id` devolvido com o que você esperava. Vem HTTP 200 nos dois
+casos, sem aviso. Se precisa garantir conversa nova, feche a anterior antes
+(`conversations_toggle_status` para `resolved`).
+
+**O que é DESCARTADO no reuso** (a conversa já existe; o disparo não reescreve o estado dela):
+`status`, `snoozed_until`, `additional_attributes` e `assignee_id`. Se você precisa trocar o
+responsável, chame `conversations_update` depois — não adianta mandar junto na criação.
+
+**O que É aproveitado:** `custom_attributes` entram por merge, **sem sobrescrever chave que já tem
+valor**. A conversa mantém a origem com que nasceu e só ganha o que ainda não tinha.
+
+**Reuso não dispara `conversation_created`** — automação, gatilho de flow, webhook de saída,
+notificação e a Agenda não rodam. Se o seu fluxo depende de um desses, ele não vai acontecer
+quando houver reuso.
+
 ## Estado relacional
 
 ```
@@ -266,6 +329,41 @@ Conversation
 2. Tem SLA policy ativando state change?
 3. Veio de external API call?
 
+## Pesquisa de satisfação (CSAT) — vale em TODO canal (corrigido 2026-07-31)
+
+A pesquisa de satisfação é enviada **dentro da própria conversa** (modo `in_chat`) em **todos os
+canais** — WhatsApp, Telegram, Instagram, SMS, site. O backend sempre funcionou assim; era a TELA que
+só mostrava a configuração quando a caixa era WhatsApp, então de 01/04 a 31/07 quem usava outro canal
+via a aba quase vazia e herdava um texto padrão que não conseguia editar. Hoje a configuração aparece
+igual pra todos.
+
+Duas coisas pra não errar ao explicar:
+- **A regra de etiqueta (`survey_rules`) agora é respeitada de verdade.** Ela aparecia na tela e era
+  IGNORADA no envio — a pesquisa saía pra todo mundo. Se o cliente configurou "só enviar quando a
+  conversa tem a etiqueta X" antes de 31/07 e reclamou que ia pra todos, a causa era essa e já está
+  corrigida.
+- **Caixa que nunca teve a aba salva** pode continuar sem `csat_mode` gravado e cair no caminho antigo.
+  Se duas caixas iguais se comportarem diferente, mande abrir a aba de Pesquisa de Satisfação e salvar
+  uma vez.
+
+## Migrar conversas entre caixas de WhatsApp (2026-08-01)
+
+Serve pra quem está saindo do WhatsApp por QR Code e indo pro Oficial (ou trocando de número): leva as
+conversas e os contatos da caixa antiga pra nova. Tools: `lionchat_inboxes_inbox_migration_list`
+(prévia), `_execute` (executa) e o acompanhamento de status. **Admin-only e irreversível** — mostre os
+números da prévia e confirme antes.
+
+O que a prévia devolve (e o que ela conta): a contagem é de **CONVERSAS**, dividida em migráveis,
+conflitantes e não-migráveis; contato sem conversa é ignorado, e os baldes fecham com o total.
+
+**Regras que mudam o resultado — diga ao cliente ANTES de executar:**
+- **Grupos não vão pro canal Oficial.** A Meta não tem grupos: conversa de grupo (`@g.us`), lista de
+  transmissão e canal ficam na caixa de ORIGEM e aparecem contados como pulados. Não é falha.
+- QR Code → Oficial passou a funcionar de verdade em 01/08. Antes a migração falhava — em uma conta
+  gravou "0 migradas" por causa de um grupo, e na prática teria falhado em 100% dos contatos, porque o
+  formato de identificador do QR Code não estava sendo convertido. Se o cliente tentou migrar antes
+  dessa data e não deu certo, mande tentar de novo.
+
 ## Receitas de ação (qual tool usar pra cada coisa)
 
 ### ENVIAR MENSAGEM (`conversations_messages_create`)
@@ -563,10 +661,41 @@ Todos os formatos abaixo foram conferidos linha a linha em `app/services/action_
 | `add_note_to_kanban_item` | `[{"funnel_id": 31, "text": "texto da nota"}]` — a chave e **`text`**, nao `note` |
 | `set_kanban_item_status` | `[{"funnel_id": 31, "status": "won"}]` — `won`, `lost` ou `open`. Status fora disso e ignorado |
 | `start_kanban_item_timer` / `stop_kanban_item_timer` | `[{"funnel_id": 31}]` |
+| `wait` | `[30]` — segundos. Ver "Acao Aguardar" abaixo |
 
 **Acoes de Kanban:** todas precisam que a conversa ja tenha um card no funil informado. Sem card,
 a acao e pulada (fica so no log do servidor). Use `create_kanban_item` antes, na mesma regra.
 
+### Acao `wait` (Aguardar) — novo 2026-08-04
+
+Pausa a regra: as acoes **seguintes** so rodam depois do tempo passar. As anteriores ja rodaram.
+
+```json
+{ "action_name": "wait", "action_params": [30] }
+```
+
+| Regra | Detalhe |
+|---|---|
+| Unidade | **segundos** |
+| Teto | **300** (5 minutos). Valor maior e limitado a 300 em silencio, sem erro |
+| Formatos aceitos | `[30]`, `30`, `"30"` e `{"seconds": 30}` — todos funcionam |
+| Tempo invalido | `[]`, `[0]`, `[""]` ou ausente = **nao pausa**, a regra segue direto. Nao da erro |
+| Ultima acao da regra | Nao agenda nada (nao ha o que retomar depois) |
+| Pilula "Automacao X disparou" | So aparece na 1a rodada, nao se repete na volta |
+
+**Para que serve.** O caso que originou: a regra mandava a mensagem **antes** da politica de
+atribuicao carimbar o responsavel, entao a variavel com o nome do atendente saia vazia. Meio
+segundo de espera resolve. Use quando a acao seguinte depende de algo que outro processo ainda
+esta gravando (atribuicao, card recem-criado, atributo que outra regra vai escrever).
+
+**Precisa de mais de 5 minutos?** O lugar certo e o FlowBuilder, que tem espera em horas e sessao
+propria pra sustentar o estado. A automacao nao foi feita pra isso.
+
+**A regra nao "dorme":** ao encontrar a espera ela encerra a rodada e agenda a retomada. Varias
+conversas esperam ao mesmo tempo sem travar o atendimento. Na volta, o sistema confere se a regra
+ainda existe e esta ligada, se a conversa ainda existe e se a caixa nao foi excluida — se algo
+disso mudou, ele simplesmente nao retoma.
+
 Lista autoritativa de nomes validos: `AutomationRule#actions_attributes` no backend. Nome de acao
 fora dessa lista e recusado com 422 ao salvar — isso a API valida. O que ela **nao** valida e o
 conteudo do `action_params`. `apply_kanban_checklist_template` existe no motor mas **nao** e uma

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

@@ -412,14 +412,25 @@ Atributos de sistema no CONTATO (prefixo `eclinica_`, protegidos, usáveis como
 | `eclinica_idagenda` | text | ID do último agendamento |
 | `eclinica_data_consulta` | date | Data da consulta, ISO |
 | `eclinica_hora_consulta` | **time** | Hora da consulta 24h `"HH:MM"` (novo 2026-07-06) |
+| `eclinica_hora_final` | **time** | Hora final da consulta (novo 2026-07-27) |
 | `eclinica_status_agendamento` | text | agendado / no_show / atendido / desmarcado |
-| `eclinica_compromisso` | text | Tipo da consulta (ex: Consulta, Retorno, Exame) |
+| `eclinica_situacao` | text | Situação crua da agenda (age_situacao do webhook) |
+| `eclinica_compromisso` | text | Tipo da consulta — TEXTO LIVRE da recepção (ex: Consulta, Retorno) |
+| `eclinica_agendatipo` | text | Tipo de Agendamento — NOME da lista fixa do painel, resolvido por unidade (novo 2026-07-28). **Filtrar sempre pelo NOME, nunca pelo número: os números colidem entre filiais** |
+| `eclinica_agendatipo_id` | text | Tipo de Agendamento — número cru (não comparável entre filiais) |
+| `eclinica_profissional` | text | NOME do profissional, resolvido por unidade (novo 2026-07-10) |
+| `eclinica_profissional_id` | text | Número do profissional (não comparável entre filiais) |
+| `eclinica_convenio_id` | text | Convênio (número) |
+| `eclinica_ultimo_evento` | text | Tipo do último webhook recebido (ex: falta, agendamento_novo) |
 | `eclinica_ultimo_pagamento` | text | Valor do último pagamento |
 | `eclinica_ultimo_pagamento_data` | date | Data do último pagamento/baixa (novo 2026-07-06) |
 | `eclinica_ultimo_pagamento_descricao` | text | Descrição da baixa (ex: CONSULTA INICIAL) |
 | `eclinica_laboratorio_data_prevista` | date | Previsão de entrega da medicação (novo 2026-07-23) |
 | `eclinica_laboratorio_data_moldagem` | date | Data do pedido da medicação |
-| `eclinica_laboratorio_data_entrega` | date | Data de entrega da medicação |
+| `eclinica_laboratorio_data_entrega` | date | Data em que a medicação CHEGOU na unidade — é a data que dispara o aviso de retirada do flow |
+| `eclinica_laboratorio_data_retirada` | date | Data em que o paciente RETIROU a medicação (coa_datainstalacao; novo 2026-08-03). NÃO confundir com a entrega. Vazia = peça atual não retirada |
+| `eclinica_laboratorio_trabalho_id` | text | Trabalho/tipo da medicação — número cru (aparelho_id; novo 2026-08-03). Lista própria de cada unidade (COMPRIMIDO/POMADA/SPRAY...); número não comparável entre filiais |
+| `eclinica_laboratorio_trabalho` | text | Trabalho/tipo da medicação — NOME resolvido na lista da própria unidade ("SPRAY", "POMADA"...; novo 2026-08-03). Best-effort: pode ficar vazio se a API da unidade estiver fora do ar. Para filtrar/personalizar flows, use SEMPRE este NOME, nunca o número |
 | `eclinica_laboratorio_situacao` | text | Situação do pedido no laboratório |
 | `eclinica_ultima_cobranca_valor` | text | Valor da última cobrança/carnê gerado |
 | `eclinica_ultima_cobranca_vencimento` | date | Vencimento da última cobrança |

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

@@ -29,13 +29,44 @@ E/OU é encadeado condição a condição (sem parênteses).
 | `display_id` | equal_to, not_equal_to, contains, does_not_contain (o `contains`, busca por trecho do número, passou a funcionar de verdade em 2026-07-25 — antes dava erro de banco) |
 | `referer`, `mail_subject` | equal_to, not_equal_to, contains, does_not_contain |
 | `browser_language`, `conversation_language` | equal_to, not_equal_to |
-| `created_at`, `last_activity_at` (valor = data) | is_greater_than, is_less_than, days_before |
+| `created_at`, `last_activity_at` (valor = data) | is_greater_than, is_less_than, days_before + relativos `today`, `yesterday`, `last_days`, `days_ago` (novo 01/08 — ver abaixo) |
 | `card_funnel_stage` (conversa POR CARD do Kanban — valor `funnel:<id>` ou `stage:<id>:<chave_etapa>`) | equal_to, not_equal_to |
 | **qualquer outra chave** = atributo personalizado | conforme o tipo do atributo (ver tabela em api-conventions) |
 
 Atributo personalizado: informe `custom_attribute_type` na condição — `'conversation_attribute'`
 (atributo da conversa) ou `'contact_attribute'`. Sem ele o escopo pode sair errado.
 
+### Data relativa — "Hoje", "Ontem", "últimos X dias" (novo 2026-08-01)
+
+Não calcule data no seu lado pra perguntar "quantas conversas entraram hoje". Existem operadores
+próprios, e eles resolvem tudo em **dias INTEIROS no fuso da CONTA** (`Account#timezone`, padrão
+`America/Sao_Paulo`). Valem em `created_at` e `last_activity_at`, tanto em
+`lionchat_conversations_filter` quanto em `lionchat_contacts_filter`.
+
+| Operador | Valor | Janela |
+|---|---|---|
+| `today` | **nenhum** | hoje, 00:00 → 23:59 |
+| `yesterday` | **nenhum** | ontem, 00:00 → 23:59 |
+| `last_days` | `values: [N]` | últimos N dias **incluindo hoje** (N=7 → de 6 dias atrás 00:00 até hoje 23:59) |
+| `days_ago` | `values: [N]` | o dia EXATO de N dias atrás (um dia só, não um intervalo) |
+| `days_before` | `values: [N]` | tudo **mais antigo** que N dias atrás (o comportamento que já existia) |
+
+```json
+{ "attribute_key": "created_at", "filter_operator": "today", "values": [], "query_operator": null }
+{ "attribute_key": "created_at", "filter_operator": "last_days", "values": [7], "query_operator": null }
+```
+
+**Regras que derrubam a chamada se ignoradas:**
+- `today` e `yesterday` NÃO levam valor — o servidor nem espera o campo.
+- Nos outros três, N tem que ser inteiro entre **1 e 998**. Zero, negativo, texto ou vazio = HTTP 422
+  (`InvalidValue`). Não existe `last_days: 0` pra dizer "hoje" — pra hoje use `today`.
+- `is_greater_than` / `is_less_than` continuam sendo o caminho da data FIXA (`values: ["2026-08-01"]`).
+  Use-os quando o cliente citou um dia específico; use os relativos quando ele disse "hoje", "ontem"
+  ou "últimos X dias".
+
+Por que mudou: até 01/08 a borda do dia era montada em UTC, o que errava **3 horas** no Brasil —
+conversa criada às 22h aparecia no dia seguinte. Agora a borda é a do fuso da conta.
+
 ## 2. Contatos — `lionchat_contacts_filter`
 
 Mesmo shape de condição. 15/página.

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

@@ -186,6 +186,13 @@ Webhooks embutidos NÃO aparecem na listagem de integrações standalone; exclui
 - `title` = texto **EXATO** do botão quick-reply aprovado na Meta (o WhatsApp devolve o TÍTULO no clique; o match é por ele). `value` = slug do título (deduplicado se dois títulos colidem).
 - Handles: `button_<value>` por botão + `no_response` (sempre — texto livre em vez de clique) + `no_reply_timeout` (só com `buttons_timeout > 0`; `buttons_timeout_unit` `minutes|hours|days`; `0` = sem timeout).
 - Modo síncrono (`ai_tool`) e `dry_run` NÃO pausam/roteiam — o template só é enviado (botões decorativos). Só faz sentido em caixa WhatsApp com template de botões aprovado.
+- **O item guarda uma FOTO do template** (corpo + botões) tirada quando foi configurado. Se o modelo for
+  alterado na Meta depois disso, a foto envelhece: até 2026-07-30 a atualização automática ao reabrir o
+  bloco comparava só o CORPO, então mudança APENAS de botão passava batido — a tela mostrava os botões
+  novos (ela lê o modelo vivo) e o flow continuava roteando pelos ANTIGOS. Caso real: um botão renomeado
+  fazia todo mundo cair em "outra resposta". Hoje corpo E botões são comparados. **Se você mudou os
+  botões de um template na Meta, avise que é preciso reabrir o bloco e RELIGAR a saída renomeada** — a
+  aresta do botão antigo é removida junto.
 
 > ⚠️ **SAÍDAS CONDICIONAIS — NUNCA ligue edge nelas sem ativar a condição.** Estas saídas SÓ existem
 > quando a config abaixo está presente. Ligar edge nelas sem isso cria uma **aresta fantasma** (linha
@@ -269,6 +276,13 @@ No editor visual esses destinos só aparecem quando a validação bate (computed
 
 **REGRA:** depois de wait_response com `options` OU `varied_options`, NUNCA coloque node `condition` pra ramificar — ligue os edges direto nos handles `option_X` (em `varied_options`, `X` é o `id` do grupo).
 
+**Node que NÃO salva também avança (corrigido 2026-08-01):** até essa data, o avanço do `wait_response`
+dependia de ter uma variável configurada — com `saveTo: ""` o node RECEBIA a resposta e reentrava em si
+mesmo, e quem respondia no prazo acabava saindo pelo caminho de `timeout`. Sintoma que o cliente
+relatava: "mando a mensagem e o fluxo trava em aguardando resposta". Hoje o node avança sempre; salvar
+o valor é opcional de novo, como o schema sempre prometeu. Se um flow antigo tiver ganhado uma variável
+só pra destravar, ela pode sair.
+
 ### 2.4 `condition`
 
 ```json
@@ -325,7 +339,8 @@ No editor visual esses destinos só aparecem quando a validação bate (computed
 | `equal_any` / `not_equal_any` / `contains_any` / `not_contains_any` | multi-valor (usa `values` array). `contains_any` = contém ALGUMA; `not_contains_any` = não contém NENHUMA (útil pra "seguir só quando a msg não tem nenhuma das palavras-chave de outros flows") |
 | `business_hours` / `outside_business_hours` | horário comercial (par: dentro/fora). `business_hours` aceita `start_hour`/`end_hour` (0-23), `days` (array 0=Dom..6=Sab, ausente=todos) e **`timezone`** (IANA, ex.: `America/Sao_Paulo` — default se ausente). **REGRA:** a saída `outside_business_hours` HERDA `start_hour`/`end_hour`/`days`/`timezone` da `business_hours` ANTERIOR no array — pode deixá-los ausentes na "fora" (o backend preenche). O horário é avaliado no `timezone` (não em UTC) |
 | `can_reply` / `can_reply_closed` | janela 24h aberta/fechada |
-| `conversation_has_agent` / `conversation_no_agent` / `conversation_not_agent` | agente atribuído |
+| `conversation_has_agent` / `conversation_no_agent` / `conversation_not_agent` | agente atribuído (HUMANO) |
+| `conversation_has_ai_agent` / `conversation_no_ai_agent` / `conversation_not_ai_agent` | agente de IA atribuído (novo 2026-08-01) — ver abaixo |
 | `contact_has_label` / `contact_no_label` / `conversation_has_label` / `conversation_no_label` | labels |
 | `kanban_exists` / `kanban_in_stage` / `kanban_won` / `kanban_lost` | card no funil. `funnel_id` é CHAVE SEPARADA da condição (número, ex.: `"funnel_id": 37`). A etapa vai em `value` (slug puro da etapa, ex.: `"avaliacao_aceita"`) ou em `stage` — NÃO no formato `"37:etapa"`. Ex.: `{ "operator": "kanban_in_stage", "funnel_id": 37, "value": "avaliacao_aceita" }` |
 | `card_attr_equals` / `card_attr_contains` | atributo do card (`attrSource: 'card'` + `attr_key`; aceita `card_source: 'trigger'` p/ ler o card que iniciou o flow) |
@@ -342,6 +357,22 @@ No editor visual esses destinos só aparecem quando a validação bate (computed
 
 `greater_than`/`less_than` valem em atributo número (valor numérico) E temporais `date`/`time`/`datetime` (o backend detecta o formato do valor: instante > dia > minutos > número). `number_range` SÓ em número. Nunca use maior/menor em texto/lista.
 
+**Agente de IA — `conversation_has_ai_agent` e irmãos (novo 2026-08-01):** o flow sempre soube LIGAR e
+DESLIGAR a IA (ações `assign_captain` / `deactivate_captain`), mas não sabia PERGUNTAR se ela estava
+ligada. Agora sabe. É o espelho exato do trio do agente humano:
+
+| Forma | Verdadeiro quando |
+|---|---|
+| `{ "operator": "conversation_has_ai_agent" }` (sem valor) | tem QUALQUER IA atribuída |
+| `{ "operator": "conversation_has_ai_agent", "values": [12, 15] }` | a IA atribuída é uma dessas |
+| `{ "operator": "conversation_has_ai_agent", "value": 12 }` | a IA atribuída é exatamente essa |
+| `{ "operator": "conversation_no_ai_agent" }` | não tem IA nenhuma |
+| `{ "operator": "conversation_not_ai_agent", "values": [12] }` | tem IA, mas não é nenhuma dessas |
+
+**Semântica (decisão do dono 01/08): reflete ATRIBUIÇÃO, não "vai responder agora".** Assistente
+pausado no botão de pânico global continua contando como atribuído. Se o cliente perguntar "a IA está
+respondendo?", essa condição NÃO responde isso — ela responde "a IA está ligada nesta conversa?".
+
 **SLA — operador `sla_check` (2026-06):** verifica se a conversa está dentro/fora do prazo de SLA. A regra NÃO usa `field`, só `value` (código fixo):
 
 | `value` | Verdadeiro quando |
@@ -813,6 +844,41 @@ continua servindo pra GRAVAR no contato). Teto: payload acima de 256KB não vira
 disparado por OUTRO gatilho (mensagem, card, data): `{{webhook.*}}` resolve vazio. O autocomplete
 do editor mostra o grupo WEBHOOK com os campos do último payload recebido.
 
+**Variáveis do gatilho `{{trigger.*}}` (novo 2026-08-01):** todo flow — não importa o gatilho — passa
+a saber O QUE o disparou. Antes só existia o tipo, e um flow com VÁRIOS gatilhos não tinha como se
+ramificar por qual deles disparou. Agora dá: `{{trigger.type}}` num node `condition`.
+
+Sempre presente:
+
+| Variável | Conteúdo |
+|---|---|
+| `{{trigger.type}}` | chave do evento (`message_created`, `conversation_created`, `label_added`, `kanban_item_stage_changed`, `webhook_received`, `date_trigger`, `flow_campaign`, `manual`, `pagetrack_visited`…) |
+| `{{trigger.name}}` | rótulo legível do MESMO evento ("Mensagem recebida", "Card mudou de etapa") — use este pra ESCREVER pro cliente, e o `type` pra COMPARAR em condição |
+| `{{trigger.activated_at}}` | quando disparou (ISO 8601) |
+| `{{trigger.kanban_item_id}}` / `{{trigger.funnel_id}}` | só quando veio do Kanban |
+
+Presentes conforme o evento (ausente = resolve vazio, sem erro):
+
+| Bloco | Campos |
+|---|---|
+| `{{trigger.message.*}}` | `id`, `content` (texto da mensagem, cortado em 2.000 caracteres), `type`, `created_at` |
+| `{{trigger.conversation.*}}` | `id` (o display_id), `status`, `channel` (nome amigável: `Waha`, `Whatsapp`, `Instagram`), `inbox_id`, `inbox_name`, `created_at` |
+| `{{trigger.contact.*}}` | `id`, `name`, `phone` |
+| `{{trigger.ad.*}}` (anúncio/CTWA) | `id`, `name`, `creative_id`, `creative_name`, `adset_id`, `adset_name`, `campaign_id`, `campaign_name`, `source`, `headline`, `description`, `cta`, `url` |
+| `{{trigger.attribute.*}}` | `name`, `previous_value`, `current_value`, `changed_at` — o valor ANTES e DEPOIS do atributo que disparou (só nos gatilhos de mudança de atributo) |
+
+Dois atalhos: `{{trigger}}` devolve o contexto INTEIRO em JSON e `{{trigger.data}}` devolve o mesmo
+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.
+
+**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.*}}`
+serve pra perguntar "o que veio COM o gatilho", não pra ser um segundo nome do mesmo dado.
+
+**Variáveis do agente de IA `{{ai_agent.*}}` (novo 2026-08-01):** `{{ai_agent.name}}` e
+`{{ai_agent.id}}` trazem o AI Agente atribuído à conversa (vazio se não houver). Prefixo `ai_agent` de
+propósito — `agent` sozinho é o atendente HUMANO, e confundir os dois seria pior que não ter.
+
 ---
 
 ## 2-D. Exit conditions (saída automática do flow)

package/dist/docs/resources/glossary.md

@@ -168,6 +168,23 @@ do rodízio).
 aceitam `supervisor_ids[]` além de `user_ids[]` — os IDs em `supervisor_ids` viram supervisores;
 os de `user_ids` viram membros comuns. A resposta traz `is_supervisor` (boolean) por agente.
 
+### Supervisor de TIME (novo 2026-07-30) — é outra marca, independente da de caixa
+
+O time ganhou os mesmos dois papéis. Supervisor de time continua membro pra tudo (menção, e-mail de
+automação, acesso a funil do Kanban, relatório, contagem, atribuição MANUAL) e fica fora da
+distribuição automática do time — tanto de conversa quanto do rodízio de card do funil.
+
+**Onde fica armazenado:** flag `team_members.auto_assignable` (espelho da de caixa).
+
+**Como definir/ler via tools:** `lionchat_team_members_create` / `_update` com `supervisor_ids[]`.
+**Diferença importante do contrato da caixa:** aqui `user_ids[]` é sempre a lista COMPLETA de membros
+e `supervisor_ids[]` é um SUBCONJUNTO dela; omitir `supervisor_ids` não mexe em papel nenhum.
+`lionchat_team_members_list` traz `is_supervisor`.
+
+**As duas marcas NÃO se comunicam:** a da caixa protege da distribuição da caixa, a do time da
+distribuição do time. Supervisor de caixa que é agente num time continua recebendo por aquele time —
+comportamento intencional.
+
 ## KanbanItem (Card do CRM)
 
 ### Estrutura

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

@@ -115,7 +115,8 @@ Um card individual dentro de uma etapa.
 | `funnel_stage` | Chave da etapa (ex: `"novo_lead"`) |
 | `position` | Ordem dentro da etapa |
 | `stage_entered_at` | Quando entrou na etapa atual (pra métrica de tempo) |
-| `conversation_display_id` | Conversa principal vinculada |
+| `conversation_display_id` | Conversa principal vinculada. **O sistema move este ponteiro sozinho (desde 04/08/2026)**: quando nasce uma conversa nova do mesmo contato naquela caixa, o card passa a apontar pra ela. O card é da PESSOA, não do atendimento. **NÃO trate este valor como estável** — releia antes de usar. Enviar `conversation_display_id` num UPDATE de card é ignorado de propósito (senão o reenvio do formulário regravaria o número antigo por cima). |
+| `origin_conversation_display_id` | Conversa em que o card NASCEU (só preenchida se o vínculo já foi movido). É o que o relatório de origem de lead usa, pra uma venda não mudar de mês nem de anúncio quando o card anda. |
 | `linked_conversations` | jsonb array `[{display_id: 123}, {display_id: 456}]` — múltiplas conversas |
 | `item_details` | jsonb (ver abaixo) |
 | `custom_attributes` | jsonb — campos custom (igual contatos) |

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

@@ -489,6 +489,25 @@ viraram conversa). É um relatório de LEITURA puro — não cria nem altera nad
 **Perguntas que esse relatório responde:** "qual plataforma trouxe mais leads?", "qual campanha/
 conjunto converteu melhor?", "quantos leads únicos vieram esse mês e quantos fecharam?".
 
+### Atributos de anúncio (`ctwa_*`) — dois novos e nomes alinhados (2026-08-01)
+
+Conversa que veio de anúncio "Clique para WhatsApp" carrega atributos `ctwa_*` (`ctwa_campaign_name`,
+`ctwa_adset_name`, `ctwa_ad_name`, `ctwa_creative_name`, `ctwa_source_url`…). Eles são atributos de
+conversa normais: dá pra filtrar (`lionchat_conversations_filter`), usar em público de campanha e ler
+em flow (`{{trigger.ad.*}}`).
+
+Dois deles apareciam no painel **sem cadastro nenhum** e por isso não dava pra filtrar por eles em
+lugar algum. Foram criados em 01/08 e agora funcionam como os demais:
+
+| Chave | Rótulo | Tipo |
+|---|---|---|
+| `ctwa_conversion_source` | Plataforma de Origem do Anúncio | texto |
+| `ctwa_conversion_delay_seconds` | Tempo até a Conversão (s) | número |
+
+Na mesma data os rótulos de exibição dos `ctwa_*` foram alinhados com os do painel. **As CHAVES não
+mudaram** — flow, automação, campanha e filtro guardam a chave, nunca o rótulo, então nada que já
+existia quebrou. Se o cliente disser que "o nome do campo mudou", é só o rótulo na tela.
+
 ## Quando o usuário pede algo MUITO específico que não existe num endpoint
 
 Se a pergunta requer cálculos custom (ex: "conversas por agente que duraram mais de X minutos"):