@lionchat/mcp-server 1.23.0 → 1.24.0

package/dist/docs/instructions.md

@@ -170,10 +170,29 @@ Detalhes completos em `lionchat://docs/api-conventions` → "Wrapper de body".
 ### Regras de formato silenciosas
 
 - **Label.title**: kebab-case ou snake_case, **SEM espaço**. `"Lead Emive"` ❌ → `"lead-emive"` ✅
-- **win_reasons / loss_reasons**: array de `{id, title}`, NÃO strings
+- **win_reasons / loss_reasons**: array de `{id, title}`, NÃO strings. O `id` é **TEXTO estável** (`"perda-preco"`),
+  nunca número. A lista SUBSTITUI a atual: leia antes e reenvie os MESMOS `id` (trocar o `id` tira o nome dos
+  cards já marcados). Motivo sem `id`/`title`, `id` repetido ou lista de textos → recusado com 422
+- **motivo no card**: `item_details.status` `"lost"`/`"won"` + `loss_reason`/`win_reason` = o `id` (texto) de um
+  motivo cadastrado + `reason` = o título. Motivo livre: `loss_reason` nulo e o texto em `reason`
 - **linked_conversations**: array de `{display_id: N}`, NÃO inteiros direto
 - **phone**: E.164 (`+5511...`), sem espaços/parênteses
-- **funnel.stages** keys: snake_case slug
+- **funnel.stages** keys: snake_case slug; cada etapa é OBJETO com `name` texto
+- **Lista de objetos é lista de objetos**: onde o formato pede `[{id: 5}]`, número solto (`[5]`) ou objeto
+  único no lugar da lista quebra a leitura — às vezes a tela da conta inteira (incidente 18/09, funil).
+
+### Gravação: TROCA inteira × SOMA (conferido no código em 18/09/2026)
+
+Muitos campos objeto/lista são **trocados inteiros** no update: o que não vier no envio é APAGADO. Nesses,
+**leia antes** (show) e **reenvie tudo** com o item alterado. A descrição de cada ferramenta diz qual é qual.
+
+| TROCA inteira (leia e reenvie tudo) | SOMA (só as chaves enviadas mudam) |
+|---|---|
+| `custom_attributes` da CONVERSA (`conversations_create_3` — só `captain_*` sobrevive; apaga utm/gclid/ctwa/origin) | `custom_attributes` do CONTATO (`contacts_update`) |
+| card: cada chave de `item_details` (a lista `custom_attributes` do card, `offers`, `notes`), `assigned_agents`, coluna `custom_attributes` | `item_details` do card no 1º nível (chave não enviada fica) |
+| `funnel.settings`, `funnel.stages` (etapa ausente = removida), `kanban_config.global_custom_attributes` | `channel.additional_attributes` da caixa WhatsApp/Instagram/Facebook/TikTok |
+| `flow_data` do fluxo, `actions` de macro/automação, `query` de filtro salvo, `audience` de campanha | `roles_layout` do modelo de contrato |
+| `settings` de integração (hooks), mapas de evento de gateway/Omie/Conta Azul/Meta Lead/Google Ads | |
 
 ### Native first
 

package/dist/docs/resources/agenda-multiplas-unidades.md

@@ -141,12 +141,55 @@ Google dela — inclusive a **mesma pessoa** com contas Google diferentes, uma p
 
 - Agenda **sem** pessoas e **sem** equipes: todo mundo da conta enxerga.
 - Marcando pessoas e/ou equipes: só elas. Quem entrar na equipe ganha acesso sozinho.
