@lionchat/mcp-server 1.9.0 → 1.10.0

package/dist/docs/instructions.md

@@ -227,9 +227,15 @@ POST /api/v1/accounts/{account_id}/kanban_items
 ### Relatório de produtividade
 ```
 1. lionchat_reports_summary (visão geral)
-2. lionchat_reports_list (por agente — passa since/until ISO 8601)
+2. lionchat_reports_list (por agente — passa since/until em Unix EM SEGUNDOS)
 3. Comparar avg_first_response_time entre agentes
 ```
+**`since`/`until` dos relatórios só aceitam número Unix em SEGUNDOS** (`1782864000` = 01/07/2026 00:00
+UTC), nunca ISO 8601 nem data por extenso — o formato ISO do resto da plataforma (seção 3) NÃO vale
+aqui. Desde 29/07/2026 a API recusa com HTTP 400 (`invalid_date_params`); antes disso o relatório
+voltava ZERADO com HTTP 200 (a conta 19 tinha 4.396 conversas no período e a resposta vinha zero).
+Converta a data do usuário para segundos antes de chamar. Os exports em CSV (agents, inboxes, labels,
+teams, conversations_summary) exigem as DUAS pontas; nos demais, `since` ou `until` sozinho é válido.
 
 ### Criar campanha de WhatsApp (disparo em massa)
 ```
@@ -292,11 +298,15 @@ e pular evita que ela receba tudo em dobro. Quem está sendo atendido pela equip
 | Limite | Valor |
 |---|---|
 | `per_page` max | 100 |
-| Bulk actions (IDs) max | 100 por chamada |
+| Bulk actions (IDs) max | 300 por chamada (desde 18/05/2026; passou disso = HTTP 422 `bulk_ids_limit_exceeded`) |
 | Rate limit leitura | 1200/min por token |
 | Rate limit escrita | 600/min por token |
 | Loop detection | bloqueia chamada idêntica >10x em 10s |
 
+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
+teto de 300 vale para o caminho normal, com a lista de IDs. Kanban usa o mesmo teto no `item_ids`.
+
 ## 7. Confirmar antes de agir — regra de ouro
 
 Antes de QUALQUER ação que escreve, modifica, apaga ou envia, pare e avalie se o pedido está claro e completo. Na dúvida, pergunte — **nunca chute**.

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

@@ -349,17 +349,27 @@ Quando rate-limited:
 
 ### Bulk actions
 
-`POST /bulk_actions` aceita arrays de IDs. **Máximo 100 IDs por chamada**.
+`POST /bulk_actions` aceita arrays de IDs. **Máximo 300 IDs por chamada** (`MAX_BULK_IDS`, desde
+2026-05-15). Acima disso o servidor recusa com `422` + `code: "bulk_ids_limit_exceeded"` — quebre em
+chamadas de 300.
+
+**Exceção:** contato com `select_all: true` (agir sobre TODOS os contatos do filtro) **não tem teto** —
+o servidor resolve pelo próprio filtro (`query` / `labels_filter`), em lotes no fundo, e não usa `ids`.
 
 ```json
 {
   "type": "Conversation",
-  "ids": [1, 2, 3, ...],   // max 100
-  "action_name": "assign_agent",
-  "action_attributes": { "assignee_id": 6 }
+  "ids": [1, 2, 3, ...],          // max 300
+  "fields": { "assignee_id": 6 }  // conversa: status, assignee_id, team_id, inbox_id, captain_assistant_id
 }
 ```
 
+**⚠️ `action_attributes` NÃO EXISTE.** O servidor não lê esse campo em lugar nenhum (só aparece em
+comentário de TODO no código). Mandar a mudança por ali devolve **200 OK e não faz absolutamente nada** —
+falha silenciosa, sem erro na tela. Conversa se altera por `fields` (+ `labels: {add:[], remove:[]}` e
+`snoozed_until`). Em conversa o `action_name` é **ignorado**; ele só tem efeito em **contato**, onde
+`"delete"` apaga os contatos (sem ele, o que vale é `labels: {add: []}`).
+
 ### Search (overhaul 2026-06-10)
 
 `GET /search?q=texto` — busca cross-entidade (conversations, contacts, messages, articles, kanban_items)

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

@@ -77,7 +77,14 @@ Conversa com 200 mensagens? **Não baixe tudo**:
 ## Operações em massa
 
 Pra atribuir labels, mover cards, etc em vários itens:
-- `kanban_bulk_bulk_actions` (cards Kanban)
+
+- `kanban_bulk_bulk_actions` — **NÃO é de cards do Kanban**, apesar do nome. Ela bate em
+  `POST /bulk_actions` e age em **conversas ou contatos** (o `type` é `Conversation` ou `Contact`).
+  Usar ela achando que move card não dá erro visível — só não faz o que você queria.
+- Cards do Kanban têm **três** ferramentas próprias, uma por ação:
+  - `kanban_bulk_create` → `bulk_move_items` (mover cards de etapa)
+  - `kanban_bulk_create_1` → `bulk_assign_agent` (definir o responsável)
+  - `kanban_bulk_create_2` → `bulk_set_priority` (definir a prioridade)
 - `kanban_items_kanban_agents_create` em massa (passar array)
 - `automation_rules_*` (criar regras em vez de fazer manualmente)
 
@@ -127,7 +134,32 @@ O `config` DEVE ser enviado como **objeto** (ex.: `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.
-- **Cache automático** ativo em todos os 15 modelos suportados (GPT-4.1 Nano até GPT-5.2 Pro, o1, o3, o4-mini). Desconto 50-75% no input cachado, sem configuração. Reuso do prompt do agente em múltiplas conversas maximiza a economia.
+- **Cache automático** ativo em todos os 16 modelos oferecidos na plataforma. Desconto 50-75% no input cachado, sem configuração. Reuso do prompt do agente em múltiplas conversas maximiza a economia.
+
+### Lista real de modelos (`config.model`)
+
+Estes são os 16 valores que o seletor de modelo do painel oferece (`ModelSelector.vue`). Só recomende
+valores desta lista:
+
+| Faixa | Modelos |
+|---|---|
+| Econômicos / rápidos | `gpt-4.1-nano`, `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-5.4-nano`, `gpt-5.4-mini` |
+| Intermediários | `gpt-4o`, `gpt-4.1`, `gpt-5-mini`, `gpt-5.4` |
+| Raciocínio | `o3-mini`, `o4-mini` |
+| Premium | `gpt-5`, `gpt-5.2`, `gpt-5.5`, `o1`, `o3` |
+
+**`GPT-5.2 Pro` não existe.** O valor válido é `gpt-5.2`, sem "Pro".
+
+> **PERIGO — família `gpt-5.6` (`gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`): REMOVIDA em 29/07/2026.**
+> Esses modelos **recusam function tools** em `/v1/chat/completions` (erro 400 real: "Function tools with
+> reasoning_effort are not supported"). Como o AI Agente usa ferramentas em **toda** resposta, 100% das
+> chamadas falhavam e a IA ficava **MUDA** — sem erro na tela, sem resposta. Ficou 2 semanas invisível.
+> **Nunca sugira, nunca grave** um `gpt-5.6` — nem se o cliente pedir "o mais novo/mais forte".
+>
+> O campo `config.model` **não tem lista branca no servidor**: ele é `store_accessor` do `config` e
+> aceita qualquer texto sem validar. Modelo inválido salva com 200 e só quebra na hora de responder.
+> Desde 29/07 o erro vira uma **nota privada em português** na conversa (`llm_request_rejected`) — é o
+> primeiro lugar a olhar quando "a IA parou de responder logo depois de mexerem nas configurações".
 
 ## Follow-up automático multi-etapa (2026-06)
 
@@ -137,21 +169,61 @@ O follow-up do AI Agente agora suporta **cadência de até 3 etapas** via `confi
 { "config": { "feature_follow_up": true, "follow_up_steps": [
   { "after_minutes": 30,  "prompt": "Pergunte gentilmente se ainda tem interesse" },
   { "after_minutes": 240, "prompt": "Ofereça tirar dúvidas" },
-  { "after_minutes": 1140, "prompt": "Última tentativa, despeça-se cordialmente" }
+  { "after_minutes": 1110, "prompt": "Última tentativa, despeça-se cordialmente" }
 ] } }
 ```
 
-Regras: cada etapa ≥ 5 min; soma total ≤ 1440 min (24h); máx 3 etapas. Campos legados
-`follow_up_time` + `follow_up_prompt` continuam funcionando como 1 etapa única.
+Regras: cada etapa ≥ 5 min; **soma total ≤ 1380 min (23h)**; máx 3 etapas. Campos legados
+`follow_up_time` + `follow_up_prompt` continuam funcionando como 1 etapa única (e obedecem ao **mesmo
+teto de 1380**).
+
+> **O teto é 1380, não 1440** (`Captain::Assistant::FOLLOW_UP_MAX_TOTAL_MINUTES`). Motivo: a janela de
+> 24h do WhatsApp conta a partir da **mensagem do cliente**, não do primeiro acompanhamento — 1h de
+> folga evita agendar uma cobrança que a Meta recusaria na hora de enviar. Montar a cadência somando
+> 1440 faz o salvamento ser **recusado**. Pegadinha: a mensagem de erro do campo legado `follow_up_time`
+> ainda diz "must be between 5 and 1440 minutes", mas a validação usa 1380 — não confie no texto do erro.
+
+(O exemplo acima soma exatamente 1380: 30 + 240 + 1110.)
+
 Dispara quando o CLIENTE fica inativo após resposta da IA. O motor de follow-up é dedicado e
 **só-leitura** (não executa ferramentas, não coleta dado — só redige a mensagem de retomada,
 com saída estruturada garantida). `paused=true` no assistente corta os follow-ups também.
 
-**Corrigido em 2026-07-24:** quando a IA é ativada por um **Flow** (ação "Ativar IA") ou por uma
-**automação**, o follow-up agora é agendado no ato da ativação. Antes, nesses dois caminhos a
-cadência simplesmente nunca começava — a conversa ficava com IA ativa e sem nenhum follow-up. Se um
-cliente relatar "a IA nunca faz o follow-up", confira primeiro se a ativação veio por flow/automação
-e se a conta já está na versão de 24/07.
+### "A IA nunca faz o follow-up" — o conserto é de 29/07, NÃO de 24/07
+
+**Não repita que isso foi corrigido em 24/07.** A versão de 24/07 agendava o follow-up **dentro** do
+bloco do "Responder na hora": ou seja, ela só funcionava quando esse interruptor estava **LIGADO** —
+justamente o caso que menos precisa dela. Com "Responder na hora" **desligado**, a IA não fala, o único
+outro gatilho (o hook de mensagem enviada) também não dispara, e a conversa fica **com IA ativa e sem
+nenhum acompanhamento, para sempre**. Aconteceu em **140 conversas da conta 52** — todas criadas
+DEPOIS do suposto conserto de 24/07. A ativação **manual pela tela** nunca esteve coberta em nenhuma
+das duas versões até 29/07.
+
+**"Responder na hora" e acompanhamento são INDEPENDENTES.** São perguntas diferentes:
+- *Responder na hora* (`captain_reply_now` / `proactive`) = "a IA fala agora, sem esperar o cliente?"
+- *Acompanhamento* (`feature_follow_up`) = "a IA cobra depois, se ninguém responder?"
+
+Desligar o primeiro **não** deve desligar o segundo. Nunca oriente o cliente a ligar "Responder na
+hora" para o acompanhamento funcionar.
+
+**Corrigido de verdade em 2026-07-29**, nos três caminhos que ativam a IA, com o agendamento **fora**
+do bloco do "Responder na hora":
+- Flow, ação "Ativar IA" (`FlowBuilder::ActionDelegator`) — só em ativação nova (a conversa não tinha IA)
+- Automação, ação "Atribuir assistente" (`AutomationRules::ActionService`)
+- Ativação manual pela tela da conversa (`ConversationsController`) — armado **antes** da checagem do
+  "Responder na hora"
+
+**Ainda descoberto (não corrigido):** ativar a IA em **lote** (ação em massa de conversas com
+`captain_assistant_id`) **não arma o acompanhamento nem dispara resposta imediata**. Se o cliente
+ativou a IA em massa e reclama que ela não cobra de volta, é isso — e o caminho é reativar pela tela
+ou por automação.
+
+Diagnóstico, nesta ordem, quando relatarem "a IA nunca faz o follow-up":
+1. `config.feature_follow_up` está ligado no assistente? E `paused` está desligado? (`paused=true`
+   corta os follow-ups)
+2. A ativação veio por **lote**? Então nunca foi armado.
+3. Tem `follow_up_skip_conditions` batendo (etiqueta, atributo, janela de silêncio)?
+4. A soma das etapas passa de 1380 min? Nesse caso o assistente nem salvou a cadência.
 
 ## Condições para NÃO fazer follow-up + horário de silêncio (2026-07)
 

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

@@ -98,17 +98,65 @@ Avaliação:
 
 ### 4. Auto-assignment
 
-Roda após automation rules. Lógica simplificada:
+Roda após automation rules. Existem **DOIS caminhos vivos** (`Inbox#auto_assignment_v2_enabled?`),
+não um moderno e um legado:
 
 ```
-SE inbox.enable_auto_assignment_v2:
-  SE inbox.assignment_policy associada:
-    → Política decide (round-robin, balanced, etc)
-  SENAO:
-    → assignee_id fica null (manual)
+SE inbox.assignment_policy vinculada:
+  → modo POLÍTICA: round-robin ou balanced, prioridade da fila, capacidade
+SENÃO SE inbox.enable_auto_assignment (botão "Distribuição automática" da própria caixa):
+  → modo SIMPLES: round-robin entre os membros da caixa
+SENÃO:
+  → assignee_id fica null (atribuição manual)
 ```
 
-V2 (Assignment Policy) é o motor moderno. V1 (campo `auto_assignment` simples) é legado.
+Os dois caminhos rodam no MESMO serviço (`AutoAssignment::AssignmentService`), usam o MESMO rodízio
+(`AutoAssignment::RoundRobinSelector` — só a política pode trocá-lo pelo modo `balanced`) e passam
+pelo MESMO freio de rajada
+(`AutoAssignment::RateLimiter`). O que muda é de onde vem a configuração: com política vinculada, ela
+manda em tudo (inclusive em "distribuir para agentes offline"); sem política, vale o que está no
+`auto_assignment_config` da própria caixa.
+
+**NUNCA escreva que o modo simples é legado, nem recomende criar Política de Atribuição para quem só
+quer o botão da caixa.** Vincular uma política **esconde a seção inteira de Distribuição Automática da
+tela da caixa** (`CollaboratorsPage.vue`: `showAutoDistribution = !inbox.has_assignment_policy`). O
+cliente perde os controles que estava usando, não entende por que sumiram, e o que ele configurou lá
+passa a ser ignorado (o valor fica gravado e só volta a valer se a política for desvinculada).
+
+Regra prática:
+- Cliente quer só "dividir os leads entre a equipe" → **botão da própria caixa**. Não crie política.
+- Cliente quer regra compartilhada entre várias caixas, modo balanced, prioridade de fila ou limite de
+  capacidade por atendente → aí sim Política de Atribuição.
+
+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.
+
+**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
+  manda; `false` = vale o botão da própria caixa.
+- Com política vinculada, leia `fair_distribution_limit` (quantas conversas por atendente),
+  `fair_distribution_window` (tamanho da janela, **em segundos**) e `assign_offline_agents` na
+  resposta da política. O `auto_assignment_config` da caixa é **IGNORADO** nesse caso — não o cite.
+- Sem política, leia as MESMAS chaves dentro do bloco `auto_assignment_config` da caixa
+  (`fair_distribution_limit`, `fair_distribution_window`, `assign_offline_agents`).
+- Chave ausente/vazia = vale o padrão de fábrica (hoje 10 conversas a cada 600 segundos) — cite isso
+  só como "valor de fábrica, confira o da conta", nunca como se fosse a configuração do cliente.
+
+**EXCEÇÃO SEM FREIO (não dá pra descobrir lendo a resposta):** caixa **sem** política vinculada, com
+`assign_offline_agents` LIGADO e **sem número escolhido** em `fair_distribution_limit`, roda **SEM
+FREIO NENHUM** (`AutoAssignment::RateLimiter#resolve_limit`: `return 0 if inbox.assign_offline_agents?`).
+Racional (decisão do dono 29/07): com offline ligado todo membro está sempre na roleta, então a divisão
+já é igual por construção e o freio só atrasaria a entrega. Não existe campo dizendo "sem freio" — o
+bloco vazio parece "padrão", mas não é. Efeito prático: **nessas caixas, dizer ao cliente que existe um
+teto por atendente é MENTIRA**. Número escolhido pelo cliente sempre vence o toggle: se
+`fair_distribution_limit` tem um número MAIOR QUE ZERO, o freio existe mesmo com offline ligado.
+
+**Zero também é "sem freio":** na caixa (não na política), `fair_distribution_limit: 0` é a saída
+explícita de quem não quer teto nenhum — o freio fica desligado (`RateLimiter#enabled?` exige limite
+positivo). Ou seja, existem DUAS formas de a caixa ficar sem freio: campo vazio com offline ligado, ou
+zero escrito de propósito. Na Política de Atribuição o zero nem é aceito (o cadastro exige maior que
+zero), então política vinculada SEMPRE tem freio.
 
 ### 5. Captain (IA Agente)
 
@@ -138,7 +186,10 @@ handoff consultor→gestor). Pendente só acontece por ação explícita:
 - Ferramenta nativa da IA (deixar conversa pendente)
 
 Comportamentos importantes:
