@lionchat/mcp-server 1.32.0 → 1.34.0

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

@@ -752,7 +752,7 @@ Pra auditar o que foi/será disparado, use `lionchat_eclinica_reminder_history_l
 **Um aviso por CONSULTA (desde 2026-09-17).** A regra antiga "um lembrete por dia" saiu: paciente com duas
 consultas no mesmo dia — ou duas pessoas no mesmo celular (mãe e filho) — recebe um lembrete para CADA
 consulta, cada um com o seu nome, horário, profissional e link. Eles não saem juntos: sai o da consulta
-mais cedo e, ~10 minutos depois (na rodada seguinte), o da próxima. No histórico
+mais cedo e, ~2 minutos depois (desde 26/10/2026 a rotina roda de minuto em minuto; o irmão espera a janela de 120 s), o da próxima. No histórico
 (`lionchat_eclinica_reminder_history_list`) isso aparece assim: o que espera a vez fica `pending` com
 `fire_at` no passado por alguns minutos (normal); `skip_reason = outra_consulta_no_mesmo_dia` só existe em
 linhas ANTIGAS (até 17/09); e `fail_reason = fluxo_ainda_em_andamento_com_este_contato` significa que o

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

@@ -197,16 +197,29 @@ SEM mudar nenhum número antigo (Ganhos e Receita continuam do vendedor):
 |---|---|---|
 | `any` (PADRÃO) | criado no período **OU** fechado no período | É a régua histórica e a mais larga. **Omitir mantém exatamente os números de sempre.** É a certa pra RECEITA: com qualquer outra, venda fechada no período de um lead antigo some (medido 07/08: 17% dos ganhos da frota) |
 | `created` | só quando o card nasceu | "quantos leads entraram" |
-| `moved` | só quando entrou na etapa atual (mesma expressão do `stage_date_*` da seção 3) | "o que se mexeu no período" |
+| `moved` | quando entrou numa etapa (período até hoje: a etapa atual, mesma expressão do `stage_date_*` da seção 3; período que já terminou: qualquer entrada registrada no período, mesmo que o card tenha andado de novo depois) | "o que se mexeu no período" |
 | `closed` | só ganhos/perdidos no período | **a pergunta de receita** — é a régua certa pra "quanto vendemos em julho" |
 
 **Ganho/perda pela DATA DO FECHAMENTO (23/09/2026).** Com a régua `any` o relatório traz também cards que
 nasceram no período mas fecharam DEPOIS dele. Por isso, para "quanto ganhamos/perdemos em julho", leia
-`wonInPeriod`/`wonValueInPeriod` e `lostInPeriod`/`lostValueInPeriod` (este último é campo NOVO) — **nunca**
-`statusDistribution`, que é a foto do status de HOJE (serve só para "negócios abertos agora"). Desde 23/09 os
+`wonInPeriod`/`wonValueInPeriod` e `lostInPeriod`/`lostValueInPeriod` (este último é campo NOVO). Desde 23/09 os
 motivos de ganho/perda, os perdidos recentes, a receita por semana e o ranking de vendedores também contam só
 o que FECHOU no período — antes somavam por status de hoje e divergiam do quadro de Ganhos na mesma tela.
 
+**Situação no FIM do período (19/10/2026).** Num período que JÁ TERMINOU (pelo dia da conta), tudo que é
+SITUAÇÃO sai como o card estava no último instante do período: `statusDistribution` (aberto/ganho/perdido/adiado),
+`itemsByStage`/`itemsByStageSlug` (o "Funil — ocupação por etapa"), `stageMetrics.valueByStage`, `forecast`,
+`topDeals`, `staleCards`, `agingAnalysis` e `stageVelocityData` (só abertos) e os "parados" por etapa. Período que
+vai até HOJE = o estado de agora (números de sempre). Por isso `statusDistribution.won` passa a bater com
+`wonInPeriod`. Campo NOVO `periodEndState` `{past, unknownStageCount, removedStageCount}`: se `unknownStageCount > 0`,
+avise que esses cards aparecem como "Etapa desconhecida" (sem histórico daquela época — o histórico de etapas
+começou em julho de 2026); as chaves cruas `:etapa_desconhecida`/`:etapa_removida` NUNCA devem ser mostradas ao
+cliente — traduza para "Etapa desconhecida"/"Etapa removida". Card ganho/perdido conta no funil onde a venda
+aconteceu (também quando foi transferido depois). `taskMetrics.overdue`/`upcoming7days` vêm `null` num período
+passado — NÃO diga "nenhuma atrasada", diga que esse número só existe para períodos que vão até hoje. Ciclo de vendas
+e "Tempo médio" só com ganhos do período; checklist e follow-up só com o que fechou no período (follow-up = ações
+feitas por pessoa até ganhar/perder, não dias).
+
 O relatório de UMA etapa — tool `lionchat_funnels_stage_report` (`GET /funnels/:id/stage_report`, o
 painel que abre dentro do quadro) — tem as MESMAS 4 opções de régua, mesmo parâmetro `date_basis` e as
 MESMAS expressões da seção 3, mas o **padrão dele é `moved`**, não `any`. Não é inconsistência: ele
@@ -216,7 +229,9 @@ que as duas telas não batem, a resposta é: escolha a MESMA régua nas duas.
 
 Ela devolve números calculados no SERVIDOR (total de cards da etapa, faixa de valores, ganhos/perdidos,
 distribuição por prioridade, ranking de vendedores da etapa) — antes a tela só somava os cards já
-carregados na coluna.
+carregados na coluna. Num período que JÁ TERMINOU (19/10/2026) ela responde quantos cards ESTAVAM na etapa no fim do
+período, e os botões `show_*`/`statuses`/`stages` valem pela situação naquele dia (um card aberto no fim do período e
+ganho depois aparece com o padrão "só abertos").
 
 **Parâmetros de `lionchat_funnels_stage_report`:**
 
@@ -250,9 +265,12 @@ categoria: 15/página (kanban: primeiros 15, sem paginação).
   lista/show pesadas). Anexos de mensagem (data_url/download_url) NUNCA são podados.
 - **Segredos:** chaves de credencial (api_key, tokens, senhas) saem SEMPRE como `[REDACTED]` —
   sem exceção, nem com full_response. Precisa de um token? Painel, não robô.
-- **Paginação:** os DOIS conectores agora informam `pagination.{current_page,total_pages,
-  total_count,has_more}` — pagine até `has_more=false`. (No remoto o bloco é ADICIONADO ao lado
-  do shape original.)
+- **Paginação:** nas listas que paginam por página, os DOIS conectores informam
+  `pagination.{current_page,total_pages,total_count,has_more}` — pagine até `has_more=false`. (No
+  remoto o bloco é ADICIONADO ao lado do shape original.) Lista que NÃO pagina por página vem SEM
+  `pagination` e com o `meta` do servidor intacto: mensagens de uma conversa (volte com `before_id` =
+  id da mais antiga recebida) e agentes de ligação (lista inteira; `meta.dial_inboxes` = caixas que
+  ligam). Ausência do bloco NÃO quer dizer "acabou" nas mensagens.
 - **Corte:** resposta acima do teto é enxugada por ITENS INTEIROS (aviso `[LISTA ENXUGADA...]`
   com contagem exibida/total) — o JSON nunca vem quebrado no meio.
 

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

@@ -62,7 +62,7 @@ Todo node tem essa estrutura base:
 
 **ATENÇÃO — chave `items`, não `triggers` (corrigido 19/08/2026).** Os gatilhos vão em **`data.items`**, cada item no formato **`{ "key": "...", "config": { ...filtros... } }`**. O formato antigo (`data.triggers` + `type` + filtros soltos no topo) ainda é aceito pelo motor por compatibilidade, mas **NÃO deve ser usado em fluxo novo**: o editor do FlowBuilder lê apenas `data.items`, então um fluxo gravado no formato antigo **dispara normalmente mas abre com o bloco Início EM BRANCO no painel do cliente** — e um clique em "Concluir" naquele modal apagava o gatilho em silêncio. Foram 53 fluxos de 9 contas nesse estado até o conserto de 19/08. Alguns leitores do backend (`has_webhook_trigger?` do disparo por webhook, o filtro de Campanha de Fluxo, o gatilho LionTrack e o histórico de execução) também só entendem `items`.
 
-**Triggers válidos:** `message_received`, `message_sent`, `conversation_created`, `conversation_resolved`, `conversation_reopened`, `team_changed`, `assignee_changed`, `label_added`, `label_removed`, `sla_missed`, `card_created`, `card_moved`, `card_won`, `card_lost`, `card_opened`, `card_snoozed`, `conversation_attribute_changed`, `card_attribute_changed`, `contact_attribute_changed`, `date_trigger`, `campaign_trigger`, `manual_trigger`, `webhook_received`, `page_track`, `group_participant_joined`, `group_participant_left`, `lead_form_completed`, `lead_form_milestone`, `lead_form_abandoned`, `booking_created`, `booking_cancelled`, `booking_rescheduled`, `booking_completed`.
+**Triggers válidos:** `message_received`, `message_sent`, `conversation_created`, `conversation_resolved`, `conversation_reopened`, `team_changed`, `assignee_changed`, `label_added`, `label_removed`, `sla_missed`, `card_created`, `card_moved`, `card_won`, `card_lost`, `card_opened`, `card_snoozed`, `card_open_in_stage`, `card_open_in_funnel`, `conversation_attribute_changed`, `card_attribute_changed`, `contact_attribute_changed`, `date_trigger`, `campaign_trigger`, `manual_trigger`, `webhook_received`, `page_track`, `group_participant_joined`, `group_participant_left`, `lead_form_completed`, `lead_form_milestone`, `lead_form_abandoned`, `booking_created`, `booking_cancelled`, `booking_rescheduled`, `booking_completed`.
 
 **NÃO existem** os gatilhos `webhook` (o correto é **`webhook_received`**) nem `cron` (para disparo por data use `date_trigger`; para disparo em lote use `campaign_trigger` + Campanha de Fluxo). Até 19/08/2026 este guia listava os dois por engano — o fluxo 180 da conta 54 ficou ATIVO com `webhook` e **nunca disparou uma vez em 26 dias**, sem erro nenhum.
 
@@ -75,6 +75,13 @@ Todo node tem essa estrutura base:
 - `card_created` / `card_moved`: `funnel_ids` (array de STRINGS, ex.: `["37"]` — número puro `[37]` NÃO casa) + `funnel_stages` (array de `"funnel_id:chave_da_etapa"`, ex.: `"37:agendamento_pendente"`). A `chave_da_etapa` é a CHAVE INTERNA da etapa no funil (slug legível em funis de template; pode ser um UUID/`stage_<n>` em etapa criada à mão ou funil duplicado) — NÃO o nome exibido na tela. Sem `funnel_ids` → dispara em qualquer funil; com `funnel_ids` mas sem `funnel_stages` → qualquer etapa daquele(s) funil(is). O card precisa estar num funil listado em `funnel_ids` pra o filtro de etapa valer. ATENÇÃO: dois flows ATIVOS na mesma inbox com `card_created`/`card_moved` de funil/etapa sobrepostos são bloqueados na criação/ativação (ver `flow_trigger_conflict` no fim deste guia).
 - `team_changed`: `team_ids` (array de STRINGS; vazio = qualquer equipe). `assignee_changed`: `agent_ids` (array de STRINGS; vazio = qualquer atendente). `card_won` / `card_lost`: `funnel_ids` (array de STRINGS) — disparam SÓ quando o STATUS do card vira ganho/perdido, nunca por etapa com esse nome.
 - `card_opened` ("Card aberto") / `card_snoozed` ("Card adiado") — NOVOS 11/10/2026, mesma config `funnel_ids` (array de STRINGS; vazio = qualquer funil). `card_snoozed` dispara quando o card é ADIADO. `card_opened` dispara quando um card adiado ABRE (pela data, por alguém ou por automação) e também quando um card ganho/perdido é REABERTO — card NOVO não dispara (para isso existe `card_created`). Pela data, o fluxo sai pela fila de disparos agendados, uma vez por card. Use `{{trigger.kanban.previous_status}}` (`snoozed`/`won`/`lost`) para separar "voltou do adiamento" de "reabriram um ganho/perdido".
+- `card_open_in_stage` ("Card aberto na etapa") / `card_open_in_funnel` ("Card aberto no funil") — NOVOS 28/10/2026, gatilhos de **PRAZO**: disparam o fluxo UMA vez quando o card cruza um prazo ("lead parado"). Item: `{ "key": "card_open_in_stage", "config": { "funnel_ids": ["12"], "funnel_stages": ["12:novo_lead"], "duration_value": 1, "duration_unit": "hours" } }`; `card_open_in_funnel` tem a mesma config **sem** `funnel_stages`. `funnel_ids` (array de STRINGS) vazio = qualquer funil; `funnel_stages` (`"<funil>:<chave_da_etapa>"`) vazio = qualquer etapa. `duration_unit` = `minutes`|`hours`|`days`; `duration_value` inteiro (ou texto de inteiro, ex.: `"2"`); o servidor recusa (422) prazo fora de **15 minutos a 365 dias**, unidade desconhecida e funil de outra conta.
+  - **Relógio:** `card_open_in_stage` conta o tempo desde que o card ENTROU na etapa atual (o SEGUNDO número do "2d / 1d" do card no quadro; trocar de funil também recomeça). `card_open_in_funnel` conta a idade do card desde a criação (o PRIMEIRO número, "2d"; trocar de funil NÃO recomeça).
+  - **Quem conta:** card ABERTO ou ADIADO; ganho e perdido nunca. Dispara **uma vez por entrada na etapa** (`card_open_in_stage`: sai e volta = conta do zero) e **uma vez por card** (`card_open_in_funnel`).
+  - **Só dispara quem CRUZA o prazo com o fluxo ligado.** Card que já passou do prazo quando o fluxo foi ligado NÃO dispara (nem depois); com prazo de 5 dias, o card que está com 4 dispara ao chegar a 5. Mudar o prazo, o funil ou a etapa do gatilho vale como gatilho NOVO: só cruzamentos depois da mudança disparam. Relógio corrido (noite e fim de semana contam); a conferência roda de 5 em 5 minutos, então o fluxo pode começar até ~5 min depois do prazo.
+  - **Onde roda:** inicia SÓ o fluxo dono do gatilho, em cada conversa do card (card sem conversa não dispara). O card que disparou é o "card do gatilho": `card_source: 'trigger'` funciona e as condições "Card na etapa" / "Card adiado" olham para ele. Variáveis `{{trigger.kanban.title}}`, `.funnel_name`, `.stage_name`, `.stage` valem como nos outros gatilhos de card; `{{trigger.type}}` = a própria chave (`card_open_in_stage` / `card_open_in_funnel`).
+  - Dois fluxos com o mesmo gatilho na mesma caixa são permitidos (não há checagem de conflito): os dois disparam.
+  - Exemplo — avisar um grupo de WhatsApp quando o lead passa mais de 1 hora na etapa do vendedor: Início `card_open_in_stage` (1 hora, funil + etapa) → (opcional) condição "Card na etapa" → bloco `update_group` com a operação de enviar mensagem ao grupo, texto usando `{{agent.name}}` e o link da conversa `https://<host>/app/accounts/<id_da_conta>/conversations/{{conversation.id}}`.
 - `page_track` (LionTrack, só flow individual): `{ "track_type": "visited_page"|"event_fired", "urls": [...], "operator": "contains"|"exact"|"starts_with", "event_names": [...], "event_operator": "equals"|"contains", "cooldown_hours": 24 }` — `cooldown_hours` (padrão 24, mínimo 1) não re-dispara pro mesmo contato dentro da janela.
 - `conversation_attribute_changed` / `card_attribute_changed` (novo 2026-07-08): disparam na VIRADA de um atributo (da CONVERSA ou do CARD do kanban) pro valor que casa — RE-ENTRAM toda vez que o atributo muda pro valor alvo. Config: `{ "logic": "and"|"or", "rules": [ { "attr_key": "...", "operator": "...", "value": "..." } ] }` (uma rule pode usar `values: [...]` no lugar de `value` pra multi-valor). O `attrSource` é IMPLÍCITO pela chave do gatilho (conversa vs card) — NÃO informe. Operadores (contexto REATIVO — desde 09/07 `is_empty`/`is_not_empty` NÃO valem aqui, pois "está vazio AGORA" dispararia a cada evento; use-os só no nó Condição): `equal`/`not_equal`/`contains`/`not_contains`/`starts_with`/`ends_with`/`greater_than`/`less_than`/`number_range`. Só `card_attribute_changed` aceita `funnel_id`/`card_source` opcionais dentro da rule (pra achar o card). Rule sem `attr_key` é ignorada.
 - `contact_attribute_changed` (novo 2026-07-22 — "Atributo do contato muda"): dispara quando um atributo personalizado do **CONTATO** muda e a condição casa — mesmo com o contato fora de flow. Item: `{ "key": "contact_attribute_changed", "config": { "logic": "and"|"or", "rules": [ { "attrSource": "contact", "attr_key": "...", "operator": "...", "value": "..." } ] } }` (1 a 10 rules; `values: [...]` pra multi-valor). **DIFERENTE dos irmãos de 08/07: aqui o `attrSource` VAI na rule e é SEMPRE `"contact"`.** Operadores iguais aos do nó Condição. **VERSÃO SEGURA por decisão de produto:** dispara SÓ na conversa mais recente que JÁ EXISTE numa caixa do flow (reabre se resolvida); contato sem conversa NÃO dispara e NUNCA cria conversa. Dedup de 30s por contato + anti-loop por profundidade de cadeia (flow que muda atributo que dispara flow…). Só flows de conversa.