-- **Administrador enxerga todas**, sempre.
+- **Administrador enxerga todas**, sempre. Desde 21/09, **quem tem a caixinha `agenda_manage`** ("Gerenciar
+  agenda da equipe") também enxerga todas — é a função da secretária.
 - `member_user_ids` e `member_team_ids` **substituem a lista inteira** (idioma do `InboxMember`).
 
+### `agenda_manage`: a caixinha da secretária (21/09)
+
+Permissão de função personalizada (`custom_roles.permissions`). Quem a tem, **sem ser administrador**:
+- vê a agenda e os compromissos de TODA a conta (`tasks_list` deixa de recortar por pessoa);
+- cria, edita, remarca, cancela e exclui compromisso de qualquer pessoa;
+- marca pelo `booking_event_type` de qualquer pessoa (`tasks_create` com `booking_event_type_id` de outro);
+- cria/edita/apaga `booking_event_types` de outra pessoa (inclusive mandando `user_id` de outro no create);
+- lê e ajusta a disponibilidade de outra pessoa (`agent_availability_*`) e abre o painel de Agentes.
+
+**NÃO** permite criar/editar/apagar AGENDA (unidade): `agendas_create/update/destroy` seguem só administrador —
+agenda é recurso do plano, com limite. Sem a caixinha, o atendente vê só a própria agenda e a de quem ligou
+`agenda_public` no perfil, e não mexe na dos outros.
+
 A listagem de compromissos já vem recortada pelas agendas que o usuário enxerga, **mesmo sem mandar
 `agenda_id`**. Ler ou editar compromisso de uma agenda que a pessoa não enxerga devolve 404.
 
+**Quem não enxerga NENHUMA agenda não vê compromisso nenhum** (21/09). Antes, "lista de agendas
+visíveis vazia" abria em vez de fechar: o recorte tratava igual dois estados opostos — *a conta não
+tem agenda nenhuma* (aí não há o que recortar, devolve tudo) e *a conta tem agendas e esta pessoa não
+foi posta em nenhuma* (aí ela não pode ver nada). Medido: atendente fora das duas agendas da conta
+enxergava todos os compromissos.
+
+## 6.1. Toda conta tem a agenda "Principal" (21/09)
+
+Antes, a agenda de uma conta era **implícita**: não havia linha no banco e todo compromisso nascia com
+`agenda_id` NULO. A aba Agendas abria dizendo "Nenhuma agenda ainda" numa conta que **tinha** agenda —
+e não havia onde escolher quem a enxerga.
+
+Hoje `Agenda.garantir_padrao!` (chamada no `index`) materializa essa agenda como **Principal**, marcada
+`is_default`, com o fuso da conta. Vale para **toda conta, com ou sem o recurso de múltiplas agendas**:
+quem tem uma agenda só pode editá-la e escolher equipes/pessoas — só não pode **criar outra**, o que
+continua barrado por `Agendas::Quota` (motivo `feature_off`, que é avaliado ANTES do número).
+
+**NEVER CHANGE / GOTCHAS**
+- A condição é "não existe agenda **PADRÃO**", nunca "não existe agenda": enquanto o defeito do
+  `is_default` esteve no ar, quem criou agenda ficou **sem padrão** e com os compromissos antigos
+  invisíveis. Perguntar só por "existe agenda?" deixaria essas contas quebradas para sempre.
+- **Não promover** uma agenda existente a padrão: ela é um LUGAR que o cliente nomeou (uma filial), e
+  herdar os compromissos da agenda de antes jogaria o histórico inteiro dentro da filial errada.
+- A Principal nasce **sem membros** — lista vazia é visível a todos, então ninguém perde acesso no
+  deploy.
+- Criar agenda: a pergunta "é a primeira?" tem que ir ao **banco** (`exists?`) e **antes** do `.new`.
+  `conta.agendas.new(...)` ACRESCENTA o registro não salvo à coleção em memória, então o `.empty?`
+  que existia ali respondia sempre `false` e `is_default` **nunca** era marcado.
+
 ---
 
 ## 7. Programa de sessões (15/09)

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

@@ -73,7 +73,61 @@ Praticamente nunca — exceto se você está testando legacy/curl e quer ser exp
 }
 ```
 
-Strings simples (`"win_reasons": ["motivo"]`) causam erro de serialização.
+Regras (conferidas no servidor desde 21/09):
+
+- O `id` é **texto estável** (`"wr-1"`, `"perda-preco"`) — **nunca número**. Número é convertido para texto
+  (`7` vira `"7"`), mas o certo é já mandar texto. Motivo cadastrado com `id` numérico derrubava o relatório do
+  funil (conta 137, 21/09).
+- Como a lista **substitui** a atual, **reenvie os mesmos `id`** dos motivos que já existem. Trocar o `id` de um
+  motivo faz os cards já marcados com ele perderem o nome no relatório.
+- Recusado com **422** (mensagem diz o formato): lista de textos soltos (`["motivo"]` — antes APAGAVA os motivos da
+  conta em silêncio), motivo sem `id`, motivo sem `title`, `id` repetido. O servidor **não inventa** `id`.
+- Lista vazia (`[]`) limpa os motivos.
+
+**Marcar o card com o motivo** (`PATCH /kanban_items/{id}`, `item_details` mescla no 1º nível):
+
+```json
+{ "item_details": { "status": "lost", "loss_reason": "perda-preco", "reason": "Preço alto" } }
+```
+
+`loss_reason`/`win_reason` = o `id` (texto) de um motivo cadastrado; `reason` = o título. Motivo livre (fora da
+lista): `loss_reason` nulo e o texto em `reason`.
+
+### Outras listas de OBJETOS — formato conferido no servidor (desde 21/09)
+
+Estes campos são **listas de objetos**. Mandar lista de textos/números soltos, lista misturada (alguns objetos e
+alguns textos) ou um objeto solto no lugar da lista é recusado com **422**, e a mensagem mostra o formato certo.
+Antes o servidor aceitava, gravava **lista vazia** e respondia 200 — ou seja, apagava a configuração do cliente.
+
+| Ferramenta | Campo | Formato |
+|---|---|---|
+| `custom_dashboards_create/update` | `widgets` | `[{"widget_type": "conversations_timeseries", "metric": "conversations", ...}]`; dentro de cada bloco, `columns` também é lista de objetos |
+| `kanban_config_update` | `global_custom_attributes` | `[{"name": "Origem", "type": "text"}]` (`list_values` é lista de textos) |
+| `kanban_config_update` | `checklist_templates` | `[{"name": "Onboarding", "items": [{"text": "Ligar"}]}]` — `items` é lista de objetos |
+| `funnels_create/update` | `global_custom_attributes` | igual ao do Kanban |
+| `booking_event_types_create/update` | `confirmation_blocks` e `follow_up_schedules_attributes[].blocks` | `[{"type": "text", "content": "Olá"}]` |
+| `inboxes_update` | `csat_config.survey_rules` | **objeto** `{"operator": "contains", "values": ["vip"]}` — `values` é lista de textos |
+
+Continua valendo: a lista **substitui** a anterior (leia com GET e reenvie inteira) e `[]` limpa.
+Recebeu 422 de formato? **Não repita a mesma chamada**: leia a mensagem, corrija o formato e mande de novo.
+
+### Recusa por PERMISSÃO (401) — o que mudou em 21/09
+
+O servidor responde **401** (não 403) quando o usuário do token não tem a permissão. Não retente; explique ao usuário.
+
+- **Fluxos** (`flows_create/update/destroy/toggle`, duplicar, fixar teste, testar nó): só **administrador** ou cargo com
+  **Gerenciar FlowBuilder**. `flows_list` e `flows_show` seguem abertos. "Gerenciar Regras de Automação" **não** libera fluxo.
+- **Respostas de formulário** (`lead_forms_responses_list/show`, `lead_forms_stats`, `lead_forms_test_run`): administrador ou
+  **Gerenciar Formulários**. As respostas de UM contato continuam em `contacts_form_entries_list`.
+- **Mesclar contatos** (`contacts_create_4` — "Mesclar Contatos", `POST actions/contact_merge`): administrador ou **Gerenciar contatos**
+  (mesclar apaga uma das fichas).
+- **Configuração do Kanban** (`kanban_config_update`): motivos de ganho/perda = qualquer usuário; campos do card, checklists e
+  `config` = administrador ou **Gerenciar Funis**; webhook e liga/desliga = só administrador. A recusa lista as chaves barradas.
+- **Card do Kanban**: `kanban_items_show/update` e os arquivos do card devolvem **404** para card que o usuário não enxerga no
+  quadro. Cargo sem opção de Kanban só edita o card dele ou o sem responsável.
+- **Tipo de agendamento** (`booking_event_types_update/destroy`): só o dono do link ou administrador.
+- **Relatório do Kanban** (`kanban_items` reports): traz `metrics.visibilityScope` — `partial` significa "só os cards que ESTE
+  usuário vê". Diga isso ao usuário antes de apresentar o número como total da conta.
 
 ## Restrições de formato em campos comuns
 
@@ -282,7 +336,7 @@ Vale pra automações, filtro avançado de conversas/contatos e busca "+ Filtro"
 | Código | Significado | O que fazer |
 |---|---|---|
 | `400` Bad Request | Parâmetros mal formados | Confira sintaxe |
-| `401` Unauthorized | Token inválido ou expirado | Reporte ao usuário (não retente) |
+| `401` Unauthorized | Token inválido/expirado **ou usuário sem a permissão** (o LionChat recusa permissão com 401, não 403) | Reporte ao usuário (não retente) |
 | `403` Forbidden | Sem permissão (papel insuficiente) | Reporte (não retente) |
 | `404` Not Found | Recurso não existe (ou de outra conta) | Confira ID |
 | `422` Unprocessable Entity | Validação falhou | Leia mensagem, corrija |

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

@@ -172,10 +172,13 @@ valores desta lista:
 | 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`, `gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`, `o1`, `o3` |