-- Mensagem nova do cliente NÃO reabre conversa pendente (segue pendente na lista)
+- Mensagem nova do CLIENTE REABRE conversa pendente (volta pra Aberta, com pílula de aviso na
+  conversa). Só a do cliente: resposta do ATENDENTE não reabre. Vale desde 30/07/2026 e REVOGA a
+  regra anterior de 20/07 ("pendente não reabre") — decisão do dono depois de a conta 19 acumular
+  258 clientes esperando sem o time ver. NUNCA responda que a conversa fica parada em Pendente
 - Pendente ATRIBUÍDA notifica o responsável (o gestor recebe o aviso)
 
 ### 7. Resolução (status 1)
@@ -186,10 +237,20 @@ Conversation
 
 ### "Conversa não atribuiu ninguém"
 
-1. `inbox.enable_auto_assignment_v2` está true?
-2. `inbox.assignment_policy` está setado?
-3. Tem `InboxMember` ativos pra essa inbox?
-4. Tem `automation_rule` que poderia ter atribuído antes?
+1. A distribuição está ligada em ALGUM dos dois caminhos? `inbox.assignment_policy` vinculada **ou**
+   `inbox.enable_auto_assignment` true. Não existe campo `enable_auto_assignment_v2` — não peça por ele.
+   Política vinculada **não é requisito**: caixa sem política e com o botão ligado distribui normalmente.
+2. Se há política: ela está com `enabled: true`? Política desligada = ninguém é atribuído.
+3. Tem `InboxMember` com `auto_assignable: true`? Supervisor de caixa é membro mas **não entra** no rodízio.
+4. Se "distribuir para agentes offline" está desligado, tem alguém **online** agora? Sem ninguém online
+   a fila fica parada até alguém logar.
+5. O atendente pode estar no **teto da janela** do freio de rajada (o robô só entrega N conversas por
+   atendente/caixa dentro de uma janela deslizante). A vaga volta quando a conversa é resolvida, adiada
+   ou vira pendente — e a fila anda sozinha em até 1 minuto. Antes de culpar o freio, confira os
+   valores reais da conta e a exceção SEM FREIO (seção 4) — pode não haver teto nenhum ali.
+6. Se a caixa tem **uma única** conversa esperando, o freio **nem se aplica** (`should_apply_rate_limit?`
+   exige mais de 1 não atribuída). Nesse caso a causa é outra — não culpe o freio.
+7. Tem `automation_rule` que poderia ter atribuído antes?
 
 ### "IA não respondeu"
 

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