@@ -156,7 +163,7 @@ Webhooks embutidos NÃO aparecem na listagem de integrações standalone; exclui
 **Gatilhos de AGENDAMENTO — Booking NATIVO do LionChat (2026-08-20):** `booking_created` (alguém marcou pelo link público, pela IA ou pelo painel), `booking_cancelled` (paciente cancelou pelo link, IA cancelou ou a equipe cancelou na Agenda), `booking_rescheduled` (a data/hora mudou — link do paciente, IA, editar/adiar na Agenda), `booking_completed` (equipe concluiu na Agenda; exige a Agenda unificada ligada na conta). **Não é e-Clínica.** Config (tudo opcional, vazio = todos): `booking_event_type_ids` (array de ids de tipo de agendamento, **STRING**), `agent_ids` (array de ids de usuário — o RESPONSÁVEL da tarefa), `create_conversation` (boolean, padrão `false`: só dispara para quem já tem conversa numa caixa do flow; `true` = cria a conversa na 1ª caixa do flow). Exemplo: `{ "key": "booking_created", "config": { "booking_event_type_ids": ["44"], "agent_ids": [], "create_conversation": true } }`. São INERTES a evento de conversa (quem dispara é o `Booking::FlowTriggerDispatcher`, por CONTA — caixa do flow só define onde a conversa é criada/reusada). Variáveis no flow: `{{booking.date}}` (DD/MM/AAAA), `{{booking.time}}`, `{{booking.weekday}}`, `{{booking.datetime}}` (ISO), `{{booking.type}}`, `{{booking.type_format}}` (presencial/videochamada), `{{booking.duration}}`, `{{booking.agent}}`, `{{booking.status}}` (confirmado/cancelado/remarcado/concluído), `{{booking.description}}`, `{{booking.cancel_url}}`, `{{booking.reschedule_url}}`, `{{booking.confirm_url}}`, `{{booking.calendar_url}}` (16/10: página onde o cliente salva o compromisso na agenda DELE, sem e-mail; no remarcado já sai com a hora nova — é o jeito de avisar a mudança, pedindo para apagar o compromisso antigo), `{{booking.color}}`, `{{booking.id}}`; só no remarcado: `{{booking.previous_date}}`, `{{booking.previous_time}}`, `{{booking.previous_datetime}}`; `{{booking.meeting_url}}` NÃO vem no criado (nasce vazio). Data/hora vêm da TAREFA da Agenda (sempre atuais). Regras: o evento mais novo SUBSTITUI a rodada ativa do mesmo flow na mesma conversa (2ª consulta do mesmo paciente, ou cancelado chegando com o criado ainda esperando resposta); excluir a tarefa, reabrir cancelada ou desfazer conclusão NÃO disparam; adiar (snooze) conta como remarcado; tipo com confirmação/lembrete próprios ligados + `booking_created` = o paciente pode receber duas mensagens (a tela avisa). Colisão entre flows é por CONTA: mesmo kind + tipos se cruzando + agentes se cruzando (vazio = todos). Há também `{{booking.event}}` (`created`|`cancelled`|`rescheduled`|`completed` — bom pra condição; não aparece no seletor da tela, mas resolve); `{{trigger.type}}` = a chave do gatilho (ex.: `booking_created`), `{{trigger.kind}}` = `created`|`cancelled`|`rescheduled`|`completed` e `{{trigger.booking_id}}`. SÓ flow de conversa **individual** (a tela nem oferece em flow de grupo); **nunca dispara flow `ai_tool`**. Em caixa WhatsApp OFICIAL, conversa criada nova (ou parada há mais de 24h) está FORA da janela — texto livre no 1º bloco cai em `window_closed`/erro; comece por template.
 
 **TRAVA DE GATILHO DUPLICADO (2026-06-16) — leia ANTES de ativar/criar flow ativo:** o sistema BLOQUEIA ter dois flows ATIVOS com o MESMO gatilho na MESMA inbox e mesmo `conversation_mode` (evita o evento disparar dois flows). Colisão = mesmo tipo de gatilho + config cruzando (mesmas keywords/funil/labels/url/etc) + inbox compartilhada + mesmo modo. EXCEÇÕES que podem coexistir: `webhook_received`, `manual_trigger` e `campaign_trigger` (este último porque não dispara por evento — é só uma autorização para a campanha).