+| Premium | `gpt-5`, `gpt-5.2`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-6-sol`, `o1`, `o3` |
+| Custo-benefício (nova geração) | `gpt-6-luna` — US$ 0,10/0,50 por 1M tokens, raciocínio, sem temperatura; liberado em 23/09/2026 |
 
 **`GPT-5.2 Pro` não existe.** O valor válido é `gpt-5.2`, sem "Pro".
 
+> **Família `gpt-6` (`gpt-6-luna`, `gpt-6-sol`) — LIBERADA em 23/09/2026**, pelo mesmo trilho do `gpt-5.6`: sem temperatura e fora do bloco de IA do Formulário de Lead. `gpt-6-astra` NÃO está disponível.
+>
 > **Família `gpt-5.6` (`gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`) — LIBERADA em 09/2026.**
 > Foi removida em 29/07/2026 porque recusa function tools no canal antigo da OpenAI e deixava a IA MUDA.
 > Desde 09/2026 o servidor fala com esses três pela porta `/v1/responses` (só para eles — nenhum outro
@@ -190,6 +193,47 @@ valores desta lista:
 > 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".
 
+## Ligação por IA — Agentes de ligação (2026-09-24)
+
+A ligação por voz **saiu do agente de texto**. Desde 24/09 ela mora em **Agentes de ligação**, uma área
+própria: cada agente de ligação tem um objetivo e **não ocupa vaga de IA do plano**. As chaves antigas
+`config.call_*` do `captain_assistants_update` **não existem mais** — mandar elas não tem efeito.
+
+| Ferramenta | Para quê |
+|---|---|
+| `captain_call_agents_list` | lista os agentes de ligação e `meta.dial_inboxes` (caixas que podem ligar) |
+| `captain_call_agents_create` / `_update` / `_duplicate` / `_destroy` | cadastro |
+| `captain_call_test_phones_list` / `_create` / `_destroy` | números autorizados a receber ligação de teste |
+| `captain_call_agents_test_call` | **liga de verdade** para um número de teste cadastrado |
+| `captain_call_agents_test_call_status` | tocando / atendeu / não atendeu, e em qual conversa ficou |
+
+Campos do agente de ligação: `name`, `objective` (roteiro, até 4000), `first_message` (até 400), `style`
+(jeito de falar, até 1200), `voice_provider` (`openai` padrão ou `elevenlabs`), `engine` (`gptlive` padrão
+ou `realtime`, só na OpenAI), `voice_id`, `elevenlabs_agent_id` (obrigatório na ElevenLabs),
+`max_duration_seconds` (30 a 600, padrão 180) e **`captain_assistant_id`**.
+
+**Como a ligação trabalha (GPT-Live).** A voz conversa e **só consulta** agenda (horários livres, agenda do
+atendente, quem está trabalhando). Quando o cliente pede algo que precisa ser FEITO — mandar link,
+endereço ou proposta pelo WhatsApp, mover o card, anotar — a voz **repassa** ao agente de texto de
+`captain_assistant_id`, diz "já pedi, vai chegar no seu WhatsApp" e **segue a conversa** (nunca diz "já
+mandei"). O agente de texto executa na conversa daquele contato, com as ferramentas e a configuração
+DELE, e decide se escreve ao cliente. Regras fixas desse pedido: roda mesmo com atendente humano na
+conversa ou com a IA pausada; não liga a IA na conversa nem mexe na IA que já estava lá; não passa para
+humano, não encerra, não transfere e não agenda retorno (fluxos rodam completos); no máximo 3 pedidos
+por ligação; caixa oficial fora da janela de 24h faz as ações mas não escreve.
+Sem `captain_assistant_id` (ou no motor `realtime`/ElevenLabs), a voz **só conversa**.
+
+**Voz.** É **própria** do agente de ligação — não mexe na voz do áudio da IA no WhatsApp
+(`config.voice_provider`/`config.voice_id` do agente de texto continuam sendo só do WhatsApp). No GPT-Live
+use `captain_voices_list` com `engine=gptlive`: aceita alloy, ash, ballad, coral, echo, sage, shimmer, verse,
+**marin** e **cedar** (as duas mais naturais de telefone); voz fora disso cai na marin.
+
+**Ligação de teste.** Só para número **cadastrado** em `captain_call_test_phones` (o telefone nunca vai no
+corpo, só o id). Cria contato e conversa de verdade, pode disparar automações de "conversa criada" e fica
+gravada. Limite de 10 por hora na conta. Precisa da Ligação com IA liberada na conta e da linha da caixa
+conectada; recusa volta 422 com o motivo em `message`. Depois que a ligação termina, a transcrição do
+próprio fornecedor aparece no card da ligação.
+
 ## Follow-up automático multi-etapa (2026-06)
 
 O follow-up do AI Agente agora suporta **cadência de até 3 etapas** via `config.follow_up_steps`:
@@ -463,7 +507,13 @@ puxados. Se a ativação reclamar de sample, NÃO é bloqueio — a integração
 - `ContactLabel` `{id}` — etiqueta de CONTATO (novo)
 - `ContactAttribute` `{key, value}` — atributo do contato (novo)
 - `CardAttribute` `{key, value}` — atributo do card Kanban (novo)
-- `AgentTeam` `{assignee_ids:[], team_ids:[]}` — responsável atual OU time da conversa (novo)
+- `AgentTeam` `{assignee_ids:[], team_ids:[], assignee_mode?, team_mode?}` — responsável atual OU time da
+  conversa. **Modos (24/09/2026):** `assignee_mode:'none'` = conversa SEM responsável ("Sem atendente"),
+  `'any'` = com qualquer responsável; `team_mode:'none'|'any'` igual para time. Ausente/`'specific'` = usa os
+  ids (comportamento de sempre). Vale QUALQUER conversa do contato, de qualquer status. Atendente e time
+  SEMPRE somam (um OU outro) — inclusive em blocos `AgentTeam` separados, que viram UMA seção só; o
+  `audience_mode:'all'` cruza o AgentTeam com as OUTRAS seções (etiqueta, funil, atributo), não atendente com
+  time. "Sem atendente E com time" não é montável hoje. Mesmos modos na `exclusion`.
 
 O campo `audience_mode` define a combinação ENTRE seções:
 - `"sum"` (default): união — contato em QUALQUER seção entra

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

@@ -215,7 +215,8 @@ Funnel
 ├── name
 ├── stages (jsonb: hash com slug_etapa => { name, color, position, description, checklist_templates })
 ├── settings (jsonb: { agents: [], goals: [], automations: [{trigger_type, action, action_config, enabled}] })
-├── global_custom_attributes (jsonb array)
+├── global_custom_attributes (jsonb array — NENHUMA tela lê este campo do funil; os campos da aba do card
+│     são os do KanbanConfig acima)
 ├── meta_events_config (jsonb: won/lost/stages → Meta Pixel/CAPI events; cada bloco: enabled, name,
 │     is_standard, value_strategy, value_fixed, currency, messaging_name — este último é o evento de
 │     ANÚNCIO DE WHATSAPP, tri-estado: ausente = automático, '' = não enviar, um dos 14 nomes da Meta;
@@ -241,9 +242,10 @@ KanbanItem
 ├── stage_entered_at (datetime)
 ├── position (int, ordem dentro da etapa)
 ├── conversation_display_id (FK opcional → Conversation.display_id)
-├── item_details (jsonb)
-├── custom_attributes (jsonb)
-├── assigned_agents (jsonb array)
+├── item_details (jsonb — os campos da aba Campos ficam em item_details.custom_attributes, LISTA de
+│     {name, type, value}; nunca objeto {chave: valor})
+├── custom_attributes (jsonb — coluna que NENHUMA tela mostra; nao confundir com a lista acima)
+├── assigned_agents (jsonb array — para gravar: lista de NUMEROS [5, 12])
 ├── linked_conversations (jsonb array de { display_id })
 ├── checklist (jsonb array de itens — NAO e tabela separada; ver abaixo)
 ├── activities (jsonb)
@@ -492,7 +494,7 @@ daquele tipo no calendário; vazio = cor do agente. A tarefa devolve `booking_co
 
 ## e-Clínicas (Efficient) — integração de clínicas
 