@@ -245,15 +245,23 @@ Captain::Assistant
 ├── config (jsonb) — chaves principais:
 │     model, temperature, instructions (max 20.000 chars), feature_memory, feature_faq,
 │     feature_follow_up (bool), follow_up_steps (array de {after_minutes, prompt} — ATE 3 etapas,
-│       cada uma >= 5 min, soma <= 1440 min/24h; legado follow_up_time+follow_up_prompt = 1 etapa),
+│       cada uma >= 5 min, soma <= 1380 min = 23h (2026-07-29 — NAO 1440: a janela de 24h do WhatsApp
+│       conta da MENSAGEM DO CLIENTE, nao do 1o follow-up, entao 1440 disparava com a janela ja fechada.
+│       Somar 1440 = 422. GOTCHA: no campo legado follow_up_time a mensagem de erro do servidor ainda
+│       diz "must be between 5 and 1440 minutes" por engano — o teto que ele aplica e 1380);
+│       legado follow_up_time+follow_up_prompt = 1 etapa),
 │     follow_up_skip_conditions (array — condicoes pra NAO fazer follow-up, logica OU, ate 3; tipos:
 │       label {operator present|absent, labels[]}; contact_attr/conversation_attr {attribute, operator
 │       equal|not_equal|contains|present|blank|gt|lt, value}; time_window {start, end — horas inteiras
 │       0-23; NAO envia follow-up nesse periodo, janela circular ex 22->7; a IA SEGUE respondendo o
 │       cliente normal — o silencio e so do follow-up}),