-- **`date_trigger` separa por HORÁRIO (24/09/2026):** dois flows no mesmo campo de data, mesma direção e mesmos dias NÃO colidem se os dois tiverem horário FIXO diferente (ex.: "1 dia depois às 08:00" e "às 14:00"). Horário vindo de atributo/fórmula continua colidindo (só existe na hora do disparo); `send_time` vazio conta como 09:00 e "8:00" = "08:00". A entrega é de 10 em 10 minutos — horários a menos de 10 min podem sair juntos.
+- **`date_trigger` separa por HORÁRIO (24/09/2026):** dois flows no mesmo campo de data, mesma direção e mesmos dias NÃO colidem se os dois tiverem horário FIXO diferente (ex.: "1 dia depois às 08:00" e "às 14:00"). Horário vindo de atributo/fórmula continua colidindo (só existe na hora do disparo); `send_time` vazio conta como 09:00 e "8:00" = "08:00". A entrega é de minuto em minuto (desde 26/10/2026) — horários no mesmo minuto saem juntos.
 - Ao **ativar** (`flows_toggle` inativo→ativo) ou **criar já ativo**: qualquer conflito é barrado.
 - Ao **editar** um flow já ativo: só conflito NOVO é barrado (duplicados que já existiam são preservados).
 - A API responde **422** com `{ "error_code": "flow_trigger_conflict", "conflicts": [{ flow_id, flow_name, trigger_type, inbox_id, inbox_name }] }`.
@@ -460,9 +467,34 @@ campanha"):
   (origem unificada), `ctwa_*` (anúncio click-to-WhatsApp: `ctwa_ad_id`, `ctwa_ad_title`, `ctwa_campaign_name`,
   `ctwa_adset_name`...), `meta_lead_*` (formulário Meta Lead Ads), `lt_*` (LionTrack: UTMs, página, dispositivo).
   Veja a lista real com `lionchat_custom_attributes_list` (`attribute_model: conversation_attribute` — com o sufixo; só `conversation` devolve a lista VAZIA —, `include_system: true` — as chaves de campanha são atributos de sistema).