-17 eventos de webhook, cada um mapeável a automação OU flow na tela Integrações > e-Clínica
+19 eventos de webhook, cada um mapeável a automação OU flow na tela Integrações > e-Clínica
 (o mapeamento e os lembretes passaram a ser editáveis por MCP em 31/08/2026, com
 `lionchat_eclinica_integrations_update` — ele **SUBSTITUI** o objeto inteiro, então leia com
 `_show` e devolva completo, senão apaga o resto):
@@ -502,7 +504,10 @@ daquele tipo no calendário; vazio = cor do agente. A tarefa devolve `booking_co
 `cliente_inclusao_pagamento`, `controle_laboratorio_novo`, `controle_laboratorio_alterado`,
 `agendamento_aguardando`, `odontograma_aprovado`, `procedimento_finalizado`,
 `cliente_alteracao_pagamento`, `odontograma_finalizado`, `inclusao_procedimento`
-(capturados ao vivo, não documentados pelo e-Clínica).
+(capturados ao vivo, não documentados pelo e-Clínica) +
+`agendamento_confirmado_link` e `agendamento_cancelado_link` (18/09/2026 — o PACIENTE confirmando/
+cancelando pelo link do portal, ecli.co; confirmado processa como `agendamento_alterado`, mantendo o
+lembrete; cancelado processa EXATAMENTE como `agendamento_desmarcado`, cancelando o lembrete).
 
 O recurso `eclinica_integration` da conta passou a ser ligado e desligado pelo PRÓPRIO cadastro da
 integração (10/09/2026, `auto_managed`): sumiu do Super Admin e não há passo manual — os blocos de

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

@@ -36,6 +36,14 @@ E/OU é encadeado condição a condição (sem parênteses).
 Atributo personalizado: informe `custom_attribute_type` na condição — `'conversation_attribute'`
 (atributo da conversa) ou `'contact_attribute'`. Sem ele o escopo pode sair errado.
 
+**`contact_attribute` lê a FICHA DO CONTATO da conversa (funciona de verdade desde 24/09/2026).** Antes o
+servidor ignorava o valor e lia o atributo da própria conversa — por isso lead de formulário da Meta
+(formulário, anúncio, campanha e 1ª/última origem ficam SÓ no contato) não era achado. Agora a conversa entra
+quando o contato dela casa. Chave precisa ter cadastro de atributo DE CONTATO na conta (senão 422). Exemplo:
+`{attribute_key:'meta_lead_form_name', custom_attribute_type:'contact_attribute', filter_operator:'contains',
+values:['vendas']}`. Negativos (`not_equal_to`, `does_not_contain`, `is_not_present`) incluem a conversa cujo
+contato não tem o dado. Texto compara sem maiúscula/acento.
+
 - `chat_type` em `conversations_filter` funciona desde 19/08/2026 (antes respondia 500). `group` =
   conversa de grupo de WhatsApp; `individual` cobre também canal, transmissão e status. Com
   `not_equal_to`, conversa sem contato vinculado NÃO some do resultado.
@@ -162,6 +170,13 @@ Params: `funnel_id` (obrigatório), `from`, `to`, `user_ids[]` (agentes), `team_
 | `moved` | só quando entrou na etapa atual (mesma expressão do `stage_date_*` da seção 3) | "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