-│     feature_pause_on_human_reply (bool — a IA se DESLIGA sozinha na conversa quando um HUMANO
-│       assume: atendente responde pelo painel (ao vivo) OU mensagem enviada do celular. NAO conta:
-│       nota privada, msg da propria IA, automacao, campanha, confirmacao de agendamento, msg agendada),
+│     feature_pause_on_human_reply (bool, nasce DESLIGADO — quando ligado, a IA se DESLIGA sozinha na
+│       conversa quando um HUMANO assume: atendente responde pelo painel (ao vivo) OU mensagem enviada
+│       do celular. NAO conta: nota privada, msg da propria IA, automacao, campanha, confirmacao de
+│       agendamento. MENSAGEM AGENDADA DEPENDE DE QUEM AGENDOU (2026-07-29): agendada pela IA (a tool
+│       carimba source_type='Captain::Assistant' e o disparo assina como o assistente) NAO desliga;
+│       agendada por ATENDENTE assina como User com Current.user setado no disparo = conta como
+│       atendente ao vivo e DESLIGA a IA da conversa),
 │     activation_label (etiqueta que ativa o agente — unica por conta),
 │     min_response_time / max_response_time (delay humanizado, 1-60s),
 │     disabled_tools (array de IDs de tools desativadas pro assistente),

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