-- **Valores fechados** de `origin_kind` (e `origin_first_kind`/`origin_last_kind`): `paid_ad` (Anúncio),
-  `lead_form` (Formulário), `organic` (Orgânico), `direct` (Direto), `referral` (Indicação), `manual` (Origem
-  cadastrada). O painel mostra o rótulo em português, mas a comparação é pelo VALOR — `"Anúncio"` nunca casa.
+- **Valores fechados** de `origin_kind` (e `origin_first_kind`/`origin_last_kind`): `paid_ad` (Anúncio (clique)),
+  `lead_form` (Anúncio (formulário)), `organic` (Orgânico), `direct` (Direto), `referral` (Indicação),
+  `agendamento` (Página de agendamento), `formulario` (Formulário do site), `manual` (Origem cadastrada). O painel
+  mostra o rótulo em português, mas a comparação é pelo VALOR — `"Anúncio"` nunca casa.
+- **Desde 26/10/2026, o formulário do mesmo anúncio continua formulário:** quando a pessoa preenche o formulário do
+  Meta e depois clica no MESMO anúncio para abrir o WhatsApp, a conversa fica com `origin_kind: "lead_form"` (antes
+  virava `paid_ad`). Conversas anteriores a 26/10 não mudam.
+
+**"Veio de anúncio pago" — chave `origin_paid` (25/10/2026). USE ESTA para "só lead de anúncio":**
+`origin_kind equal paid_ad` deixa de fora quem veio pelo FORMULÁRIO do anúncio (`lead_form`) — foi o defeito real da
+Cast (conta 137, fluxo 590: a IA nunca ligou para os leads de formulário de 08/10 a 24/10). A chave `origin_paid` junta
+as duas portas do anúncio. Forma que a tela grava (reabre no card "Veio de anúncio pago", Sim/Não):
+
+```json
+{ "id": "c1", "valueType": "attr_config", "attrSource": "conversation", "attrScope": "origin_paid",
+  "attr_key": "origin_paid", "operator": "equal", "value": "", "values": ["paid"] }
+```
+
+- Sim = `operator: "equal"`; Não = `operator: "not_equal"` (inclui conversa sem origem e origem cadastrada a mão).
+- Valores possíveis (calculados na hora, nunca gravados): `paid` (`paid_ad` ou `lead_form`), `not_paid` (orgânico,
+  direto, indicação, página de agendamento, formulário do site), `unknown` (`manual` ou tipo desconhecido — nunca é
+  tratado como pago), `unclassified` (sem origem ainda).
+- É chave VIRTUAL: não existe em `custom_attributes`, não aparece em `lionchat_custom_attributes_list`, não serve em
+  `{{conversation.custom_attribute.origin_paid}}` nem como gatilho "atributo mudou". Só em condição (fluxo e
+  automação) e no filtro de conversas.
+- A mesma pergunta existe na automação (condição `origin_paid`, operadores `equal_to`/`not_equal_to`), no filtro de
+  conversas (`lionchat_conversations_filter`) e no relatório de origem (`paid` e `by_paid` em
+  `lionchat_lead_origin_reports`).
 - `origin_platform` (e first/last): `facebook`, `instagram`, `google`, `tiktok`, `linkedin`, `youtube`,
   `whatsapp`, `email`, `messenger`, `audience_network` (Rede de parceiros da Meta, desde 29/09/2026), `direct` — e, para origem cadastrada pelo cliente em Configurações > Origens de Lead,
   `custom:<slug>` (slug = nome parametrizado, ex.: "Indicação de amigo" → `custom:indicacao-de-amigo`;
@@ -472,7 +504,8 @@ campanha"):
   "operator": "equal", "value": "paid_ad", "valueType": "variable" }` — reabre no card "Variável", não no de
   campanha. Prefira o formato `attr_config` acima quando o cliente vai editar pela tela.
 - Caso real (Cast, 01/09): flow "Ativar IA" só para lead de anúncio = condição `origin_kind equal paid_ad`
-  na saída `cond_0` + ação `assign_captain` nessa saída; `default` sem nada.
+  na saída `cond_0` + ação `assign_captain` nessa saída; `default` sem nada. **Desde 25/10 use `origin_paid equal paid`
+  (seção acima)**: `origin_kind equal paid_ad` não pega o lead do formulário do anúncio.
 
 - **`attrScope: "lead_origin"` (02/09/2026):** preset "Origem do lead" da aba Conversas — mesmo shape do `campaign_attr`, ja nasce com `attr_key: "origin_platform"`. Valores: plataformas fixas (`facebook`, `google`...) ou origem cadastrada como `custom:<slug>`. O motor ignora `attrScope`; sem ele a regra reabre como "Atributo de campanha" (falha macia).
 
@@ -570,21 +603,21 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 | `send_conversion` (novo 2026-09-01; `event_names` 2026-09-02; `messaging_event_names` 2026-09-10) | `{ destinations: ['meta'\|'ga4'\|'google_ads'], event_names: { meta?, google_ads?, ga4? }, messaging_event_names: { meta? }, event_name (reserva), value? }` | Manda o evento de conversão pro Meta (CAPI), Google Ads e/ou GA4 — o mesmo caminho do Funil, de dentro do fluxo. Aba Sistema (só flow `conversation`). Ver bloco próprio abaixo |
 | `deactivate_flow` ou `disable_flow` | `{}` | Encerra fluxo atual |
 | `set_booking_situation` (novo 2026-09-14) | `{ situation: 'cancelled' \| 'completed' \| 'attended' \| 'no_show' \| 'confirmed' }` | Muda a situação do agendamento **que disparou o fluxo** (gatilho de agendamento do bloco Início, ou fluxo ligado na configuração do tipo de agendamento). Aba **Agenda** (só flow `conversation`, só com a Agenda ligada na conta). Disparado por outra coisa: **não faz efeito e o passo fica com erro visível** (não há como adivinhar o agendamento). Já no estado pedido = passo PULADO, sem escrita (sem evento, sem laço). `cancelled` cancela o **agendamento** (desarma lembretes, invalida o link de gerenciar). Origem gravada = `fluxo`, ator = o próprio flow. Sem `rescheduled`/`snoozed`: o bloco não mexe em data |
-| `create_account_task` (novo 2026-10-20) | `{ title, description?, task_type, agenda_id?, priority?, occupies_agenda?, due: {amount, unit: 'hours' \| 'days', at?, business_days?}, responsible: {mode: 'card_owner' \| 'fixed' \| 'funnel_rotation' \| 'team_rotation', user_id?, team_id?, fallback_user_id?}, card_source: 'funnel' \| 'trigger', funnel_id? }` | "Criar tarefa": cria uma tarefa COMUM da Agenda, presa ao card do fluxo (ou só à conversa, se não houver card). Os campos de `title` a `responsible` são os MESMOS da ação `create_task` da automação do funil (ver `kanban-deep-dive`). Aba **Agenda**; exige a Agenda unificada ligada na conta. **NÃO roda em fluxo `ai_tool` nem em fluxo de grupo** (o motor recusa com erro visível no passo; o save aceita, a tela esconde o item). Detalhes logo abaixo |
+| `create_account_task` (novo 2026-10-20) | `{ title, description?, task_type, agenda_id?, priority?, occupies_agenda?, duration_minutes?, due: {amount, unit: 'hours' \| 'days', at?, business_days?}, responsible: {mode: 'card_owner' \| 'fixed' \| 'funnel_rotation' \| 'team_rotation', user_id?, team_id?, fallback_user_id?}, card_source: 'funnel' \| 'trigger', funnel_id? }` | "Criar tarefa": cria uma tarefa COMUM da Agenda, presa ao card do fluxo (ou só à conversa, se não houver card). Os campos de `title` a `responsible` são os MESMOS da ação `create_task` da automação do funil (ver `kanban-deep-dive`). Aba **Agenda**; exige a Agenda unificada ligada na conta. **NÃO roda em fluxo `ai_tool` nem em fluxo de grupo** (o motor recusa com erro visível no passo; o save aceita, a tela esconde o item). Detalhes logo abaixo |
 | `update_attribute` | `{ attr_source: 'contact'\|'conversation'\|'card', attr_key, attr_value }` | Seta custom_attribute (ver abaixo) |
 | `assign_captain` (ou `assign_captain_assistant`) | `{ assistant_id }` | Atribui IA Captain |
 | `deactivate_captain` | `{}` | Tira a IA da conversa |
 
 **Handles que SAEM:** `success`. Não tem handle `error` — falhas viram warning silencioso e o flow continua.
 
-**`card_source` (blocos de card) — opcional:** as ações de card aceitam `card_source`: `'funnel'` (default — procura o card pelo `funnel_id`) ou `'trigger'` (usa o card que DISPAROU o flow, em flows iniciados por `card_created`/`card_moved`/`card_won`/`card_lost`/`card_opened`/`card_snoozed`). Com `'trigger'`, `funnel_id` deixa de ser obrigatório — EXCETO em `move_kanban_stage`/`create_kanban_item`, cujo funil/etapa são o DESTINO. Sem card-gatilho disponível, a ação é pulada (não cai no fallback de funil). Aplica-se a `move_kanban_stage`, `set_won`/`set_lost`/`set_open`, `snooze_kanban_item` (esta, sem card-gatilho, dá ERRO em vez de pular), `assign_agent_card`, `add_card_note`, `add_card_checklist`, `add_card_offer`, `create_account_task` (aqui sem card-gatilho = ERRO; ver abaixo), `update_attribute` (com `attr_source: 'card'`) e às condições `card_attr_equals`/`card_attr_contains` (gravando `card_source` na própria regra).
+**`card_source` (blocos de card) — opcional:** as ações de card aceitam `card_source`: `'funnel'` (default — procura o card pelo `funnel_id`) ou `'trigger'` (usa o card que DISPAROU o flow, em flows iniciados por `card_created`/`card_moved`/`card_won`/`card_lost`/`card_opened`/`card_snoozed`/`card_open_in_stage`/`card_open_in_funnel`). Com `'trigger'`, `funnel_id` deixa de ser obrigatório — EXCETO em `move_kanban_stage`/`create_kanban_item`, cujo funil/etapa são o DESTINO. Sem card-gatilho disponível, a ação é pulada (não cai no fallback de funil). Aplica-se a `move_kanban_stage`, `set_won`/`set_lost`/`set_open`, `snooze_kanban_item` (esta, sem card-gatilho, dá ERRO em vez de pular), `assign_agent_card`, `add_card_note`, `add_card_checklist`, `add_card_offer`, `create_account_task` (aqui sem card-gatilho = ERRO; ver abaixo), `update_attribute` (com `attr_source: 'card'`) e às condições `card_attr_equals`/`card_attr_contains` (gravando `card_source` na própria regra).
 
 **`create_account_task` — Criar tarefa (2026-10-20):**
 
 ```json
 { "key": "create_account_task", "config": {
   "title": "Ligar para {{contact.name}}", "description": "", "task_type": "call", "agenda_id": null,
-  "priority": "none", "occupies_agenda": false,
+  "priority": "none", "occupies_agenda": false, "duration_minutes": 45,
   "due": { "amount": 3, "unit": "days", "at": "09:00", "business_days": true },
   "responsible": { "mode": "card_owner", "fallback_user_id": 12 },
   "card_source": "trigger", "funnel_id": ""
@@ -592,14 +625,15 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 ```
 
 - **Os campos da regra** (`title`, `description`, `task_type`, `agenda_id`, `priority`, `due`, `responsible`,
-  `occupies_agenda`) têm o mesmo formato e os mesmos limites da ação `create_task` do funil: `title` obrigatório; `due`
+  `occupies_agenda`, `duration_minutes`) têm o mesmo formato e os mesmos limites da ação `create_task` do funil: `title` obrigatório; `due`
   em horas (1 a 720) ou dias (0 a 365, com `at` "HH:MM" e `business_days` só em dias); `responsible.mode` com a chave
   obrigatória do modo (`fallback_user_id`, `user_id` ou `team_id`; `funnel_rotation` não pede nenhuma no save,
   mas no fluxo SEM card o rodízio do funil não tem funil e cai na pessoa reserva `fallback_user_id` — sem reserva a
   tarefa não nasce, com o motivo no histórico: mande `fallback_user_id` se o fluxo puder rodar sem card). Regra torta =
   passo VERMELHO com a frase do campo a consertar, sem tarefa.
+- **Duração**: `duration_minutes` (22/10/2026): minutos que a tarefa ocupa, inteiro de 1 a 1440; ausente ou `null` = o tempo do TIPO (Tarefa/Follow-up/Prazo 15, Ligação/Personalizado 30, Reunião/Call 60, tipo criado pela conta 30). Com `occupies_agenda: true` o horário ocupado vai do prazo até o fim da duração.
 - **De onde vem o card (`card_source`)**: `'trigger'` = o card que INICIOU o fluxo (gatilhos `card_created`,
-  `card_moved`, `card_won`, `card_lost`, `card_opened`, `card_snoozed`); fluxo que não nasceu de card = ERRO
+  `card_moved`, `card_won`, `card_lost`, `card_opened`, `card_snoozed`, `card_open_in_stage`, `card_open_in_funnel`); fluxo que não nasceu de card = ERRO
   visível, nunca pulado. `'funnel'` (o padrão da tela) = o card DESSA conversa no funil `funnel_id` (**obrigatório**
   neste modo; funil sem `funnel_id` ou que não existe mais = erro). Conversa sem card naquele funil não é erro: a
   tarefa nasce SÓ na conversa e o passo diz "sem card". Variáveis `{{ }}` em `title` e `description` resolvem pelo
@@ -731,6 +765,13 @@ mensagem elas são bloqueadas por segurança); aqui resolvem no `apiUrl`, `apiHe
 NÃO existe `.payload`/`.response` (`{{api_response.payload.x}}` resolve vazio). O status fica em
 `{{api_response_status}}`. Se a resposta não for JSON, só `{{api_response}}` inteiro funciona.
 
+**Listas na resposta:** item de lista pelo índice com PONTO — `{{api_response.data.0.id}}`,
+`{{api_response.data.0.itens.1.nome}}` — funciona em qualquer versão. Tamanho da lista com FILTRO:
+`{{api_response.data | size}}`. Colchete (`{{api_response.data[0].id}}`) e `.size` sem filtro
+(`{{api_response.data.size}}`) só funcionam depois da correção de 30/10/2026 estar no ar; antes disso saem
+VAZIOS sem erro (a prévia da tela mostra o valor e a execução real não). Prefira sempre o ponto e o `| size`.
+Posição que não existe sai vazia.
+
 **Handles que SAEM:** `success`, `error`.
 
 ### 2.7 `ai`
@@ -1138,8 +1179,12 @@ pela linha de ligacao do WhatsApp (LionCalls).
   "data": { "aiCallAgentId": 4, "aiCallInboxId": 82 } }
 ```
 
-- `aiCallAgentId`: id de `lionchat_captain_call_agents_list`. O que a IA fala, a voz e o **tempo maximo** da ligacao
-  vem do agente (`max_duration_seconds`, 30-600 s; no tempo o motor desliga sozinho).
+- `aiCallAgentId`: id de um **agente de LIGACAO**, vindo de `lionchat_captain_call_agents_list`. O que a IA fala, a
+  voz e o **tempo maximo** da ligacao vem do agente (`max_duration_seconds`, 30-600 s; no tempo o motor desliga sozinho).
+  **NUNCA** use o id de um agente de TEXTO (`lionchat_captain_assistants_*`): sao cadastros diferentes, e o agente de
+  ligacao so APONTA para um de texto em `captain_assistant_id`. Se `captain_call_agents_list` nao estiver entre as
+  suas ferramentas, **pesquise pelo nome** antes de concluir que nao existe. Agente de ligacao que ja existe na conta
+  **nao se recria** — use o id que a lista devolve.
 - `aiCallInboxId`: id de `meta.dial_inboxes` da mesma lista (caixa com a ligacao ligada).
 - Saidas: `answered` (atendeu), `no_answer` (nao atendeu/recusou), `error` (nao deu pra ligar; motivo no historico).
   `answered`/`no_answer` sem edge = o flow termina; `error` sem edge = execucao "Falhou".
@@ -1148,6 +1193,9 @@ pela linha de ligacao do WhatsApp (LionCalls).
 - Nao confere horario (use `condition` antes). Linha ocupada: espera a vez por ate 2 h (a IA sempre deixa uma vaga
   para a equipe).
 - **Proibido** em flow `action`, em flow de grupo e em `ai_tool` (o save recusa). Id de outra conta tambem e recusado.
+- O save tambem recusa agente ou caixa **escolhidos ou trocados** que nao existem nesta conta ("ai_call block uses a
+  call agent that does not exist in this account" / "...an inbox without a calling line..."). Agente apagado ou
+  caixa excluida DEPOIS nao travam o save — falham na execucao.
 
 **Receita — a IA de atendimento pede a ligacao:** etiqueta `ligar`; o cenario manda por a etiqueta quando o cliente
 pede para falar por telefone; flow `conversation` com gatilho `label_added` (`label_names: ["ligar"]`) -> action
@@ -1269,7 +1317,7 @@ Sempre presente:
 
 | Variável | Conteúdo |
 |---|---|
-| `{{trigger.type}}` | código do **EVENTO** que disparou — **NÃO é a chave do item do Início**. Valores reais: `message_created` (gatilho `message_received`), `message_sent`, `conversation_created`, `conversation_opened` (gatilho `conversation_reopened`), `conversation_resolved`, `label_added`, `label_removed`, `team_changed`, `assignee_changed`, `sla_missed`, `kanban_item_created`/`card_created`, `kanban_item_stage_changed`/`card_moved`, `card_status_changed` (`card_won`, `card_lost`, `card_opened` e `card_snoozed` — olhe `{{trigger.kanban.status}}`: `won`/`lost`/`open`/`snoozed`; rótulo "Situação do card mudou" desde 11/10/2026), `conversation_attributes_changed`, `card_attributes_changed`, `contact_attribute_changed`, `group_participant_joined`/`_left`, `webhook_received`, `date_trigger`, `manual` (sidebar), `kanban_manual` (botão do card), `campaign` (Campanha de Fluxo), `page_track`, `activated_by_flow` (fluxo chamou fluxo), `lead_form` (os 3 gatilhos de formulário — `trigger.kind` diz `completed`/`milestone`/`abandoned`), `booking_created`/`booking_cancelled`/`booking_rescheduled`/`booking_completed`. Compare SEMPRE com esses códigos numa condição |
+| `{{trigger.type}}` | código do **EVENTO** que disparou — **NÃO é a chave do item do Início**. Valores reais: `message_created` (gatilho `message_received`), `message_sent`, `conversation_created`, `conversation_opened` (gatilho `conversation_reopened`), `conversation_resolved`, `label_added`, `label_removed`, `team_changed`, `assignee_changed`, `sla_missed`, `kanban_item_created`/`card_created`, `kanban_item_stage_changed`/`card_moved`, `card_status_changed` (`card_won`, `card_lost`, `card_opened` e `card_snoozed` — olhe `{{trigger.kanban.status}}`: `won`/`lost`/`open`/`snoozed`; rótulo "Situação do card mudou" desde 11/10/2026), `conversation_attributes_changed`, `card_attributes_changed`, `contact_attribute_changed`, `group_participant_joined`/`_left`, `webhook_received`, `date_trigger`, `manual` (sidebar), `kanban_manual` (botão do card), `campaign` (Campanha de Fluxo), `page_track`, `card_open_in_stage` / `card_open_in_funnel` (o `type` é a própria chave do gatilho de prazo; rótulo "Card aberto na etapa" / "Card aberto no funil"), `activated_by_flow` (fluxo chamou fluxo), `lead_form` (os 3 gatilhos de formulário — `trigger.kind` diz `completed`/`milestone`/`abandoned`), `booking_created`/`booking_cancelled`/`booking_rescheduled`/`booking_completed`. Compare SEMPRE com esses códigos numa condição |
 | `{{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). Desde 20/08/2026 `name` e `activated_at` são preenchidos em TODOS os caminhos de disparo (antes só no de evento de conversa) |
 | `{{trigger.kanban_item_id}}` / `{{trigger.funnel_id}}` | só quando veio do Kanban |
@@ -1309,7 +1357,7 @@ Oferecidos no autocompletar (só quando o bloco Início tem o gatilho que os pre
 
 | Gatilhos do Início | Variáveis |
 |---|---|
-| `card_created`, `card_moved`, `card_won`, `card_lost`, `card_opened`, `card_snoozed`, `card_attribute_changed` | `{{trigger.kanban.title}}`, `{{trigger.kanban.funnel_name}}`, `{{trigger.kanban.stage_name}}`, `{{trigger.kanban.stage}}` (código da etapa) |
+| `card_created`, `card_moved`, `card_won`, `card_lost`, `card_opened`, `card_snoozed`, `card_open_in_stage`, `card_open_in_funnel`, `card_attribute_changed` | `{{trigger.kanban.title}}`, `{{trigger.kanban.funnel_name}}`, `{{trigger.kanban.stage_name}}`, `{{trigger.kanban.stage}}` (código da etapa) |
 | `card_moved` | `{{trigger.kanban.previous_stage_name}}`, `{{trigger.kanban.previous_stage}}` |
 | `card_won`, `card_lost`, `card_opened`, `card_snoozed` | `{{trigger.kanban.status}}` (`won`/`lost`/`open`/`snoozed`) |
 | `card_opened` | `{{trigger.kanban.previous_status}}` (`snoozed` = voltou do adiamento; `won`/`lost` = reabriram um ganho/perdido) |

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

@@ -489,8 +489,9 @@ publicado e ligado numa janela e preenche durante a ligação. Essa resposta é
 - Contato e conversa ficam **fixos**: os da conversa. Telefone digitado nunca troca de contato nem cria ficha; se já
   for de outra ficha (com ou sem o nono dígito) não é gravado.
 - Todos os blocos rodam como no link (atributos, etiquetas, marco, API, IA, WhatsApp, contrato, agenda). A única
-  diferença: os fluxos **"Formulário concluído"** e **"Formulário abandonado"** NÃO disparam — o pulo fica registrado
-  com o motivo `filled_by_team`. "Marco do formulário" dispara.
+  diferença: o fluxo **"Formulário abandonado"** NÃO dispara — o pulo fica registrado com o motivo `filled_by_team`.
+  **"Formulário concluído"** dispara como no link (desde 23/10/2026; de 20 a 23/10 ele também era pulado, e esses
+  pulos antigos seguem no histórico). "Marco do formulário" dispara.
 - Fica **fora** de `lionchat_lead_forms_stats` (funil, conclusão) e dos contadores da lista (`responses_count`,
   `completed_count`), e do relatório de formulários. Aparece em `responses_list`/`responses_show` com o selo.
 - Não há ferramenta do MCP para começar esse preenchimento — ele só existe na janela do painel.

package/dist/docs/resources/glossary.md

@@ -468,6 +468,15 @@ caixa oficial → `whatsapp_calls`; telefone/ramal → Zenvia (softphone) ou VTC
 WhatsApp Calling (Cloud) fica fora, em `whatsapp_calls_*`. Ligações antigas do **Wavoip** (integração
 encerrada em 30/07/2026) continuam aparecendo nesse histórico, com `provider: "wavoip"`.
 
+**Agente de Ligação com IA pelo TELEFONE (ramal VTCall, 30/10/2026).** O Agente de Ligação
+(`captain_call_agents_*`) é a IA de voz. Por padrão ela liga pelo WhatsApp; se o agente tiver um
+**ramal VTCall** configurado (`sip_ramal` + `sip_server`, com `sip_port` e `max_concurrent_calls`),
+ela passa a **ligar por TELEFONE** por esse ramal, e a conversa de cada ligação nasce na caixa
+`new_conversation_inbox_id`. Os campos do ramal vão no `create`/`update` do agente; **a senha do ramal
+(`sip_password`) NUNCA entra pelo MCP — só pela tela do painel** (o MCP só lê `has_sip_password`
+true/false). `captain_call_agents_ramal_status` lê no motor se o ramal conectou (`comprovado`),
+foi recusado (`senha_recusada`) ou ainda está registrando (`aguardando_teste`).
+
 **Wavoip — INTEGRAÇÃO REMOVIDA (12/08/2026).** O vínculo com a Wavoip acabou; o último uso real foi
 em 30/07/2026. Saíram do produto: a aba "Ligação WP" da caixa, o discador, o Super Admin, as rotas,
 os webhooks, as tarefas automáticas e a tabela. As 8 tools `wavoip_*` já haviam sido removidas do MCP

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

@@ -469,8 +469,9 @@ acesso a uma conversa solta vem de estar atribuído ao card dela.
 
 ## Funil arquivado vs ativo
 
-- `archived = true`: funil escondido da UI principal. Cards ainda existem mas não aparecem nas listas
-- `active = false`: bloqueia movimentação (modo "somente leitura")
+Arquivar e `active = false` são a MESMA coisa (`funnels_archive` grava `active: false`; `funnels_unarchive`
+volta para `true`). Não existe campo `archived` separado. O funil arquivado some da tela principal e os cards
+continuam guardados.
 
 Use cases:
 - Arquivar funis antigos no fim do ano
@@ -561,21 +562,26 @@ PUT /api/v1/accounts/43/funnels/43
 | action | action_config | Observação |
 |---|---|---|
 | `move_to_stage` | `{stage}` | NUNCA executa com trigger `stage_moved` (anti-loop do backend) |
-| `assign_agent` | `{agent_id}` | Agente precisa ter acesso ao funil, senão é ignorado |
+| `assign_agent` | `{agent_id}` | Agente precisa ter acesso ao funil, senão é ignorado. **Não use com gatilho `won`/`lost`**: a automação roda com o card já fechado e card fechado não aceita responsável novo — não faz nada (a tela não oferece mais desde 22/10) |
 | `create_note` | `{note_text}` | Cria nota no card com autor "Sistema" |
-| `notify_team` | `{message}` | HOJE só registra em log interno — não notifica ninguém de verdade |
+| `notify_team` | `{message}` | HOJE só registra em log interno — não notifica ninguém de verdade. **Não use** (a tela não oferece mais desde 22/10) |
 | `duplicate_item` | `{funnel_id, stage}` | Cria cópia noutro funil/etapa; título ganha sufixo "(cópia)" |
 | `send_webhook` | `{webhook_url}` | POST com payload completo do card (fire-and-forget) |
 | `apply_checklist_template` | `{template_id}` | Template de `kanban_config.checklist_templates`; aditivo (appenda) — cada aplicação vira um grupo (carimba `group_id`/`group_name` nos itens) |
 | `update_checklist` | `{checklist_updates: [{checklist_item_id, completed, text}]}` | Não aparece na UI — só via API |
-| `create_task` (20/10/2026) | `{title, description?, task_type, agenda_id?, priority?, occupies_agenda?, due: {amount, unit: 'hours'\|'days', at?: 'HH:MM', business_days?: true}, responsible: {mode: 'card_owner'\|'fixed'\|'funnel_rotation'\|'team_rotation', fallback_user_id (card_owner), user_id (fixed), team_id (team_rotation)}}` | Cria uma tarefa COMUM da Agenda presa ao card (ver "Tarefa automática do card" abaixo). Exige a Agenda unificada ligada na conta |
+| `create_task` (20/10/2026) | `{title, description?, task_type, agenda_id?, priority?, occupies_agenda?, duration_minutes?, due: {amount, unit: 'hours'\|'days', at?: 'HH:MM', business_days?: true}, responsible: {mode: 'card_owner'\|'fixed'\|'funnel_rotation'\|'team_rotation', fallback_user_id (card_owner), user_id (fixed), team_id (team_rotation)}}` | Cria uma tarefa COMUM da Agenda presa ao card (ver "Tarefa automática do card" abaixo). Exige a Agenda unificada ligada na conta |
 
 **Regras críticas (gravar diferente disso = automação perdida ou morta):**
 
-- `trigger_value` vazio ou `enabled: false` → a UI DESCARTA a automação no próximo "Salvar" do usuário. Nunca grave automação desabilitada "pra ativar depois".
+- `trigger_value` vazio → a UI DESCARTA a automação no próximo "Salvar" do usuário. `enabled: false` é estado válido desde 20/10: a regra desligada que já existe fica guardada, desligada (antes a tela a descartava).
 - Nomes de trigger/action fora das tabelas acima (ex.: `status_changed`, `duplicate_to_funnel`, `send_message`, `set_priority` — NÃO existem) são salvos mas NUNCA disparam, sem erro nenhum.
 - `id` no formato `automation_<timestamp_ms>` — a UI usa pra editar/remover a automação.
 - Trigger `card_created` + ação `duplicate_item` funciona (backend tem anti-loop), mas a UI esconde essa combinação.
+- **A ordem da lista `automations` é a ordem de execução**: quando várias regras disparam no mesmo acontecimento (ex.:
+  duas em `won`), elas rodam de cima para baixo. Para mudar a ordem, reenvie a lista inteira na ordem desejada (no
+  painel, desde 22/10, a pessoa segura e arrasta cada regra). Mudar a ordem não mexe na configuração de nenhuma regra.
+- `assign_agent` com `status_change` `won`/`lost` e `notify_team` são aceitos pelo servidor mas **não fazem nada**: não
+  grave regras novas com eles. Regra antiga que já os tenha aparece no painel com um aviso amarelo.
 
 Use para: "ao ganhar um card de Vendas → criar automaticamente em Pós-Venda na etapa Agendar Instalação" (`status_change`/`won` + `duplicate_item`).
 
@@ -587,6 +593,7 @@ Use para: "ao ganhar um card de Vendas → criar automaticamente em Pós-Venda n
   `business_days: true` (dias úteis) **só em dias**. Dia útil = segunda a sexta **sem feriado de dia inteiro** da agenda
   da tarefa (feriado de meio período não conta). O fuso é o da agenda da tarefa. Prazo que já passou nasce atrasado,
   nunca é empurrado.
+- **Duração**: `duration_minutes` (22/10/2026): minutos que a tarefa ocupa, inteiro de 1 a 1440; ausente ou `null` = o tempo do TIPO (Tarefa/Follow-up/Prazo 15, Ligação/Personalizado 30, Reunião/Call 60, tipo criado pela conta 30). Com `occupies_agenda: true` o horário ocupado vai do prazo até o fim da duração.
 - **Responsável (`responsible.mode`)**: `card_owner` (primeiro responsável do card; senão o da conversa; senão a reserva `fallback_user_id`,
   obrigatória), `fixed` (exige `user_id`), `funnel_rotation` (rodízio de quem acessa o funil) e `team_rotation` (exige
   `team_id`).
@@ -609,11 +616,11 @@ Use para: "ao ganhar um card de Vendas → criar automaticamente em Pós-Venda n
 
 `AutomationRule` é o motor geral da conta (mensagens, contatos, conversas, e também eventos Kanban). Bem mais genérico, com sistema completo de condições/ações.
 
-Eventos Kanban: `kanban_item_created`, `kanban_item_moved`, `kanban_item_stage_changed`.
+Eventos Kanban: `kanban_item_created` e `kanban_item_stage_changed` (não existe `kanban_item_moved`).
 
 ```json
 {
-  "event_name": "kanban_item_moved",
+  "event_name": "kanban_item_stage_changed",
   "conditions": [
     {"attribute_key": "funnel_stage", "operator": "equal_to", "value": "ganho"}
   ],
@@ -638,9 +645,35 @@ Use para: ações cross-cutting que envolvem conversa/contato/label, ou regras c
 
 ## Bulk operations
 
-- `POST /api/v2/kanban/items/bulk_actions` — operações em massa (mover, atribuir, arquivar)
-- `POST /api/v2/kanban/items/import` — importar CSV de cards
-- `GET /api/v2/kanban/items/export` — exportar funil completo
+- `POST /api/v1/accounts/{account_id}/bulk_actions` — operações em massa (mover, atribuir, arquivar) — `lionchat_kanban_bulk_bulk_actions`
+- `POST /api/v1/accounts/{account_id}/kanban_items/import` — importar planilha de cards (só pela tela: exige o arquivo)
+- `GET /api/v1/accounts/{account_id}/kanban_items/export` — exportar funil completo — `lionchat_kanban_items_export`
+
+### Importar cards com campos personalizados (2026-10-23)
+
+A importação de cards (Kanban > botão azul **+** > **Importar itens**) liga colunas da planilha a **campos do card** e a
+**atributos do contato**, no mesmo formato da importação de contatos. O conector não sobe o arquivo, então oriente a
+pessoa a importar pela tela; o que segue serve para explicar o que ela vai ver e para ler o resultado.
+
+- **O que pode ser importado** vem da prévia (`lionchat_kanban_items_create_3`, campo `attribute_fields`): campos do card
+  da conta (sem nome protegido nem secreto; dois campos com o mesmo nome = vale o primeiro) e atributos do contato (sem os
+  do sistema — rastreio, identificadores do WhatsApp — nem secretos). **Atributos do contato só aparecem para quem também
+  pode importar contatos** (administrador ou cargo "Exportar e importar contatos").
+- **Como o card grava** (`item_details.custom_attributes`, nasce com o card): data `DD/MM/AAAA` ou `DD/MM/AA` vira
+  `AAAA-MM-DD`; número com ou sem milhar (`1.500`, `1.234,56`) vira texto (`"1500"`); hora vira `HH:MM`; campo de LISTA
+  aceita várias opções na mesma célula separadas por `;` e só grava opção que existe. Os demais tipos gravam o texto como
+  está na planilha.
+- **Contato**: mesma conversão da importação de contatos. Vai só para o **contato principal do card** (numa linha com
+  vários contatos). Contato novo nasce com os atributos; contato que **já existe** tem o valor **substituído** — conta como
+  alteração (fluxo "Atributo do contato muda", webhook `contact_updated`). Célula vazia nunca apaga.
+- **Resultado** (`lionchat_kanban_items_import_status`): `attributes_applied: true` confirma que os campos foram aplicados;
+  `skipped` lista os valores que **não** entraram (`row`, `field`, `message`) e `skipped_count` dá o total. O card nasce
+  do mesmo jeito — só aquele valor fica de fora (formato que não converte, opção fora da lista, texto longo demais, ou
+  linha sem telefone válido, que não tem contato para receber o atributo). `row` é a linha da planilha (cabeçalho = 1).
+- **Armadilhas**: `422` = escolha de campo com formato errado, campo que não existe mais/é do sistema, ou coluna que a
+  planilha não tem (a mensagem lista quais); `403` = atributo de contato sem a permissão de importar contatos. Sem
+  `attributes_applied` no resultado de uma importação que ligou campos = o servidor estava sendo atualizado e os cards
+  nasceram sem eles (preencher nos cards, ou excluir e importar de novo — reimportar cria cards novos).
 
 ## Custom attributes em cards — TRÊS LUGARES POSSÍVEIS
 
@@ -743,8 +776,9 @@ A planilha do financeiro (ou de outro sistema) entra e:
 
 | Situação do card no funil | O que acontece |
 |---|---|
-| Card **aberto** (mais antigo, se houver vários) | Grava o valor e marca **ganho com a DATA DA VENDA** |
-| Card **já ganho** | Atualiza **só o valor**; a data do ganho dele **não muda** |
+| Card **aberto** (mais antigo, se houver vários) | Grava o valor (e os produtos, se vierem) e marca **ganho com a DATA DA VENDA** |
+| Card **já ganho** com o mesmo valor e a mesma data | É a mesma venda: **nada muda** (`ja_ganho`) |
+| Card **já ganho** com outro valor ou outra data | Venda nova: nasce **outro card ganho** (`nova_venda`, só se `criar_sem_card: true`) |
 | Card marcado como **perdido** | **Não é tocado** — vai pra conferência humana |
 | **Sem card nenhum** | Cria card já ganho (só se `criar_sem_card: true`) |
 | Linha com telefone sem DDI, valor ilegível ou data no futuro | Vira **erro da linha**, com motivo |
@@ -771,6 +805,11 @@ arquivo, aponta as colunas e ainda oferece uma planilha de exemplo pra baixar.
 | `email` | não | |
 | `agent` | não | Nome ou e-mail do vendedor |
 | `order_id` | não | Número do pedido, guardado no card |
+| `co_participant` | não | Nome ou e-mail de quem ajudou na venda |
+| `products` | não | TEXTO `"Plano Pro:1200; Instalação:300"` (até 20). Troca os produtos do card e o valor vira a soma; com ele, `value` pode ir vazio. Lista ou objeto é recusado |
+
+Card **ganho nunca é editado** (regra de 30/10/2026). Produto que não está no catálogo da conta entra só no
+card (aviso na conferência). A conferência devolve, por linha, `produtos` e `avisos`.
 
 ### O que você PRECISA saber antes de aplicar
 
@@ -781,8 +820,8 @@ arquivo, aponta as colunas e ainda oferece uma planilha de exemplo pra baixar.
 - **A conciliação não dispara conversão por conta própria.** Quem dispara é o caminho normal do ganho
   (Meta/GA4/Google Ads), e só nos funis com o evento de Ganho configurado. Por isso rodar a mesma
   planilha duas vezes não reenvia conversão: o identificador do evento de ganho é estável.
-- **Rodar a mesma planilha duas vezes é seguro**: card já com aquele valor volta como `sem_mudanca` e
-  nem é gravado.
+- **Rodar a mesma planilha duas vezes é seguro**: a venda já registrada (mesmo valor e mesma data) volta
+  como `ja_ganho`/`sem_mudanca` e nada é gravado.
 - **`criar_sem_card: true` abre uma CONVERSA nova por card criado**, e conversa nova acorda o que a conta
   tiver em "Conversa criada" (automação, fluxo, notificação). Avise a pessoa antes de ligar isso numa
   planilha grande.
@@ -856,6 +895,16 @@ data marcada, **abre sozinho** e volta para a coluna (disparando o fluxo "Card a
   sem card no funil, tempo inválido) — nunca passa verde sem adiar.
 - Fluxo: ação `snooze_kanban_item`, gatilhos `card_opened` ("Card aberto") e `card_snoozed` ("Card adiado") e
   condição `kanban_snoozed`. Ver o resource do FlowBuilder.
+- Fluxo, **card parado (NOVO 28/10/2026)**: gatilhos de prazo `card_open_in_stage` ("Card aberto na etapa") e
+  `card_open_in_funnel` ("Card aberto no funil"). Config `{ "funnel_ids": ["12"], "funnel_stages": ["12:novo_lead"],
+  "duration_value": 1, "duration_unit": "hours" }` (`funnel_stages` só na etapa; vazio = qualquer funil/etapa;
+  `minutes`|`hours`|`days`, de 15 minutos a 365 dias). Relógio da etapa = tempo desde que o card ENTROU na etapa atual
+  (o segundo número "1d" do card; trocar de funil também recomeça); do funil = idade do card (o primeiro número "2d";
+  trocar de funil não recomeça). Conta card aberto ou adiado, nunca ganho/perdido. Dispara uma vez por entrada na etapa
+  (etapa) ou uma vez por card (funil), só para quem cruza o prazo com o fluxo ligado (card que já passou do prazo ao ligar
+  não dispara; mudar prazo/etapa/funil do gatilho = gatilho novo). Conferência de 5 em 5 minutos (pode chegar ~5 min
+  depois). Inicia só o fluxo dono do gatilho, em cada conversa do card; o card que disparou é o "card do gatilho"
+  (`card_source: 'trigger'`, condições "Card na etapa" e "Card adiado"). Dois fluxos iguais na mesma caixa disparam os dois.
 
 **Onde o adiado aparece e como filtrar:**
 
@@ -901,3 +950,68 @@ depois não trava outro salvamento.
   `co_participant_changed` (antes e depois, com nome e quem marcou).
 - Números: `coParticipantRanking`, `sharedSalesSummary`/`sharedSalesBySeller` (com `include_shared_sales=true`) no
   relatório agregado e a lista `lionchat_kanban_items_shared_sales` — ver `lionchat://docs/filtros-e-relatorios` §4.
+
+---
+
+## Analisar com IA — a IA sugere o que mudar nos cards (2026-10-28)
+
+A mesma análise do botão **Analisar com IA** do Kanban (topo do quadro e menu da coluna). A IA lê os cards **abertos e
+adiados** das etapas escolhidas de UM funil, com as conversas deles, e sugere: mudar de etapa (também para trás), levar
+para outro funil, pôr/tirar etiqueta e marcar ganho/perdido. **Nada muda sem aplicar, e aplicar não tem como desfazer.**
+
+### Ferramentas
+
+1. `lionchat_kanban_ai_analyses_setup` — o que a janela mostra: etapas com a contagem de cards, se cada etapa e o funil
+   têm descrição, `selection` (quantos cards entram e `estimated_cost_usd`), funis de destino, etiquetas, motivos de
+   ganho/perda, `has_openai_key` e `latest_run` (análise viva do funil).
+2. `lionchat_kanban_ai_analyses_create` — cria a análise. Os cards são escolhidos AQUI: até `filters.limit` (1 a 1.000,
+   padrão 200), os parados há mais tempo, PULANDO os que a IA leu nos últimos 7 dias (a não ser que o cliente tenha
+   escrito depois); `filters.include_read: true` lê de novo os já lidos.
+3. `lionchat_kanban_ai_analyses_show` — andamento (`status`, contadores, custo).
+4. `lionchat_kanban_ai_analyses_items` — a lista de sugestões (só depois de `ready`). Com `no_change: true` traz também
+   `no_change_items`: os cards que a IA leu e deixou como estão, cada um com `lines` dizendo o porquê.
+5. `lionchat_kanban_ai_analyses_apply` — aplica o que o usuário escolheu. Pede `confirm: true`.
+6. `lionchat_kanban_ai_analyses_reanalyze` — analisa de novo UM card cuja linha travou.
+
+### Passo a passo
+
+1. `setup` com `funnel_id` (e `stages` para saber o total e o custo). Mostre ao usuário as etapas e quantos cards cada
+   uma tem. Dica: marcar VÁRIAS etapas numa análise só evita ler a mesma conversa duas vezes.
+2. Pergunte o que a IA pode fazer (`options`), quais cards (todos, `stale_days` ou `no_reply_days`) e QUANTOS
+   (`filters.limit`, 1 a 1.000; mostre o `estimated_cost_usd` e o `estimated_minutes` do `setup` com o mesmo número). Se o
+   `setup` disser `already_read` > 0, avise que esses serão pulados; para repetir nos mesmos cards, `include_read: true`.
+3. `create`. Depois chame `show` a cada 5 a 10 segundos até `status = ready` (ou `failed`, com `error_code`).
+4. `items`: mostre as sugestões agrupadas por etapa — card, ação, força ("Alta" >= 70%, "Média" 50-70%), motivo e o que
+   a ação dispara (`hints`: conversão, regras do funil, fluxos; aviso de WhatsApp QR).
+5. **Antes de aplicar, confirme com o usuário** quais cards e ações, quantas mudanças em quantos cards, e diga que **não
+   tem como desfazer**: fica como se uma pessoa tivesse feito à mão, e automações, fluxos e conversões do funil disparam.
+6. `apply` com `items: [{ item_id, actions: [ids] }]` e `confirm: true`. Os `actions` são os `id` das `suggestions`
+   daquele item (`stage`, `funnel`, `outcome`, `label_add:...`, `label_remove:...`) — nunca invente: ação que não foi
+   sugerida para o item volta em `ignored`.
+7. `show` até `status = finished`; `items` traz `done`, `apply_code` e `return_code` de cada card.
+8. **"Por que a IA não mudou nada?"** — chame `items` com `no_change: true` e explique pelos `no_change_items[].lines`:
+   `kind` (`stage`, `funnel`, `outcome`, `label`) + `state`: `same` = confirmou o que já está (com `confidence` em %),
+   `doubt` = as duas ordens discordaram (`value` x `other_value`), `weak` = pensou em `value` mas abaixo de 50%,
+   `other_funnel` = achou que o card é de outro funil (anulou a etapa), `not_chosen` = sugeriu um funil que não estava
+   entre os destinos, `add_no` / `remove_keeps` = etiqueta com a chance (`probability`). `lines: null` = análise antiga,
+   sem detalhes.
+
+### Regras que você PRECISA saber
+
+- **Quem pode:** administrador ou cargo com a permissão `kanban_ai_analyze` ("Analisar funil com IA"), com o recurso de
+  plano `kanban_ai_analysis` ligado na conta e o menu do Kanban visível. Funil que a pessoa não vê = 404
+  `funnel_not_visible`. Sem o recurso = `feature_disabled`.
+- **Custo:** usa a chave da OpenAI DA CONTA (`no_openai_key` sem ela). Costuma ficar abaixo de um centavo de dólar a cada
+  dezenas de cards — mostre o `estimated_cost_usd` do `setup` antes de criar.
+- **Uma análise por vez por funil** (`funnel_busy`, 409) e no máximo duas rodando por conta (`account_busy`). Criar uma
+  análise nova **substitui a lista anterior** do mesmo funil que tiver etapa em comum (ela vira `superseded`).
+- **A lista vale 24 horas** (`expires_at`); depois vira `expired` e é preciso analisar de novo.
+- **O que vem marcado** (`checked: true`): sugestões de força Alta de etapa, funil e perdido. Ganho, Média e etiqueta vêm
+  sempre desmarcados, com o motivo em `unchecked_reason`. Na dúvida, proponha aplicar só as marcadas.
+- **Linha travada** (`locked`: `client_wrote` = o cliente escreveu depois da análise; `card_changed` = o card mudou):
+  não aplique. Chame `reanalyze` com o `item_id` e depois `items` de novo.
+- **Linha que voltou** (`return_code`): `interrupted` (sistema reiniciou), `card_busy` e `apply_failed` podem ser
+  aplicadas de novo; `agent_no_access` (o responsável não acessa o funil de destino) exige dar o acesso antes.
+- **"Por que não sugeriu nada?"** A IA só sugere quando responde a mesma coisa com as opções em duas ordens e com pelo
+  menos 50% de certeza. Card sem conversa, ou com pouca conversa, costuma ficar como está (`counts.no_change`). Escrever
+  a descrição das etapas e do funil melhora o resultado (o `setup` diz quais não têm).