@lionchat/mcp-server 1.9.0 → 1.10.1

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"
 
@@ -359,6 +420,154 @@ POST /api/v1/accounts/{account_id}/automation_rules
   "event_name": "conversation_updated",
   "action_types": ["label_added"],
   "conditions": [{"attribute_key": "labels", "filter_operator": "contains", "values": ["vip"]}],
-  "actions": [{"action_name": "send_email_to_team", "action_params": {"team_ids": [1], "message": "VIP!"}}]
+  "actions": [{"action_name": "send_email_to_team", "action_params": [{"team_ids": [1], "message": "VIP!"}]}]
 }
 ```
+
+---
+
+## Condicoes de automacao — e a REGRA DO CONECTOR
+
+```json
+"conditions": [
+  {"attribute_key": "status",  "filter_operator": "equal_to", "values": ["resolved"], "query_operator": "AND"},
+  {"attribute_key": "labels",  "filter_operator": "equal_to", "values": ["vip"],      "query_operator": null}
+]
+```
+
+### O conector (`query_operator`) — leia isto antes de gravar
+
+O conector **liga a condicao com a SEGUINTE**. Logo:
+
+- A **ULTIMA** condicao **TEM** que ter `query_operator: null`.
+- Condicao **UNICA** = `query_operator: null` (nao ha proxima pra ligar).
+- Valores aceitos nas demais: `"AND"` ou `"OR"`.
+
+> **A API valida o VALOR do conector, mas NAO a POSICAO.** Conector na ultima condicao **salva com
+> sucesso**, aparece certo na tela — e a regra nunca dispara.
+>
+> Incidente real: **8 regras criadas pelo conector de IA entre 26 e 30/07/2026, em 3 contas
+> diferentes, todas com conector na ultima condicao. Todas nasceram mortas.** A pergunta ao banco
+> saia pela metade (`... IN ($1) and`), o erro era engolido e a regra respondia "nada casou". A conta
+> 62 ficou com as **6** regras de etiquetagem automatica paradas. Medido em producao em 03/08:
+> **732 erros por hora**.
+>
+> O motor foi corrigido em 03/08 (a limpeza acontece ao montar a consulta), entao regra torta nao
+> quebra mais. **Mas continue gravando certo:** a tela de edicao le o dado cru e formato errado
+> aparece estranho ali — mesmo efeito do campo de template que sumia da tela.
+
+### Campos da condicao
+
+| Campo | Obrigatorio | O que e |
+|---|---|---|
+| `attribute_key` | SIM | Campo padrao (ver abaixo) ou a chave de um atributo personalizado que **exista na conta** |
+| `filter_operator` | SIM | Como comparar |
+| `values` | SIM (menos em `is_present`/`is_not_present`) | Array, sempre |
+| `query_operator` | SIM em todas | `"AND"`/`"OR"`; **`null` na ultima** |
+| `custom_attribute_type` | so p/ atributo personalizado | `conversation_attribute` ou `contact_attribute` |
+
+### Operadores de filtro
+
+`equal_to`, `not_equal_to`, `contains`, `does_not_contain`, `is_present`, `is_not_present`,
+`is_greater_than`, `is_less_than`, `starts_with`, `days_before`, `days_ago`, `last_days`, `today`,
+`yesterday`.
+
+**Cada campo aceita so um subconjunto.** Operador que o campo nao aceita faz a regra inteira falhar
+na validacao. Na duvida, leia uma regra que ja funciona com `lionchat_automation_rules_show` e copie.
+
+### Chave que a conta nao conhece
+
+Se `attribute_key` nao for um campo padrao **nem** um atributo personalizado existente na conta, a
+regra **inteira** falha na validacao e nunca dispara — erro
+`Automation conditions <chave> not supported`. Aconteceu de verdade na conta 62 (`tipo_interesse`).
+Antes de usar atributo personalizado numa condicao, confirme que ele existe com
+`lionchat_custom_attributes_list`.
+
+---
+
+## Acoes de automacao — formato do `action_params`
+
+> **REGRA DE OURO:** `action_params` e SEMPRE um **array**, mesmo quando so tem um item.
+> O backend le `params[0]`. Passar um objeto solto (`{...}` em vez de `[{...}]`) quebra a acao.
+
+> **PERIGO — falha silenciosa:** o `action_params` e um campo livre (JSONB). A API **aceita e grava
+> qualquer formato**, sem validar. Se as chaves estiverem erradas, a regra e salva com sucesso, o
+> painel mostra a acao na tela, e na hora de disparar ela **nao faz nada e nao registra erro nenhum**
+> — sem log, sem mensagem falhada, sem aviso. Por isso: **nunca invente nome de chave**. Se a acao
+> nao estiver documentada abaixo, leia uma regra existente com `lionchat_automation_rules_show` e
+> copie o formato exato dela.
+>
+> Incidente real (conta 39, 02-03/08/2026): uma IA gravou `template_name`/`template_id` em vez de
+> `name`/`id`. A regra ficou 14 horas sem enviar nada, 9 leads pagos entraram e ninguem foi avisado.
+
+### `send_whatsapp_template` — ATENCAO ESPECIAL
+
+Envia um modelo aprovado da Meta. **So funciona em caixa WhatsApp API Oficial (Cloud).**
+
+```json
+{
+  "action_name": "send_whatsapp_template",
+  "action_params": [{
+    "name": "confirmacao_pedido",
+    "id": "1071396275361941",
+    "language": "pt_BR",
+    "category": "UTILITY",
+    "processed_params": {"body": {"1": "{{contact.first_name}}"}}
+  }]
+}
+```
+
+| Chave | Obrigatoria | O que e |
+|---|---|---|
+| `name` | **SIM** | Nome EXATO do modelo aprovado na Meta. E por ele que o envio acontece |
+| `id` | nao | ID do modelo na Meta. Serve so de reserva se `name` faltar |
+| `language` | nao (padrao `pt_BR`) | Precisa bater com o idioma do modelo aprovado |
+| `category` | nao | `UTILITY`, `MARKETING` ou `AUTHENTICATION` |
+| `processed_params` | nao | Valores das variaveis: `{"body": {"1": "...", "2": "..."}}`. Aceita Liquid (`{{contact.first_name}}`) |
+
+**NUNCA use `template_name`, `template_id`, `template_category` nem `template_language` aqui.**
+Esse e o formato dos **nos do FlowBuilder**, que e outra coisa. Na automacao, essas chaves sao
+ignoradas e a acao vira um nada silencioso.
+
+Antes de gravar, confirme que o modelo existe e esta aprovado com
+`lionchat_inboxes_whatsapp_templates_list` — o envio so acha o modelo se `name` + `language`
+casarem e o status for `approved`.
+
+### Demais acoes
+
+Todos os formatos abaixo foram conferidos linha a linha em `app/services/action_service.rb` e
+`app/services/automation_rules/action_service.rb`.
+
+| `action_name` | `action_params` |
+|---|---|
+| `send_message` | `["texto da mensagem"]` |
+| `add_private_note` | `["nota interna"]` |
+| `send_canned_response` | `[12]` — id da resposta pronta |
+| `add_label` / `remove_label` | `["etiqueta1", "etiqueta2"]` |
+| `assign_agent` | `[70]` — o agente precisa ser membro da caixa. `["nil"]` desatribui |
+| `assign_team` | `[3]`. `["nil"]` desatribui |
+| `assign_captain_assistant` | `[17]` ou `[{"assistant_id": 17, "proactive": true}]` — `proactive` false = a IA assume mas nao fala na hora |
+| `send_email_to_team` | `[{"team_ids": [1], "message": "texto"}]` |
+| `send_webhook_event` | `["https://..."]` |
+| `send_attachment` | `[blob_ids]` — so funciona se a regra ja tiver arquivo anexado; nao da pra montar so por API |
+| `change_status` | `["resolved"]`, `["open"]`, `["pending"]` ou `["snoozed"]` |
+| `change_priority` | `["urgent"]`, `["high"]`, `["medium"]`, `["low"]`. `["nil"]` limpa |
+| `send_email_transcript` | `["a@b.com,c@d.com"]` — UMA string, varios e-mails separados por virgula |
+| `mute_conversation` | `[]` |
+| `snooze_conversation` | `[]` |
+| `resolve_conversation` / `open_conversation` / `pending_conversation` | `[]` |
+| `update_contact_attribute` / `update_conversation_attribute` | `[{"attribute_key": "chave", "value": "texto ou {{contact.phone_number}}"}]` |
+| `create_kanban_item` | `[{"funnel_id": 31, "funnel_stage": "prospeccao", "allow_duplicates": false}]` |
+| `move_kanban_item_to_stage` | `[{"funnel_id": 31, "funnel_stage": "qualificacao"}]` |
+| `assign_agent_to_kanban_item` | `[{"funnel_id": 31, "agent_id": 70, "mode": "add"}]` — `mode` aceita `add` (padrao) ou `remove_all` |
+| `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}]` |
+
+**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.
+
+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
+acao de automacao valida (e so do FlowBuilder) — usar aqui devolve 422.

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),
@@ -388,11 +396,12 @@ Booking (agendamento confirmado)
 
 ## e-Clínicas (Efficient) — integração de clínicas
 
-9 eventos de webhook, cada um mapeável a automação OU flow na tela Integrações > e-Clínica:
+13 eventos de webhook, cada um mapeável a automação OU flow na tela Integrações > e-Clínica:
 `cliente_novo`, `agendamento_novo`, `falta`, `pagamento` (os 4 da doc oficial) +
 `agendamento_atendido`, `agendamento_alterado`, `agendamento_desmarcado`,
-`agendamento_transferido`, `cliente_baixa_pagamento` (capturados ao vivo, não documentados
-pelo e-Clínica).
+`agendamento_transferido`, `cliente_baixa_pagamento`, `cliente_alteracao`,
+`cliente_inclusao_pagamento`, `controle_laboratorio_novo`, `controle_laboratorio_alterado`
+(capturados ao vivo, não documentados pelo e-Clínica).
 
 Atributos de sistema no CONTATO (prefixo `eclinica_`, protegidos, usáveis como variável):
 

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