@@ -107,8 +107,16 @@ Item (sem `config`): `{ "key": "campaign_trigger" }`
 - Pode conviver com outros gatilhos no mesmo flow (ex.: um flow que responde a mensagem E também pode
   ser disparado em campanha). É **isento** da trava de gatilho duplicado.
 - Só flow de conversa (`flow_type: conversation`); flow de grupo funciona, mas o público é de contatos.
-- Em caixa WhatsApp **oficial**, o 1º bloco de mensagem do flow precisa ser um **template aprovado** —
-  a campanha é recusada na criação (422) se não for. Em QR Code não existe essa regra.
+- Em caixa WhatsApp **oficial**, o primeiro bloco de mensagem de **CADA CAMINHO** que sai do Início
+  precisa abrir com **template aprovado** — não só o primeiro bloco que o flow encontra. Com
+  randomizador (teste A/B) ou condição logo no começo, **todas** as variações são conferidas: basta
+  UMA sem template pra campanha ser recusada na criação (422). O erro nomeia os blocos culpados pelo
+  rótulo, teto de 5: `must start with an approved WhatsApp template on official inboxes (no template
+  in: <rótulos>)`. O que vale é o **primeiro item** do `messageItems` daquele bloco, e os tipos
+  aceitos são `template` (o que a tela grava) e `whatsapp_template` (legado). Flow sem nenhum bloco
+  de mensagem não tem o que validar. Em QR Code não existe essa regra.
+  (Corrigido em 2026-07-29: até então a checagem aceitava só `whatsapp_template` — nome que a tela
+  NUNCA gravou — e olhava um caminho só; recusava 100% das caixas oficiais.)
 - Como a campanha inicia o flow com o contato **sem ter mandado nada**, escreva o 1º bloco assumindo
   contato frio (apresente-se, dê contexto) — diferente de um flow de atendimento, que responde a alguém.
 
@@ -418,6 +426,10 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 
 **`update_attribute` — campos EXATOS:** `attr_source` (`'contact'`, `'conversation'` ou `'card'`), `attr_key` (nome do atributo), `attr_value` (valor). NÃO existem `entity`/`key`/`value` — esses são ignorados e não salvam nada.
 