+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.
+
 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

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

@@ -140,6 +140,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.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.
 - 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 }] }`.
@@ -705,7 +706,9 @@ Exemplo: `{"aiMode":"sentiment","aiAssistantId":"12","aiModel":"gpt-4.1-mini","a
 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`, `gpt-5.6-luna`, `gpt-5.6-terra`,
-`gpt-5.6-sol`, `o1`, `o3`, `o3-mini`, `o4-mini`.
+`gpt-5.6-sol`, `gpt-6-luna`, `gpt-6-sol`, `o1`, `o3`, `o3-mini`, `o4-mini`.
+A família **`gpt-6` (luna/sol) entrou em 23/09/2026** pelo mesmo trilho do `gpt-5.6` (porta `/v1/responses`,
+sem temperatura, fora do Formulário de Lead).
 A família **`gpt-5.6` (luna/terra/sol) voltou em 09/2026** (tinha sido removida em 2026-07-29 porque
 recusa function tools no canal antigo): o servidor fala com esses três pela porta `/v1/responses`.
 Eles ignoram a temperatura do bloco (só o padrão) e **NÃO valem no bloco de IA do Formulário de Lead**

package/dist/docs/resources/glossary.md

@@ -388,13 +388,15 @@ mandar). Detalhes em `lionchat://docs/best-practices`.
 
 **Onde fica armazenado:** `kanban_config.win_reasons` e `kanban_config.loss_reasons` (jsonb arrays na tabela `kanban_configs`).
 
-**Formato:** array de objetos `{id, title}`:
+**Formato:** array de objetos `{id, title}`, com `id` em **texto estável** (nunca número) — detalhes e erros 422 em
+`lionchat://docs/api-conventions` → "Estrutura interna das listas":
 ```json
 "win_reasons": [
   {"id": "wr-1", "title": "Preço competitivo"},
   {"id": "wr-2", "title": "Indicação forte"}
 ]
 ```
+**No card:** `item_details.loss_reason` / `win_reason` guardam o `id` (texto) do motivo escolhido; `reason`, o título.
 
 **Endpoint:** `PUT /api/v1/accounts/{id}/kanban_config` com body wrapped:
 ```json
@@ -414,7 +416,7 @@ mandar). Detalhes em `lionchat://docs/best-practices`.
 |---|---|---|
 | Motivo de Ganho/Perda do card | `kanban_config.win_reasons` / `loss_reasons` | ❌ NÃO |
 | Atributo em TODO card | `kanban_config.global_custom_attributes` | só se não couber acima |
-| Atributo de UM card específico | `kanban_item.custom_attributes` (jsonb direto) | já é nativo, não precisa definition |
+| Valor de um campo em UM card | `item_details.custom_attributes` — LISTA `[{name, type, value}]` casando com o campo de `kanban_config.global_custom_attributes` | a coluna `kanban_item.custom_attributes` NÃO aparece em tela nenhuma — não use pra dado que o cliente precisa ver |
 | CPF, RG, CNPJ, endereço, data nasc., gênero do cliente | mecanismo NATIVO cadastral: `PATCH /contacts/{id}/cadastral` (`update_cadastral`) | ❌ NÃO (tem nativo) |
 | Tag pro contato (residencial, empresarial) | `labels` | ✅ SIM via Label |
 | Etapa do funil | `funnel.stages` | ❌ NÃO |

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

@@ -16,6 +16,7 @@ Container de etapas. Conta pode ter vários funis (ex: "Vendas", "Pós-venda", "
 | `archived` | Boolean — funis arquivados não aparecem na UI ativa |
 | `active` | Boolean — controla se aceita movimentação |
 | `settings` | jsonb — config customizada (ex: cores, automações) |
+| `settings.agents` | agentes do funil. Grave `[{"id": <id do agente>}]` — cada item é um OBJETO, nunca número solto (ids de `lionchat_agents_list`); o sistema completa nome, e-mail, cargo e foto — é o que o editor do funil, o card e a conversa mostram. Agente de outra conta fica sem nome e sem acesso. `settings` é substituído INTEIRO no update: leia o funil antes e reenvie goals+agents+teams+automations. |
 
 ### Stages (Etapas) — dentro de `funnel.stages`
 
@@ -65,8 +66,8 @@ Stages NÃO são tabela separada. São armazenadas como jsonb dentro do Funnel:
 
 | Campo | Tipo | O que guarda |
 |---|---|---|
-| `win_reasons` | jsonb array | **Motivos de Ganho** — `[{id, title}]`. Aparecem como dropdown quando o vendedor marca "Ganho" num card. NATIVO. NÃO usar custom_attribute. |
-| `loss_reasons` | jsonb array | **Motivos de Perda** — mesma estrutura. Aparece ao marcar "Descartado". |
+| `win_reasons` | jsonb array | **Motivos de Ganho** — `[{id, title}]`, `id` em **texto estável** (nunca número). Aparecem como dropdown quando o vendedor marca "Ganho" num card. NATIVO. NÃO usar custom_attribute. |
+| `loss_reasons` | jsonb array | **Motivos de Perda** — mesma estrutura e mesma regra do `id`. Aparece ao marcar "Descartado". |
 | `checklist_templates` | jsonb array | Templates de checklist reusáveis — `[{id, name, items: [{id, text}]}]`. Aplicados manualmente ou via automação `apply_checklist_template`. |
 | `global_custom_attributes` | jsonb array | Atributos globais que aparecem em TODOS os cards de TODOS os funis — `[{name, type, is_list, list_values}]`. |
 | `config` | jsonb hash | Configurações gerais (title, default_view, auto_assignment, support_email, dragbar_enabled, etc) |
@@ -82,7 +83,8 @@ Stages NÃO são tabela separada. São armazenadas como jsonb dentro do Funnel:
 | DELETE | `/api/v1/accounts/{id}/kanban_config` | Remove (não afeta cards/funis) |
 | POST | `/api/v1/accounts/{id}/kanban_config/test_webhook` | Dispara payload de teste |
 
-**GOTCHA — body precisa estar wrapped:**
+**Body raiz ou com o envelope `kanban_config` — os dois funcionam** (conferido 21/09: `{"loss_reasons": [...]}` na
+raiz grava e recusa normalmente). Exemplo com envelope:
 
 ```json
 PUT /api/v1/accounts/43/kanban_config
@@ -100,7 +102,11 @@ PUT /api/v1/accounts/43/kanban_config
 }
 ```
 
-Se mandar `{"win_reasons": [...]}` direto (sem o wrapper `kanban_config`) → **HTTP 500 silencioso**. Strong params do Rails exige `params.require(:kanban_config)`.
+**Regras dos motivos** (servidor, desde 21/09): `id` em texto estável — número é convertido (`7` → `"7"`), mas mande
+texto; a lista SUBSTITUI a atual, então reenvie os MESMOS `id` dos motivos que já existem (trocar o `id` tira o nome
+dos cards já marcados); lista de textos soltos, motivo sem `id`/`title` ou `id` repetido → **422** com o formato
+(antes, a lista de textos APAGAVA os motivos em silêncio). No card: `item_details.loss_reason`/`win_reason` = o `id`
+(texto) + `reason` = o título. Detalhes em `lionchat://docs/api-conventions` → "Estrutura interna das listas".
 
 **`win_reasons` e `loss_reasons` aceitam array de OBJETOS `{id, title}`, NÃO strings simples.** Strings causam 500. O `id` é qualquer string única (UUID ou slug curto tipo `wr-1`).
 
@@ -114,7 +120,7 @@ Se mandar `{"win_reasons": [...]}` direto (sem o wrapper `kanban_config`) → **
 | Atributo que aparece em TODO card | `kanban_config.global_custom_attributes` | ❌ custom_attribute de conversation |
 | Atributo só de um contato (CPF, endereço) | `custom_attribute_definitions` model=contact_attribute | ❌ kanban_config |
 | Atributo só de uma conversa (motivo, tag interna) | `custom_attribute_definitions` model=conversation_attribute | ❌ kanban_config |
-| Atributo só de um card | `kanban_item.custom_attributes` (jsonb direto no card) | — |
+| Valor de um campo num card (aparece na aba Campos) | `item_details.custom_attributes` — LISTA `[{name, type, value}]`, com o campo definido em `kanban_config.global_custom_attributes` | ❌ `kanban_item.custom_attributes` (coluna que nenhuma tela mostra) |
 
 ### KanbanItem (Card)
 Um card individual dentro de uma etapa.
@@ -130,7 +136,7 @@ Um card individual dentro de uma etapa.
 | `origin_conversation_display_id` | Conversa em que o card NASCEU (só preenchida se o vínculo já foi movido). É o que o relatório de origem de lead usa, pra uma venda não mudar de mês nem de anúncio quando o card anda. |
 | `linked_conversations` | jsonb array `[{display_id: 123}, {display_id: 456}]` — múltiplas conversas |
 | `item_details` | jsonb (ver abaixo) |
-| `custom_attributes` | jsonb — campos custom (igual contatos) |
+| `custom_attributes` | jsonb (coluna própria) — **NÃO aparece na aba Campos, no filtro do quadro nem na busca**. Os campos visíveis do card moram em `item_details.custom_attributes` (ver abaixo) |
 | `assigned_agents` | jsonb array de agentes responsáveis |
 | `activities` | jsonb array — log de atividades |
 | `checklist` | **O que fica guardado:** jsonb array de tarefas do card (item: `text`/`completed`/`position` + `group_id`/`group_name` opcionais para agrupar). **O que a API devolve é OUTRA coisa** — ver o aviso logo abaixo |
@@ -172,13 +178,31 @@ Um card individual dentro de uma etapa.
   "offers": [
     {"id": 12, "title": "Pro 12 meses", "value": 4800}
   ],
-  "custom_attributes": {
-    "origem_lead": "Facebook Ads"
-  }
+  "custom_attributes": [
+    {"name": "Origem do Lead", "type": "string", "value": "Facebook Ads"}
+  ]
 }
 ```
 
-**`value`** é onde fica o valor monetário do negócio (usado em pipelines).
+**`value`** é onde fica o valor monetário do negócio (usado em pipelines). Sempre NÚMERO — texto quebra a
+soma das colunas.
+
+**`custom_attributes` é uma LISTA, nunca um objeto `{chave: valor}`** (conferido no código em 18/09/2026).
+Cada item é `{name, type, value}` e só aparece na aba Campos se `name` **e** `type` baterem exatamente com
+um campo de `kanban_config.global_custom_attributes` (leia com `lionchat_kanban_config_list`).
+
+Como gravar pelo `lionchat_kanban_items_update` (`kanban_item.item_details`):
+- O `item_details` é MESCLADO só no 1º nível: cada chave enviada **troca a chave inteira** no card. Por isso
+  a lista `custom_attributes` enviada **substitui a lista toda** — leia o card com `lionchat_kanban_items_show`
+  e reenvie TODOS os campos, com o alterado.
+- Mandar objeto (`{"origem_lead": "Facebook Ads"}`) no lugar da lista **APAGA todos os campos do card**: o
+  servidor só aceita itens `{name, type, value}` e o objeto vira vazio.
+- Lista fechada de chaves do `item_details` (outras são descartadas em silêncio): title, description, status,
+  reason, win_reason, loss_reason, attributed_to, duplicated_from_id, priority, value, currency,
+  custom_attributes, offers, closed_offers, closed_offer, deadline_at, scheduling_type, scheduled_at,
+  conversation_id, automations, notes.
+- Para mudar UM campo sem reenviar a lista, as ações de automação/macro `update_card_attribute`
+  (`[{funnel_id, attribute_key: "<nome do campo>", value}]`) mexem só naquela entrada.
 
 ### assigned_agents
 
@@ -198,6 +222,10 @@ Um card individual dentro de uma etapa.
 
 Múltiplos agentes podem ter o mesmo card. `source` pode ser `manual`, `automation`, `inherited_from_conversation`.
 
+**Para GRAVAR** (`kanban_items_create`/`_update`, `kanban_item.assigned_agents`) o formato é outro: LISTA de
+NÚMEROS — `[5, 12]`. O sistema completa nome, e-mail e foto. A lista enviada **substitui** a atual (mande
+todos que devem ficar). Objetos `{id, ...}` são ignorados em silêncio e a lista não muda.
+
 **Agente do card vira participante das conversas (2026-06):** atribuir um agente a um card do Kanban
 (via `kanban_agents` ou ao vincular uma conversa) agora também o adiciona como PARTICIPANTE de todas
 as conversas do card (a principal `conversation_display_id` + as de `linked_conversations`). É a 4ª
@@ -332,6 +360,9 @@ Endpoint: `GET /api/v2/kanban/items/counts` retorna contagem + soma por etapa.
 Funis agora têm visibilidade por usuário. Um funil é visível pra alguém quando:
 - é admin da conta, OU
 - tem permissão `kanban_view`/`kanban_manage` (custom role), OU
+- tem `funnel_manage` (21/09): quem pode criar/editar/arquivar qualquer funil passou a **enxergar** qualquer funil
+  na lista — antes editava pela API um funil restrito que não aparecia em `funnels_list`. Só o FUNIL: os cards do
+  funil restrito seguem a régua de card, OU
 - o funil está aberto a todos, OU
 - a pessoa participa do funil (está em `settings.agents`, OU é membro de um TIME em `settings.teams` — novo 2026-07-21, membros resolvidos ao vivo — ou tem card atribuído)
 
@@ -342,6 +373,10 @@ Funis agora têm visibilidade por usuário. Um funil é visível pra alguém qua
   `can_edit`, `can_move`, `can_delete`, `can_assign` (booleans)
 - `kanban_items_move` sem permissão → **403** com mensagem traduzida (antes dava 500/sucesso falso)
 - Cards embutidos na tela da conversa também respeitam a visibilidade
+- **Aviso em tempo real do card (21/09):** `kanban_item.created/updated` deixou de ir para a conta inteira — vai só
+  para quem VÊ aquele card (mesma régua acima) + administradores. Quem perde a visão (card passou a outro
+  responsável, mudou de funil) recebe `kanban_item.deleted` com só `{id, funnel_id}`. Integração que escuta o
+  WebSocket com token de usuário restrito recebe menos eventos que antes; com token de administrador, nada muda.
 
 **Pro MCP:** antes de tentar mover/editar card, confira os campos `can_*` do show — se `can_move`
 é false, explique ao usuário que ele não tem acesso àquele funil em vez de tentar mesmo assim.
@@ -534,33 +569,44 @@ Use para: ações cross-cutting que envolvem conversa/contato/label, ou regras c
 
 Cada card pode receber atributos custom de 3 origens diferentes. **A escolha do lugar muda completamente o resultado:**
 
-### 1. `kanban_item.custom_attributes` (jsonb direto no card)
+### 1. `item_details.custom_attributes` (o VALOR de cada campo, dentro do card)
 
 ```json
-{
-  "origem_lead": "Google Ads",
-  "campanha": "Black Friday 2026",
-  "score": 85
-}
+[
+  {"name": "Origem do Lead", "type": "string", "value": "Google Ads"},
+  {"name": "Score", "type": "number", "value": 85}
+]
 ```
 
-- Vai direto no card via `kanban_items_update`
-- Só aparece NESSE card específico
-- Sem typing/validação — qualquer chave/valor
-- Use para: campos específicos de um card, importação rápida sem cadastro prévio
+- É o que a aba **Campos** do card mostra e edita (e o que o filtro do quadro, a busca e o fluxo leem)
+- LISTA de `{name, type, value}`; `name` + `type` precisam bater com um campo do item 2 abaixo, senão o
+  valor fica gravado e **não aparece**
+- Grava via `kanban_items_update` em `kanban_item.item_details.custom_attributes` — a lista enviada
+  **substitui a inteira** (leia o card antes e reenvie tudo). Objeto `{chave: valor}` no lugar da lista
+  **apaga** os campos do card
+- Um campo só, sem reenviar a lista: ação `update_card_attribute` da automação/macro
+
+> **NÃO confundir com a coluna `kanban_item.custom_attributes`** (objeto `{chave: valor}` direto no card):
+> nenhuma tela a mostra — nem a aba Campos, nem o filtro, nem a busca. Só a ação "Alterar atributo do card"
+> do FlowBuilder e a leitura do fluxo a usam. Para o cliente ver o dado, use a lista acima.
 
 ### 2. `kanban_config.global_custom_attributes` (atributos globais do Kanban)
 
 ```json
 [
-  {"name": "Origem do Lead", "type": "list", "is_list": true, "list_values": ["Google", "Meta", "Indicação"]},
+  {"name": "Origem do Lead", "type": "string", "is_list": true, "list_values": ["Google", "Meta", "Indicação"]},
   {"name": "Score", "type": "number", "is_list": false}
 ]
 ```
 
-- Definido no `kanban_config` da conta
-- Aparece em TODOS os cards de TODOS os funis (na sidebar do card)
-- Com tipo (`text`, `number`, `date`, `list`, `boolean`)
+- Definido no `kanban_config` da conta (`lionchat_kanban_config_update`) — é a DEFINIÇÃO; o valor de cada
+  card mora no item 1
+- Aparece em TODOS os cards de TODOS os funis (aba Campos do card)
+- Tipos que a tela cria: `string` (texto), `number`, `date`, `boolean`; lista de opções = `is_list: true` +
+  `list_values`
+- A lista enviada **substitui a inteira** — campo que não vier some da aba de todos os cards. Leia antes com
+  `lionchat_kanban_config_list`
+- **Não confundir com `funnel.global_custom_attributes`** (coluna do funil): nenhuma tela lê aquele campo
 - Use para: atributos que TODO card precisa ter
 
 ### 3. `custom_attribute_definitions` (atributos globais de contato/conversa)
@@ -607,3 +653,66 @@ Cada card pode receber atributos custom de 3 origens diferentes. **A escolha do
 1. Algum card sem `item_details.value`?
 2. Cards arquivados estão sendo contados?
 3. Etapas "ganho"/"perdido" estão incluídas no cálculo?
+
+## Conciliação de vendas — "Importar vendas" (2026-09-24)
+
+O problema que ela resolve: **vendedor não marca a venda certa no card**. Aí o relatório de faturamento
+mente — ou porque o card ficou aberto, ou porque o valor do card não é o valor que o cliente pagou.
+
+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 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 |
+
+### Ferramentas
+
+1. `lionchat_kanban_sales_reconciliation_preview` — **confere e não grava nada**. Chame SEMPRE antes.
+2. `lionchat_kanban_sales_reconciliation_apply` — aplica em segundo plano, devolve `run_id`.
+3. `lionchat_kanban_sales_reconciliation_status` — acompanha até `completed`/`failed`.
+
+O MCP **não sobe arquivo**: as linhas vão em `rows` (lista de objetos). Se a pessoa anexar uma planilha
+na conversa, LEIA o arquivo, monte as linhas em JSON e chame a ferramenta — não peça pra ela converter.
+Quem tem CSV/Excel e prefere a tela usa Kanban > botão azul **+** > **Importar vendas**, que lê o
+arquivo, aponta as colunas e ainda oferece uma planilha de exemplo pra baixar.
+
+### Formato de cada linha de `rows`
+
+| Campo | Obrigatório | Como mandar |
+|---|---|---|
+| `phone` | sim | Com o código do país: `5511999887766` |
+| `value` | sim | `1500`, `"1500,00"`, `"R$ 1.500,00"` ou `"1,500.00"` |
+| `sale_date` | sim | `"01/08/2026"` ou `"2026-08-01"` — o dia em que a venda aconteceu |
+| `name` | não | Nome do cliente (usado no título do card novo) |
+| `email` | não | |
+| `agent` | não | Nome ou e-mail do vendedor |
+| `order_id` | não | Número do pedido, guardado no card |
+
+### O que você PRECISA saber antes de aplicar
+
+- **O telefone tem que vir com o código do país** (`5511999887766`). O sistema **não** completa o 55 —
+  linha sem DDI é recusada com motivo. Celular antigo sem o nono dígito é encontrado do mesmo jeito.
+- **A data da venda é o ponto da funcionalidade.** É ela que faz a venda contar no mês certo do
+  relatório. Sem data, a linha é recusada — nunca vira "hoje" em silêncio.
+- **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.
+- **`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.
+- **Automação de funil que duplica o card no ganho continua rodando** (é um dos dois motores de
+  automação, ver a seção acima). A conferência conta quantos cards de pós-venda vão nascer.
+- **O vendedor da planilha só entra em card SEM responsável** — nunca troca quem já está lá.
+- **Porta:** administrador ou cargo com "importar e exportar cards".
+
+### Diagnóstico: "a venda entrou no mês errado"
+
+Olhe `item_details.status_changed_at` do card: ele é comparado como **texto** contra a janela do
+relatório, e tem que terminar em `Z`. `2026-08-01T03:00:00Z` é 1º de agosto em Brasília; gravar
+`2026-08-01T00:00:00Z` joga a venda pra julho.