+**Coerção por TIPO (2026-07-29):** em `attr_source: 'contact'|'conversation'`, o `attr_value` de atributo personalizado é coagido pelo tipo da definição antes de gravar: número/moeda/porcentagem viram numérico ("1.234,56" → 1234.56; inteiro fica inteiro), checkbox aceita sim/não/true/false e grava BOOLEANO, lista casa caixa-insensível e grava a opção canônica, data aceita DD/MM/AAAA ou ISO, hora aceita "14:30"/"14h30". Valor irreconhecível grava como veio e o passo mostra nota âmbar no histórico. Card NÃO coage (atributo de card não tem definição tipada no backend).
+
+**Campos NATIVOS do contato (2026-07-29):** com `attr_source: 'contact'`, `attr_key` também aceita os paths canônicos `contact.name`, `contact.email`, `contact.cpf`, `contact.cnpj`, `contact.rg`, `contact.passport`, `contact.date_of_birth`, `contact.gender`, `contact.marital_status`, `contact.profession` e `contact.address.{cep,street,number,complement,neighborhood,city,state,country}` — gravam na ficha nativa do contato (não em custom_attributes). Regras: telefone/identifier/etiquetas NÃO são aceitos (mapa fechado — chave fora dele vira atributo personalizado comum); documentos, nascimento, gênero e **e-mail** só preenchem campo VAZIO; nome/profissão/estado civil/endereço sobrescrevem; valor em branco nunca grava; gênero aceita `m|f|o|na` e estado civil `solteiro|casado|uniao_estavel|divorciado|separado|viuvo`; data de nascimento em `dd/mm/aaaa` ou `aaaa-mm-dd`. Recusas aparecem no histórico de execução (passo 'skipped'/'error' com mensagem).
+
 **Somar/subtrair NÃO é operação dedicada** — é filtro Liquid no próprio `attr_value`. O valor é resolvido como template antes de salvar. Exemplos:
 
 ```json
@@ -497,14 +509,22 @@ NÃO existe `.payload`/`.response` (`{{api_response.payload.x}}` resolve vazio).
 
 **Modelo por ação — `aiModel` + `aiModelExplicit` (2026-07-13):** TODO modo aceita escolher o modelo
 LLM no próprio nó, com ou sem assistente, em qualquer tipo de flow. Enviar o par:
-`"aiModel": "gpt-4.1-mini"` (whitelist de `FlowBuilder::RawLlmService::SUPPORTED_MODELS` — ex.
-gpt-4o-mini, gpt-4o, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5*, o1, o3*, o4-mini) JUNTO de
-`"aiModelExplicit": true`. SEM a flag o backend ignora o aiModel nos modos novos (proteção de nós
-antigos que carregam aiModel de default nunca honrado). `aiModel` vazio/ausente = modelo padrão da
-conta. Com assistente selecionado, o override também vale (sobrepõe o modelo que o caminho do
-assistente usaria). Modelo fora da whitelist = ignorado (cai no padrão da conta).
+`"aiModel": "gpt-4.1-mini"` JUNTO de `"aiModelExplicit": true`. SEM a flag o backend ignora o
+aiModel nos modos novos (proteção de nós antigos que carregam aiModel de default nunca honrado).
+`aiModel` vazio/ausente = modelo padrão da conta. Com assistente selecionado, o override também vale
+(sobrepõe o modelo que o caminho do assistente usaria). Modelo fora da whitelist = ignorado (cai no
+padrão da conta).
 Exemplo: `{"aiMode":"sentiment","aiAssistantId":"12","aiModel":"gpt-4.1-mini","aiModelExplicit":true}`.
 
+**A whitelist (`FlowBuilder::RawLlmService::SUPPORTED_MODELS`) é uma lista FECHADA de 16 nomes, SEM
+curinga** — não existe "a família gpt-5 inteira":
+`gpt-4o-mini`, `gpt-4o`, `gpt-4.1-nano`, `gpt-4.1-mini`, `gpt-4.1`, `gpt-5-mini`, `gpt-5`,
+`gpt-5.2`, `gpt-5.4-nano`, `gpt-5.4-mini`, `gpt-5.4`, `gpt-5.5`, `o1`, `o3`, `o3-mini`, `o4-mini`.
+A família **`gpt-5.6` (luna/terra/sol) foi REMOVIDA em 2026-07-29**: ela recusa function tools
+(erro 400 na OpenAI), o que deixava o Agente de IA **mudo em 100% das chamadas** — saiu também daqui
+pra não ser oferecida numa tela e faltar na outra. Também não existem `o1-mini`, `gpt-4.5-preview`,
+`gpt-5.2-pro` nem `gpt-5.5-pro` (a OpenAI recusa).
+
 **OBRIGATÓRIO via API — `aiAssistantId`:** os modos `generate`/`intent`/`sentiment`/`extract`
 EXIGEM um `aiAssistantId` válido (id de um assistente Captain da conta). Sem ele o nó SAI cedo
 (`action: continue`) sem gravar nada — a variável de saída (`aiResponseVar`/`ai_intent`/`ai_sentiment`)
@@ -581,15 +601,22 @@ O campo raiz é **`waitMode`**: `"duration"` (default), `"date"` ou `"weekday"`.
     "waitMode": "weekday",
     "waitWeekday": 1,
     "waitWeekdayTime": "09:00",
+    "waitWeekdayTimeMode": "fixed",
     "waitTimezone": "America/Sao_Paulo"
   }
 }
 ```
 
-- `waitWeekday`: 0=domingo, 1=segunda... 6=sábado. `waitWeekdayTime` = `"HH:MM"` 24h, **SEMPRE fixo** (este campo NÃO aceita variável — decisão de produto). `waitTimezone` = mesmo campo do modo date.
+- `waitWeekday`: 0=domingo, 1=segunda... 6=sábado. `waitWeekdayTime` = `"HH:MM"` 24h. `waitTimezone` = mesmo campo do modo date.
+- **Variável no Horário (novo 2026-07-29 — reverte a proibição de 06/07):** o campo `waitWeekdayTime` ACEITA variável `{{ }}`, com o mesmo contrato dos campos do modo `date`. O modo mora em **`waitWeekdayTimeMode`**: `"fixed"` (default, e o que vale quando a chave está ausente) ou `"variable"` — espelho exato do `waitTimeMode`.
+  - **Mandar a variável SEM `"waitWeekdayTimeMode": "variable"` não funciona e não avisa:** o motor trata o campo como texto fixo, a chave `{{ }}` nunca é resolvida e o horário calculado não é o pretendido. Não há erro de validação, nem na API nem na tela. Como o MCP escreve o JSON do fluxo direto, sem passar pela tela, esse par é obrigatório.
+  - Exemplo: `{"waitMode":"weekday","waitWeekday":1,"waitWeekdayTime":"{{contact.custom_attribute.horario_retorno}}","waitWeekdayTimeMode":"variable","waitTimezone":"America/Sao_Paulo"}`.
+  - Resolve UMA única vez, na entrada do node (quem já está esperando mantém o valor capturado). Aceita `"14:30"`, `"9:30"`, `"14h30"`, `"14h"`, `"14:30:00"` — ou seja, atributo tipo `time` (Hora 24h). Valor ISO de atributo `date`/`datetime` é rejeitado (mesma regra do campo Horário do modo `date`).
+  - Variável que não resolve pra horário válido → saída `error` (payload `invalid_variable_datetime`, `field: waitWeekdayTime`).
+  - Modo `fixed` NUNCA emite erro: horário em branco cai no default `09:00` — flow antigo intacto.
 - (Os nomes `targetWeekday`/`targetHour` NÃO existem — eram um erro de documentação antiga.)
 
-**Handles que SAEM:** `success` (+ `error`, emitido apenas quando um campo em modo `variable` resolve pra valor inválido no modo `date`).
+**Handles que SAEM:** `success` (+ `error`, emitido quando um campo em modo `variable` resolve pra valor inválido — vale nos DOIS modos, `date` e `weekday`; em modo `fixed` o `error` nunca é emitido).
 
 ### 2.9 `set_variable`
 
@@ -621,13 +648,19 @@ O campo raiz é **`waitMode`**: `"duration"` (default), `"date"` ou `"weekday"`.
     "label": "A/B test mensagem",
     "mode": "branches",
     "branches": [
-      { "id": "A", "label": "Variante A", "weight": 50 },
-      { "id": "B", "label": "Variante B", "weight": 50 }
+      { "id": "A", "label": "Variante A", "percent": 50 },
+      { "id": "B", "label": "Variante B", "percent": 50 }
     ]
   }
 }
 ```
 
+**O campo é `percent`, NÃO `weight` (2026-07-30):** a tela sempre gravou `percent` (`randomizerBranches`
+do FlowNodeConfigModal) e o motor lia só `weight` — nenhum node configurado pela tela funcionava.
+Corrigido em 30/07: o motor lê `percent` e aceita `weight` só como dado antigo. **Escreva sempre
+`percent`** — randomizador criado com `weight` até roda, mas abre com as porcentagens EM BRANCO na
+tela do cliente (a tela lê só `percent`).
+
 **Modo `distribute_agents` (sorteio PONDERADO):** `data.mode: 'distribute_agents'` + `data.agents: [{ agent_id, percent }]` — sorteia UM agente por probabilidade (percentuais somando 100) e atribui automaticamente. Isso é SORTEIO, não rodízio: no curto prazo pode cair no mesmo agente várias vezes seguidas. Pra RODÍZIO EXATO (cada um na vez), use a AÇÃO `distribute_agents` no node `action` (ver seção 2.5) — não este modo.
 
 **Handles que SAEM:** o `id` de cada branch (`A`, `B`, ...). Em `mode: 'distribute_agents'` é `success`.

package/dist/docs/resources/glossary.md

@@ -214,7 +214,10 @@ os de `user_ids` viram membros comuns. A resposta traz `is_supervisor` (boolean)
 - `config.feature_memory`: gera notas no contato ao resolver conversas
 - `config.feature_faq`: gera FAQs sugeridas ao resolver conversas
 - `config.feature_follow_up` + `config.follow_up_steps`: follow-up automático em cadência de até
-  3 etapas (cada ≥5 min, soma ≤24h) quando o cliente some — motor dedicado só-leitura
+  3 etapas (cada ≥5 min, **soma ≤1380 min = 23h**, não 24h) quando o cliente some — motor dedicado
+  só-leitura. O teto é 1380 porque a janela de 24h do WhatsApp conta da **mensagem do cliente**, não do
+  primeiro follow-up; somar 1440 é recusado com 422 (e no campo legado `follow_up_time` a mensagem de
+  erro ainda diz "1440" por engano — o teto aplicado é 1380)
 - `config.follow_up_skip_conditions`: array (até 3, lógica OU) de condições pra NÃO fazer follow-up.
   Tipos: `label`, `contact_attr`/`conversation_attr`, e `time_window` (horário de silêncio: `start`/`end`
   horas 0-23, janela circular — no período não envia follow-up, mas a IA segue respondendo o cliente)
@@ -223,8 +226,12 @@ os de `user_ids` viram membros comuns. A resposta traz `is_supervisor` (boolean)
   com 422 "step 1 must be at least 5 minutes"). `feature_pause_on_human_reply`,
   `feature_follow_up` e demais booleans de config aceitam update direto via
   `captain_assistants_update` (merge parcial de config).
-- `config.feature_pause_on_human_reply`: bool — a IA se desliga sozinha na conversa quando um humano
-  assume (atendente responde pelo painel OU mensagem do celular); nota privada/automação/campanha não contam
+- `config.feature_pause_on_human_reply`: bool (nasce desligado) — a IA se desliga sozinha na conversa
+  quando um humano assume (atendente responde pelo painel OU mensagem do celular); nota
+  privada/automação/campanha não contam. **Mensagem agendada depende de quem agendou (2026-07-29):**
+  agendada **pela IA** não desliga (o disparo assina como o assistente); agendada **por um atendente**
+  conta como atendente ao vivo e **DESLIGA** a IA da conversa — na prática, programar uma mensagem em
+  nome do atendente numa conversa com IA ativa tira a IA dali quando ela for enviada
 - `config.model`: modelo OpenAI usado (gpt-4o, gpt-4o-mini)
 - `config.temperature`: 0.0-1.0
 - `config.instructions`: prompt sistema (Liquid template, até 20.000 chars)
@@ -373,16 +380,23 @@ Campos MUTÁVEIS (atualizáveis livremente por IA/integração): `marital_status
 
 `custom_attribute_definitions` (model=`contact_attribute`) fica reservado a dado de NEGÓCIO genérico que não tem modelo dedicado (ex: "plano contratado", "nicho do cliente").
 
-## Ligações — TRÊS sistemas distintos (não confundir!)
+## Ligações — CINCO sistemas distintos (não confundir!)
 
 | Sistema | O que é | Tools | Canal |
 |---|---|---|---|
-| **Ligação WP (Wavoip)** | Voz pelo WhatsApp em caixa **QR Code/WAHA** — QR conecta um "device" Wavoip; widget de discagem, gravação e transcrição automática | **NENHUMA — sem tool no MCP** (ver nota abaixo) | WhatsApp QR Code |
+| **Ligação WP (Wavoip)** | Voz pelo WhatsApp em caixa **QR Code/WAHA** — QR conecta um "device" Wavoip (pago, por caixa); widget de discagem, gravação e transcrição automática | **NENHUMA — sem tool no MCP** (ver nota abaixo) | WhatsApp QR Code |
+| **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 (ramais, saldo, recarga) | `voip_*` | Telefone |
+| **VoIP (Zenvia)** | Telefonia COMUM com softphone no navegador (ramais, saldo, recarga) | `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) |
 
-Quando o usuário falar "ligação", descubra o canal: caixa QR Code → Wavoip; caixa oficial →
-whatsapp_calls; telefone fixo/ramal → VoIP Zenvia.
+Quando o usuário falar "ligação", descubra o canal ANTES de responder: caixa QR Code → Wavoip **ou**
+LionCalls (dois motores diferentes para o MESMO tipo de caixa — veja qual está conectado nela); caixa
+oficial → `whatsapp_calls`; telefone/ramal → Zenvia (softphone) ou VTCall (PABX).
+
+**Histórico é compartilhado.** Wavoip, LionCalls, Zenvia e VTCall gravam na MESMA tabela de ligações,
+então `voip_calls_list` (`/voip/calls`) devolve as quatro juntas — mesmo as que não têm tool própria.
+Só o WhatsApp Calling (Cloud) fica fora, em `whatsapp_calls_*`.
 
 **Wavoip — SEM TOOL NO MCP (decisão do dono, 2026-07-16).** As 8 tools `wavoip_*` (status, token,
 calls, connect, disconnect, settings, should_ring, flag_rejected) foram REMOVIDAS dos dois conectores.

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

@@ -121,9 +121,31 @@ Um card individual dentro de uma etapa.
 | `custom_attributes` | jsonb — campos custom (igual contatos) |
 | `assigned_agents` | jsonb array de agentes responsáveis |
 | `activities` | jsonb array — log de atividades |
-| `checklist` | jsonb array de tarefas dentro do card (item: `text`/`completed`/`position` + `group_id`/`group_name` opcionais para agrupar) |
+| `checklist` | **O que fica guardado:** jsonb array de tarefas do card (item: `text`/`completed`/`position` + `group_id`/`group_name` opcionais para agrupar). **O que a API devolve é OUTRA coisa** — ver o aviso logo abaixo |
 | `timer_started_at`, `timer_duration` | Timer interno do card |
 
+> **ATENÇÃO — na maioria das respostas o `checklist` NÃO é a lista de tarefas, e sim um resumo com
+> os números:** `{ total_count, completed_count, groups: [{ group_id, group_name, total_count,
+> completed_count }] }`. Não existe nenhum `text` ali. Procurar a tarefa nesse campo faz a IA
+> concluir "esse card não tem checklist" num card que tem 12 tarefas.
+>
+> O formato **muda por ferramenta** — não é o mesmo em todas:
+>
+> | Ferramenta | `checklist` | `attachments` | `item_details.notes` / `offers` / `custom_attributes` | `activities` / `funnel` |
+> |---|---|---|---|---|
+> | `kanban_items_list` | **array completo** | `{ total_count }` | completos | ausentes |
+> | `kanban_items_show` | **resumo** | `{ total_count }` | completos | presentes |
+> | `kanban_items_filter` / `_search` | **resumo** | `{ total_count }` | `notes` vira `{ total_count }`; `offers`/`custom_attributes` **removidos** | ausentes |
+> | card embutido em `conversations_show` | **resumo** | — | — | — |
+>
+> - Para ler as tarefas de verdade em QUALQUER caso: **`lionchat_kanban_items_kanban_checklist_list`**
+>   (`GET .../kanban_items/{id}/get_checklist`) → `{ item_id, checklist: [ ...itens completos... ],
+>   checklist_count }`.
+> - No resumo, `groups` só conta o que está agrupado: tarefa **avulsa** (sem `group_id`) entra no
+>   `total_count`/`completed_count` gerais mas **não aparece** em `groups`. Somar os grupos ≠ total.
+> - O card embutido em `conversations_list`/`conversations_filter` **não traz `checklist` nenhum** —
+>   nem resumo. Só `conversations_show` traz o resumo.
+
 ### item_details (detalhes do card)
 
 ```json
@@ -326,8 +348,18 @@ qualquer agente no card (`assigned_agents`), não só ao responsável da convers
 - `conversations_list` / `conversations_search` retornam SÓ conversas de caixas acessíveis (mais as
   liberadas pela ponte de card atribuído).
 - `conversations_show` / `conversations_messages_*` de conversa inacessível → **404**.
-- Buscar card por ID ou rodar ação em massa (`kanban_bulk_bulk_actions`, export) numa caixa
-  inacessível → **404** (a ação não vaza cards de caixa que o agente não pode ver).
+- Buscar card por ID de caixa inacessível → **404** (não revela sequer que o card existe).
+- Ação em massa de CARD (`kanban_bulk_create` = mover, `kanban_bulk_create_1` = atribuir agente,
+  `kanban_bulk_create_2` = definir prioridade) em que NENHUM dos `item_ids` é acessível → **404**
+  `{ "error": "Nenhum item valido encontrado" }`. Se só PARTE for inacessível, a ação roda nos
+  acessíveis e ignora o resto em silêncio.
+- `kanban_items_export` **não dá 404** — ele filtra: exporta só os cards das caixas que o agente vê
+  (pode voltar vazio). Em nenhum dos casos a resposta vaza card de caixa sem acesso.
+
+> **Não confunda:** apesar do nome, **`kanban_bulk_bulk_actions` NÃO é ação em massa de card do
+> Kanban** — ela bate em `POST /accounts/{id}/bulk_actions`, que é a ação em massa de **conversas e
+> contatos** (`type: Conversation` ou `Contact`). Card do Kanban tem as **três** ferramentas
+> listadas acima, todas com `item_ids: [...]`, e nenhuma delas aceita etiqueta.
 
 **Pro MCP:** se uma conversa/card "some" da listagem ou dá 404 pra um agente que jura que existe,
 provavelmente é acesso por caixa — explique que ele só vê as caixas das quais participa, e que o