@lionchat/mcp-server 1.31.0 → 1.33.0

package/dist/docs/instructions.md

@@ -92,6 +92,16 @@ Account (conta/empresa)
 - Adiar: `lionchat_kanban_items_snooze`. Abrir antes da data: `lionchat_kanban_items_unsnooze`. Regras em
   `lionchat://docs/kanban-deep-dive`, seção "Card adiado".
 
+### Analisar com IA (desde 28/10/2026)
+- A IA lê os cards abertos e adiados das etapas escolhidas de um funil e sugere mudar de etapa ou de funil, pôr/tirar
+  etiqueta e marcar ganho/perdido. Ferramentas `lionchat_kanban_ai_analyses_*`: `setup` -> `create` -> `show` até
+  `ready` -> `items` -> `apply` (com `confirm: true`) -> `show` até `finished`.
+- Quantos cards: `filters.limit` (1 a 1.000, padrão 200). A análise PULA os cards que a IA leu nos últimos 7 dias sem
+  fala nova do cliente; `filters.include_read: true` lê de novo (e gasta crédito de novo). "Por que não mudou nada?":
+  `items` com `no_change: true`.
+- **Aplicar NÃO tem como desfazer**: confirme com o usuário quais cards e ações antes. Regras em
+  `lionchat://docs/kanban-deep-dive`, seção "Analisar com IA".
+
 ### AccountUser.role (string)
 - `agent` (atendente comum)
 - `administrator` (admin/dono)
@@ -187,6 +197,9 @@ Detalhes completos em `lionchat://docs/api-conventions` → "Wrapper de body".
 - **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).
+- **Chave que volta escondida** (`••••••••` ou `[REDACTED]`): é o valor de leitura, não a chave. Desde 27/10 mandar
+  esse valor de volta MANTÉM a chave gravada (chave da TopSend da conta, Hotmart, Kiwify, Ticto, Eduzz, Monetizze e
+  Greenn). Só mande o campo quando for trocar por uma chave nova de verdade.
 
 ### Gravação: TROCA inteira × SOMA (conferido no código em 18/09/2026)
 
@@ -291,7 +304,7 @@ POST /api/v1/accounts/{account_id}/kanban_items
 ```
 
 - `conversation_display_id` é **opcional** (card sem conversa vinculada é válido).
-- As ferramentas `lionchat_kanban_v2_*` cobrem anexos de card/nota e automações do Kanban (controllers criados em 07/2026 — a orientação antiga de ignorá-las está obsoleta). Upload de anexo via MCP segue sem suporte (limitação de file upload).
+- As ferramentas `lionchat_kanban_v2_*` cobrem anexos de card/nota e automações do Kanban (controllers criados em 07/2026 — a orientação antiga de ignorá-las está obsoleta). Arquivo do computador não sobe pelo MCP (não há envio direto de arquivo); arquivo **por link** sobe com `lionchat_upload_create` (`external_url`).
 
 ### Relatório de produtividade
 ```
@@ -317,6 +330,11 @@ teams, conversations_summary) exigem as DUAS pontas; nos demais, `since` ou `unt
 5. Acompanhar com lionchat_campaigns_statistics (sent/delivered/read/failed)
 ```
 Estrutura do audience: `[{type:'Label', id}, {type:'Funnel', id, stages:[], include_won, include_lost}, {type:'ConversationAttribute', key, value}]`.
+Segmento de contatos como público (22/10/2026): `{type:'Segment', id}` no audience e na exclusão
+(`trigger_rules.exclusion`). O id vem de `lionchat_custom_filters_list` com `filter_type: contact` (o segmento é da
+CONTA). Vale para WhatsApp oficial, QR Code e Campanha de Fluxo; SMS e TopSend recusam (422). A regra do segmento é
+lida na HORA do disparo: segmento apagado ou com regra quebrada = a campanha NÃO envia nada e o motivo fica em
+`trigger_rules.audience_error`; na estimativa vem `estimated_count: null` com `segment_unavailable`.
 QR Code aceita `template_params` com `delay_min/delay_max/variations` (anti-bloqueio) e `bulk_actions`.
 
 ### Criar campanha de FLUXO (dispara um flow, não uma mensagem) — novo 28/07/2026
@@ -392,7 +410,7 @@ Antes de QUALQUER ação que escreve, modifica, apaga ou envia, pare e avalie se
 
 **Como confirmar:** descreva o efeito em linguagem do usuário e aguarde o "sim". Ex.: *"Vou apagar o contato #312 — isso remove as 4 conversas dele também. Confirma?"*. Se faltar dado, peça só o que falta (1-2 perguntas), nunca um questionário.
 
-**Ferramentas com trava dura de confirmação.** Algumas ferramentas **recusam a chamada** sem `confirm: true` — a recusa vem do conector, antes de tocar no sistema. Não é erro: é o pedido de OK. O caminho é sempre o mesmo — descreva ao usuário exatamente o que será criado/alterado/apagado, aguarde o "sim", e só então reenvie a MESMA chamada com `confirm: true`. Nunca mande `confirm: true` na primeira tentativa "pra economizar uma volta": a trava existe justamente porque a descrição sozinha não segurava. Hoje: `lionchat_custom_dashboards_create`, `_update` e `_destroy` (relatório personalizado aparece na tela do cliente; alterar substitui a lista de blocos e apagar não tem desfazer).
+**Ferramentas com trava dura de confirmação.** Algumas ferramentas **recusam a chamada** sem `confirm: true` — a recusa vem do conector, antes de tocar no sistema. Não é erro: é o pedido de OK. O caminho é sempre o mesmo — descreva ao usuário exatamente o que será criado/alterado/apagado, aguarde o "sim", e só então reenvie a MESMA chamada com `confirm: true`. Nunca mande `confirm: true` na primeira tentativa "pra economizar uma volta": a trava existe justamente porque a descrição sozinha não segurava. Hoje: `lionchat_custom_dashboards_create`, `_update` e `_destroy` (relatório personalizado aparece na tela do cliente; alterar substitui a lista de blocos e apagar não tem desfazer) e `lionchat_conversations_bulk_destroy` (27/10: apaga de vez até 300 conversas com mensagens e anexos — liste ao usuário quais saem antes do OK).
 
 **Aja sem perguntar apenas em operações idempotentes:** leitura, busca, resumo, classificação.
 
@@ -429,9 +447,11 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 
 | Intenção do usuário | Tool certa | Cuidado |
 |---|---|---|
+| Criar **pasta de conversas para a conta toda** ("Urgentes do time", "Minhas abertas" para cada um) | `lionchat_custom_filters_create` com `filter_type: conversation` + `shared: true` | Só administrador (401). Pelo menos uma condição. Para cada pessoa ver as conversas DELA use `assignee_id` com `values: ["current_user"]`. `shared: false` depois devolve a pasta a quem mandou. Detalhe no resource api-conventions |
 | Listar / ver não lidas | `lionchat_conversations_list` (`conversation_type: 'unread'`) ou `lionchat_conversations_meta` | NÃO use `lionchat_conversations_unread` — é AÇÃO DE ESCRITA (marca como não-lida) |
 | Ver **uma empresa** (quem trabalha la, anotacoes, conversas) e ligar/tirar contatos | `lionchat_companies_show` + `lionchat_companies_contacts_list` / `_create` / `_destroy`, `lionchat_companies_notes_list`, `lionchat_companies_conversations_list` | Ligar pela ficha: `lionchat_contacts_update` com `company_id` (null tira). Cargo da pessoa = `additional_attributes.job_title`. Escolher a empresa troca o texto `company_name` pelo nome dela |
 | Criar / preencher **campo personalizado da empresa** ("Segmento", "Data de fundacao") | `lionchat_custom_attributes_create` com `attribute_model: company_attribute` + `lionchat_companies_update` com `company.custom_attributes {chave: valor}` | So com o modulo Empresas ligado; tipo segredo recusado. Chave que nao existe como atributo de empresa = 422 e nada do pedido grava: crie a definicao ANTES. MESCLA; `null` limpa. Desde 2026-10-16 vira variavel `{{contact.company.custom_attribute.CHAVE}}`, condicao do fluxo (`attrSource: company`), condicao de automacao e filtro de contatos (`custom_attribute_type: company_attribute`) e a IA le — detalhe no resource data-model |
+| **Importar muitas empresas** de uma vez (planilha, lista de clientes, cadastro de outro sistema) | `lionchat_companies_bulk_create` (ate 1000 por chamada; `check_only: true` CONFERE sem gravar) e depois `lionchat_companies_import_status` com o `import_id` | Mesma importacao do botao "Importar empresas" da tela. Mesma empresa = CNPJ; sem CNPJ, o site; sem os dois, o NOME — mais de uma empresa com aquele nome = a linha NAO entra (mande CNPJ ou site). Empresa existente e ATUALIZADA; campo vazio nunca apaga. Valor invalido fica em branco com aviso e o resto entra. Campos PLANOS (`address_city`, `social_instagram`), nunca objeto; `custom_attributes` so com chave que ja existe como atributo de EMPRESA. Exige modulo Empresas + administrador ou cargo "Exportar e importar contatos". So no conector remoto (Claude.ai/ChatGPT); no conector local (NPM) importe com `lionchat_companies_create` uma a uma |
 | Organizar atributos em **categorias** (pastas que abrem e fecham: "Sobre a casa", "Financeiro") | `lionchat_custom_attribute_categories_create` (`name` + `attribute_model`) e depois `lionchat_custom_attribute_categories_assign` (`attribute_key` + `category_id`; `null` tira) | Categoria e OPCIONAL e de UMA aba so (`conversation_attribute`, `contact_attribute`, `company_attribute` ou `kanban_item_attribute` = Card). Criar categoria NAO aceita atributos junto. Card: `attribute_key` = NOME do campo exatamente como gravado. Excluir categoria nunca apaga atributo (voltam para "Sem categoria"). Ver resource data-model |
 | Achar a conversa **de uma pessoa/empresa** (nome, telefone, e-mail, CPF/CNPJ, nº da conversa) | `lionchat_search_list` (`/search/conversations`) ou `lionchat_contacts_search` | RÁPIDO. **NÃO use `lionchat_conversations_search`**: apesar do nome, ele é o legado que procura dentro das mensagens e leva **15 a 22 s** (medido em produção 11/08). O sufixo `_list` aqui é histórico — `lionchat_search_list*` **são buscas**, não listagens; a regra "não baixe tudo com `*_list`" vale para `lionchat_<recurso>_list` |
 | Achar **onde foi dito** algo (palavra dentro da conversa) | `lionchat_search_list_2` (`/search/messages`) | RÁPIDO: índice trigram próprio e teto de tempo em duas fases (2 s / 2 s desde 04/09 — antes a 2ª fase herdava 14 s e o pior caso da seção era 16 s). Estourou as duas, o payload volta com `message_search_interrupted: true` e a lista VAZIA — isso NÃO quer dizer que não existe, quer dizer que não deu tempo: tente de novo. É a substituta certa do `lionchat_conversations_search` |
@@ -441,11 +461,12 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 | Criar contato | `lionchat_contacts_create` base (path `/contacts`) | NÃO use as variantes `_1` … `_9` |
 | Pausar a IA agora (botão de pânico) | `lionchat_captain_assistants_update` (`paused: true`, top-level) | — |
 | Criar/editar **formulário público de captação** (página de captura própria) | `lionchat_lead_forms_create` / `_update` | Leia `lionchat://docs/formularios-publicos` ANTES — o desenho vai em `form_data` e só entra no ar depois do `publish` (que valida o desenho e pode voltar 422 com a lista de pendências). Caixa de WhatsApp vinculada (`inbox_id`) é obrigatória pra publicar. Escrita é só de administrador |
-| **Mandar um contrato pra assinar** / ver quem assinou / reenviar / cancelar / criar ou editar o modelo escrito | `lionchat_signature_envelopes_create` / `_list` / `_show` / `_resend` / `_cancel`; `lionchat_signature_documents_list` / `_create` / `_update`; `lionchat_signature_envelopes_sign_as_sender` (o remetente assina pelo painel) | Leia `lionchat://docs/assinatura-eletronica` ANTES. Modelo `text` a API cria e edita (texto com `{{contact.*}}`); PDF/Word só pela tela. Campo do modelo sem valor na ficha bloqueia o envio (422 `variaveis_sem_valor` com a lista); `422 escolher_caixa` = repita com `inbox_id`. Cada contrato consome 1 vaga do limite mensal. Modelo Word: `422 fila_cheia` = muita gente convertendo agora, repita em instantes; `422 conversor_indisponivel` = o serviço de conversão está fora (não é o arquivo) — avise o operador. Remetente assina pelo painel com `_sign_as_sender` (PNG em base64). Importar Word, pré-visualizar e baixar PDF: só pela tela (o conector não envia arquivo nem recebe PDF) |
+| **Mandar um contrato pra assinar** / ver quem assinou / reenviar / cancelar / criar ou editar o modelo escrito | `lionchat_signature_envelopes_create` / `_list` / `_show` / `_resend` / `_cancel`; `lionchat_signature_documents_list` / `_create` / `_update`; `lionchat_signature_envelopes_sign_as_sender` (o remetente assina pelo painel) | Leia `lionchat://docs/assinatura-eletronica` ANTES. Modelo `text` a API cria e edita (texto com `{{contact.*}}`); PDF/Word só pela tela. Campo do modelo sem valor na ficha bloqueia o envio (422 `variaveis_sem_valor` com a lista); `422 escolher_caixa` = repita com `inbox_id`. Cada contrato consome 1 vaga do limite mensal. Modelo Word: `422 fila_cheia` = muita gente convertendo agora, repita em instantes; `422 conversor_indisponivel` = o serviço de conversão está fora (não é o arquivo) — avise o operador. Remetente assina pelo painel com `_sign_as_sender` (PNG em base64; `signature_method` drawn/typed + `typed_name`). Dois jeitos de mandar (27/10): `collection: 'ready'` (completa o que falta com `contact_data`; veja antes `lionchat_signature_documents_fill_fields`) ou `collection: 'form'` (a pessoa preenche pelo link); `message` vai junto. Documentos pedidos (28/10, `roles_layout.required_proofs`): contrato fica `awaiting_approval` até a equipe aprovar — `lionchat_signature_envelopes_proofs` / `_approve_proofs` / `_reject_proofs` (as duas últimas mandam mensagem ao cliente: confirme antes; os arquivos só pela tela). Link do contrato para divulgar: `roles_layout.public_link`. Importar Word, pré-visualizar e baixar PDF: só pela tela (nesta área o conector não sobe o Word do modelo nem baixa o PDF) |
 | **Testar um formulário** antes de publicar | `lionchat_lead_forms_test_run` | Roda o RASCUNHO no motor real e desfaz tudo no fim — zero rastro. Mande `answers: [{node_id, value}]` (até 60) pra reproduzir um caminho; a resposta traz o bloco atual + o log do percurso |
 | Conferir se um site **aceita ser exibido dentro do formulário** (bloco Página externa) | `lionchat_lead_forms_check_embed` | Body `{url}`; devolve `{status: allowed\|blocked\|unknown, reason}`. Grave o veredito em `embed_allowed` do bloco. Admin-only |
 | Ver **tudo que uma pessoa preencheu** (nosso formulário, anúncio do Meta, Webhook Universal, fluxo) | `lionchat_contacts_form_entries_list` / `_show` | Por CONTATO, sem paginação (teto 250 por origem, `meta.truncated`). O detalhe de Meta/webhook mostra SÓ os campos vinculados e gravados — nunca o payload cru. `show` exige `source` + `id` da mesma linha |
-| Anexar arquivo a uma mensagem | `lionchat_upload_create` primeiro, depois usar o retorno em `lionchat_conversations_messages_create` | Confira `lionchat_upload_limits` se o arquivo for grande |
+| Anexar **arquivo** a uma mensagem — foto, vídeo, áudio, PDF, Word, Excel, CSV, ZIP (inclusive na conversa de um **grupo** do WhatsApp) | `lionchat_upload_create` com `external_url` (link PÚBLICO de download do arquivo) → o `blob_id` devolvido vai no array `attachments` de `lionchat_conversations_messages_create` | Pelo conector o arquivo SEMPRE vai por link (não há envio direto do computador). Link que abre uma PÁGINA (ex.: Drive `.../view`) é recusado — use o download direto (Drive: `https://drive.google.com/uc?export=download&id=<ID>`); confira antes com `lionchat_upload_validate`. Teto por tipo em `lionchat_upload_limits_show`. Até 23/10/2026 o link só aceitava foto e vídeo |
+| Mandar um **relatório todo dia num grupo** do WhatsApp | Em texto: `lionchat_report_alerts_create` (resumo diário de um relatório personalizado, enviado pelo próprio servidor). Em PDF: gere o PDF, publique num link de download e siga a linha acima | O conector não agenda nada: "todo dia" em PDF depende de uma tarefa agendada do lado de quem usa o conector. Grupo só existe em caixa WhatsApp QR Code — ache a conversa do grupo com `lionchat_conversations_list`/busca. Receita em `lionchat://docs/best-practices` |
 | Marcar conversa como **lida** | `lionchat_conversations_update_last_seen` | NÃO use `unread` (esse marca como NÃO-lida) |
 | Criar/gerenciar **campanha** (disparo WhatsApp/SMS) | `lionchat_campaigns_*` (criar, estatísticas) | SEMPRE rode `campaigns_estimate_audience` antes de criar e mostre a contagem. Disparo em massa = confirmação obrigatória (seção 7b) |
 | Criar **flow normal** (responde mensagens na caixa) | `lionchat_flows_create` | Ler design-guide antes (seção 11). Escolha `conversation_mode`: `individual` (1-a-1, default) ou `group` (grupo WhatsApp — só aqui existe o node `update_group`; sem LionTrack). Imutável após criar |
@@ -477,6 +498,7 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 | **Migrar conversas** de uma caixa WhatsApp pra outra (ex.: QR Code → Oficial) | `lionchat_inboxes_inbox_migration_list` (prévia) → `_execute` → acompanhar status | Admin-only e IRREVERSÍVEL: sempre mostre os números da prévia e confirme (seção 7a). Grupos não vão pro canal oficial — ficam na caixa de origem |
 | Qualquer coisa de Ligação WP (Wavoip) | **INTEGRAÇÃO REMOVIDA em 12/08/2026** — não há tool nem tela | A Wavoip saiu do produto: a aba "Ligação WP" **não existe mais**. NUNCA orientar o usuário a "Configurações da caixa → Ligação WP". Para voz em caixa QR Code, o caminho hoje é o **LionCalls**. As ligações antigas seguem no histórico (`provider: "wavoip"`); as gravações delas ficavam no servidor da Wavoip e vão sumir — ao tentar ouvir, o painel mostra "Esta gravação não está mais disponível", e isso é esperado, não é defeito. |
 | Restringir agendas que a IA oferece | `lionchat_captain_assistants_update` (`config.booking_event_type_ids: [Int]`) | binding de agenda por cenário NÃO é settable via API |
+| **Tarefas atrasadas / o que falta fazer** (da equipe ou de uma pessoa) | `lionchat_tasks_task_list` (`assignee_id`, `q`, `priority`, `group` + `page`) | Só tarefas ABERTAS, em grupos `overdue`/`today`/`tomorrow`/`next_7_days`/`later` no dia da conta; 50 por grupo — conte por `totals`. Mesma regra de quem vê o quê do calendário. Ver `lionchat://docs/agenda-multiplas-unidades` §7.2 |
 | **Programa de sessões** de um contato ("em que sessão ele está", ajustar total, encerrar/reabrir) | `lionchat_agenda_treatments_list` (por `contact_id`) / `_show` / `_update` | NÃO existe create: o programa nasce junto do agendamento (na TELA chama-se "programa"; na API segue `treatment`). Marcar TODAS de uma vez: `plano_sugerido` + `marcar_todas` de um tipo com `sessions_enabled` (`tasks_create` modo booking, `treatment: {...}` por pessoa; "marcar próxima" = `agenda_treatment_id` + `treatment_session_number`). Faltar CONSOME a sessão. Ver `lionchat://docs/agenda-multiplas-unidades` §7 |
 | Configurar o Copiloto (modelo/temperatura/prompt base) | `lionchat_copilot_settings_update` | admin-only; copiloto tem motor próprio (padrão temp 0.3) |
 | **Resetar/testar do zero a IA** numa conversa | `lionchat_conversations_captain_history_reset` (POST, sem body) | Cria pílula de marco na conversa; a partir dali TODA leitura autônoma da IA (respostas, resumo, follow-up) considera só mensagens pós-marco. Não apaga nada; o atendente segue vendo tudo. Enterprise-only |

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

@@ -276,8 +276,64 @@ e se está atrasada.
   um. Compromisso de agenda que o usuário não enxerga aparece na sessão como `oculta: true`.
 - O relatório de Agendamentos tem o bloco `treatments` (vale o período escolhido: programas, sessões do período e quem parou no meio — ver `reports-guide`).
 
+## 7.1. Tarefa automática do card — de que agenda ela é (20/10/2026)
+
+A regra "Criar tarefa" do funil (`create_task`) e o item "Criar tarefa" do bloco Ações do fluxo (`create_account_task`)
+criam uma tarefa COMUM da Agenda, presa ao card (`kanban_item_id`). Para a agenda:
+
+- `agenda_id` da regra **nulo = a agenda padrão da conta**. A tarefa na agenda padrão é gravada com `agenda_id`
+  nulo (a mesma regra do resto deste guia: nulo = principal; ao filtrar a principal, inclua os nulos).
+- O **fuso do prazo é o da agenda da tarefa** (o fuso resolvido da agenda; sem agenda padrão, o da conta).
+- **Dia útil** (`due.business_days: true`, só com `unit: 'days'`) = segunda a sexta **sem feriado de DIA INTEIRO que
+  vale para aquela agenda**. Feriado de meio período não conta (o dia ainda tem expediente). Feriado "para todas as
+  agendas" (`all_agendas`) vale para qualquer agenda; o regional vale só para as agendas marcadas nele. Cadastre
+  com `lionchat_agenda_holidays_*`. **Só o prazo da tarefa automática lê feriado**: os horários livres do Booking
+  continuam sem saber de feriado, e feriado nunca impede alguém de marcar.
+- A Agenda unificada (`unified_agenda`) precisa estar ligada na conta; desligada, a regra do funil registra "não
+  criou" no histórico do card e o item do fluxo fica com erro visível no passo.
+- `occupies_agenda: false` (padrão da regra) cria a tarefa como lembrete que **não bloqueia o horário**; `true`
+  bloqueia como um compromisso, do prazo até o fim da duração. `duration_minutes` (22/10/2026, 1 a 1440) escolhe a
+  duração; ausente = o tempo do tipo (Tarefa 15, Ligação 30, Reunião 60, tipo da conta 30).
+
 ---
 
+## 7.2. Lista de tarefas abertas — aba "Tarefas" da Agenda (22/10/2026)
+
+A Agenda ganhou a aba **Tarefas**, entre Calendário e Disparos: as tarefas abertas em lista, separadas por
+período. A ferramenta é `lionchat_tasks_task_list` (`GET account_tasks/task_list`). Use-a para "o que está
+atrasado?", "quantas tarefas a fulana tem em aberto?" e "o que falta fazer esta semana?".
+
+- **Aberta** = pendente ou adiada E sem "Compareceu"/"Faltou". Concluídas e canceladas não entram.
+- **Grupos**, no dia da conta: `overdue` (antes de hoje, da mais recente para a mais antiga), `today`,
+  `tomorrow`, `next_7_days` e `later`.
+- **Quem vê o quê e filtros**: os MESMOS do calendário (`lionchat_tasks_list`): `assignee_id`, `task_type`,
+  `status` (0 pendente, 3 adiada), `priority`, `agenda_id`, `q`. Quem não gerencia a agenda da equipe vê só as
+  próprias, com ou sem `assignee_id`.
+- **50 por grupo**. Para quantidade, leia `totals` (a contagem real), nunca o tamanho da lista. Para ir além das
+  50: `group=overdue&page=2` devolve só aquele grupo naquela página.
+- **Busca `q`** (vale também no calendário): título, descrição, responsável e, com 3 letras ou mais, o CLIENTE
+  (nome, telefone, e-mail). Termo que casa mais de 1.000 clientes procura só nos campos da tarefa.
+- O "Meu Dia" (`lionchat_tasks_list_1`) continua existindo como estava: sem filtros, sem páginas e sem `later`.
+- Cargo com a Agenda escondida recebe 401 aqui.
+- **Prioridade**: o filtro `priority` passou a funcionar em 22/10 (antes o servidor o ignorava, inclusive no
+  calendário).
+
+### 7.3. Subaba "Concluídas" e datas de desfecho (23/10/2026)
+
+- **`group=completed`** em `lionchat_tasks_task_list` = a subaba "Concluídas": tarefa concluída OU marcada
+  "Compareceu"/"Faltou". Cancelada fica de fora (só no calendário). Não vem junto dos cinco grupos: só quando
+  pedida. Ordem: a mais recentemente concluída primeiro; as concluídas antes de 23/10 (sem data de conclusão) vão
+  para o fim, pela data da tarefa. 50 por página, `totals.completed` = a contagem real.
+- **Datas de desfecho** em toda tarefa (calendário, `show` e lista): `completed_at` (quando foi concluída),
+  `cancelled_at` (quando foi cancelada) e `attendance_marked_at` (quando marcaram Compareceu/Faltou). Gravadas pelo
+  servidor no momento da mudança, nunca aceitas do cliente. Reabrir, adiar ou limpar a presença APAGA a data
+  (é a data do desfecho atual, não um histórico). Nada antes de 23/10 foi preenchido: tarefa antiga vem com nulo.
+- **`concluida_no_prazo`** (true/false/nulo): só no tipo Tarefa. `true` = concluída até o horário marcado
+  (`scheduled_at`; adiar vale a data nova). Nulo = não se aplica (outro tipo, não concluída, ou concluída antes de
+  existir a data). Consulta e reunião não têm prazo: só se dão como feitas depois que acontecem.
+- **Busca `q`** (vale na lista e no calendário) passou a achar também pelo NOME DO CARD da tarefa e, com 3 letras
+  ou mais, por QUEM FEZ: quem criou, o dono antigo da tarefa e o "Agendado por".
+
 ## 8. Erros comuns
 
 | Sintoma | Causa |

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

@@ -484,6 +484,33 @@ GET /search/conversations?q=pix&conversation_filters=[{"attribute_key":"status",
 - `kanban_card` — por card vinculado (funil/etapa/prioridade/status)
 Combináveis com E/OU e salváveis como segmento (custom_filters).
 
+### Segmento de contatos é da CONTA (2026-10-22)
+
+`custom_filters` com `filter_type: contact` (segmento) passou a ser da conta inteira: todos veem e usam (quem tem o
+menu Contatos no cargo). Criar, editar e apagar segmento = administrador ou cargo com `contact_manage`,
+`campaign_manage` ou `automation_manage` — sem isso, 401. Quem criou não ganha direito extra; a resposta traz
+`user_id`/`user_name` ("criado por", pode vir nulo) e `can_manage`. Relatórios (`report`) continuam pessoais; pastas de
+conversa (`conversation`) são pessoais até um administrador compartilhar (seção seguinte). `filter_type` é IGNORADO no update (não dá para trocar o tipo). Regra vazia ou
+incompleta = 422. Segmento usado por campanha programada não pode ser apagado (422 citando a campanha). Segmento serve
+de público de campanha (`{type: 'Segment', id}`) — ver a receita de campanha nas instruções.
+
+### Pasta de conversa compartilhada (2026-10-27)
+
+Pasta de conversa (`filter_type: conversation`) com `shared: true` aparece para TODA a conta, com o ícone de
+compartilhar. Só administrador cria, edita, compartilha, descompartilha ou apaga (sem isso, 401); o atendente vê e
+usa, mas não edita. Cada pessoa vê dentro dela SÓ as conversas que já pode ver — a pasta não abre acesso. Regras:
+
+- Só mande `shared` para MUDAR o compartilhamento. `shared: false` numa compartilhada a transforma em pasta pessoal de
+  quem mandou (some para os outros). `shared` nulo = 422. Segmento e relatório não podem ser compartilhados (422).
+- Compartilhada precisa de pelo menos uma condição (422 sem nenhuma).
+- `query.sort_by` de uma compartilhada é a ordem PADRÃO de todos. A troca de ordem feita dentro da pasta pela tela vale
+  só para quem trocou e não é gravada.
+- Em compartilhada criada por outra pessoa, `user_id`/`user_name` vêm nulos.
+- "Quem está vendo": condição `{"attribute_key": "assignee_id", "filter_operator": "equal_to", "values": ["current_user"]}`
+  mostra a cada pessoa as conversas DELA. Vale também em `lionchat_conversations_filter` e nos `conversation_filters` das
+  buscas. Texto em `assignee_id` que não seja número nem `current_user` = 422. Automação NÃO aceita `current_user` (422).
+- Apagar uma compartilhada tira a pasta de todos. Pessoa removida da conta não leva a compartilhada que criou.
+
 ### Exportação de contatos (2026-06-10)
 
 `POST /contacts/export` (chega por e-mail) agora sai COMPLETO: cadastral achatado (16 colunas),

package/dist/docs/resources/assinatura-eletronica.md

@@ -10,14 +10,14 @@ Feature `document_signing` (ligada por conta; 403 `feature_disabled` quando desl
 | Camada | O que é | Ferramentas |
 |---|---|---|
 | **Modelo** (`signature_documents`) | O contrato padrão, escrito uma vez com `{{variáveis}}` da ficha. `kind`: `text` (escrito no editor — o único que a API cria), `file` (PDF pronto, igual pra todos) ou `word` (.docx que sai idêntico com os campos mapeados) — os dois últimos só pela tela (upload). | `lionchat_signature_documents_list/show/create/update/destroy/field_catalog` |
-| **Contrato** (`signature_envelopes`) | Cada ENVIO a uma pessoa: PDF próprio com os dados dela, prazo, linha do tempo. | `lionchat_signature_envelopes_list/show/create/resend/cancel/limits` |
+| **Contrato** (`signature_envelopes`) | Cada ENVIO a uma pessoa: PDF próprio com os dados dela, prazo, linha do tempo. | `lionchat_signature_envelopes_list/show/create/resend/cancel/limits`; documentos de quem assina: `_proofs` / `_approve_proofs` / `_reject_proofs` |
 | **Participante** | Quem assina dentro de um contrato: `signer` (titular, pode ser mais de um), `witness` (testemunha, opcional), `sender` (o remetente, quando o modelo tem "eu também assino" — assina NO PAINEL, sem link). Cada um tem link e código próprios. | dentro do contrato (`participants[]`) |
 
 ## Estados do contrato (`status`) e os baldes de filtro
 
 | Balde (`status` na listagem) | Estados | Significado |
 |---|---|---|
-| `aguardando` | `draft`, `sent` | criado sem entrega (draft) ou enviado e ainda não aberto |
+| `aguardando` | `draft`, `sent`, `awaiting_data`, `awaiting_approval` | criado sem entrega (draft), enviado e ainda não aberto, "aguardando formulário" (a pessoa ainda não preencheu os dados — o contrato ainda não existe) ou (28/10) "aguardando aprovação dos documentos" (todos assinaram, falta a equipe aprovar os documentos pedidos) |
 | `visualizado` | `viewed`, `partially_signed` | abriu o link / parte das pessoas já assinou |
 | `assinado` | `signed_pending_seal`, `signed` | todos assinaram; selando / documento final pronto |
 | `encerrado` | `refused`, `cancelled`, `expired` | recusado / cancelado pela equipe / prazo venceu |
@@ -27,10 +27,15 @@ Participante: `pending` → `viewed` → `verified` (confirmou o código) → `s
 
 ## Linha do tempo (`events[].kind`)
 `created` · `delivered` (link entregue a uma pessoa) · `sent` · `opened` (cada abertura) · `code_requested` ·
-`code_verified` · `signed` (com `ip`, `device`, `location`; `panel: true` = assinou no painel) · `all_signed` ·
+`code_verified` · `signed` (com `ip`, `device`, `location`; `panel: true` = assinou no painel; desde 28/10
+`signature_method` `drawn` = desenhada ou `typed` = o nome digitado numa letra de assinatura, com `typed_name`) · `all_signed` ·
 `sealed` (documento final gerado, `sealed_sha256`) · `refused` · `cancelled` · `expired` · `delivery_failed`
 (motivo em `delivery.failed[]`) · `reminded` · `resent` · `copy_sent` / `copy_failed` (a via assinada de cada pessoa,
-estado em `delivery.copies[]`). Tudo append-only — é o relatório de evidências. `delivery.failed[]` também mostra a
+estado em `delivery.copies[]`) · `data_filled` (27/10: a pessoa preencheu o formulário e o contrato foi gerado com os
+dados dela) · (28/10) `proof_sent` (a pessoa mandou um documento pedido: `kind`, `document_type`) ·
+`awaiting_approval` (o contrato passou a esperar a equipe, ou a pessoa reenviou depois de reprovada) · `proofs_approved`
+/ `proofs_rejected` (com `reason` e quem decidiu). `code_requested`/`code_verified` com `method: "whatsapp"` = a pessoa
+confirmou mandando a frase pelo WhatsApp, não pelo código. Tudo append-only — é o relatório de evidências. `delivery.failed[]` também mostra a
 recusa que a Meta manda depois (caixa oficial fora da janela de 24 h, motivo `window_expired`) e some sozinha se a
 mensagem acabar entregue.
 
@@ -46,6 +51,66 @@ pelo mesmo canal do link: anexada numa mensagem na conversa dela (WhatsApp) ou n
 pedindo que peça a via a quem enviou). Quem assinou no painel não recebe. Não há ferramenta para mandar de novo: oriente
 baixar na tela do documento. O código de 6 dígitos de quem assina por e-mail chega no próprio e-mail.
 
+## Os dois jeitos de mandar (27/10)
+- **Contrato pronto** (padrão, `collection: 'ready'`): o contrato sai agora com a ficha. Se faltar dado, mande junto
+  `contact_data: { 'contact.marital_status': 'casado' }` — vai para a ficha e para o contrato (erro de um campo volta
+  `422 dados_invalidos` com `field_errors`). Para saber o que falta antes: `GET .../signature_documents/:id/fill_fields?contact_id=`.
+- **Formulário para a pessoa preencher** (`collection: 'form'`, exige `contact_id`): o link vai SÓ para o titular, ele
+  preenche os dados dele (em branco) e o contrato nasce com o que ele digitou; o que ele digita atualiza a ficha. O
+  contrato fica `awaiting_data` até lá. O link de quem preenche é o `participants[].public_url` do titular na resposta.
+- Nos dois: `message` (até 1.000 caracteres) vai junto do link.
+- `fill_fields` devolve cada campo que se preenche pela ficha (`value` e `missing`) e `blocked` = o que falta e NÃO se
+  preenche por ali (telefone, dados da conta) — com algo em `blocked` o contrato pronto volta `variaveis_sem_valor`;
+  `blocked_in_form` é o mesmo para o jeito formulário (lá o nome também é perguntado).
+- **Como o formulário pergunta** (`roles_layout.field_prompts` no modelo): `{"contact.cpf": {"label": "Qual é o seu
+  CPF?", "description": "Igual ao documento", "placeholder": "000.000.000-00"}}` — texto até 200 caracteres; sem
+  pergunta, o formulário mostra o nome do campo; pergunta de variável que o modelo não usa é descartada ao salvar.
+- Modelo de **Word** com campo sem escolha no mapeamento: o envio volta `422 campos_sem_escolha` (`missing` = os
+  rótulos do Word) antes de gastar a vaga do mês — ajuste o mapeamento pela tela.
+
+## Como a pessoa assina (28/10)
+Na página do link (e no "Assinar agora" do painel) há duas abas: **Desenhar** (com o dedo ou o mouse) e **Digitar**
+(o nome já vem escrito, pode ser corrigido, e aparece em três letras de assinatura). Os dois valem igual — quem prova
+a autoria é o código de uso único. A folha de assinaturas e o relatório de evidências dizem "Assinatura desenhada à
+mão" ou "Assinatura digitada: <nome>"; contratos assinados antes de 28/10 não dizem nada.
+
+## Documentos de quem assina (28/10)
+- No modelo, `roles_layout.required_proofs`: lista com `id_document` (documento com foto — a pessoa escolhe RG, CNH ou
+  CPF), `selfie_with_document` e `address_proof` (comprovante, foto ou PDF). `[]` = nenhum. Outro valor = 422. O
+  contrato guarda uma cópia ao nascer: mudar o modelo depois não muda contrato já enviado (`required_proofs` vem no
+  `list` e no `show` do contrato).
+- A pessoa manda os documentos na página, antes de assinar. Com algum documento pedido, o contrato NÃO fecha quando
+  todos assinam: fica `awaiting_approval` e quem enviou recebe aviso no sininho.
+- `lionchat_signature_envelopes_proofs` mostra, por pessoa, os documentos mandados (tipo, formato, quando — nunca o
+  arquivo) e a revisão (`pending`/`approved`/`rejected`, motivo, quem, quando) e o `last_proof_event_id`.
+- **Os arquivos NÃO saem por ferramenta** (documento de identidade e selfie são dado sensível): para olhar, oriente a
+  tela — botão amarelo "Ver documentos" no contrato ou na aba Contratos da ficha. Aprovar sem alguém ter olhado o
+  arquivo na tela não faz sentido: pergunte ao usuário se ele já conferiu.
+- `lionchat_signature_envelopes_approve_proofs` (`participant_id`, `seen_event_id` = o `last_proof_event_id` que a pessoa
+  viu): com todos aprovados o contrato fecha e cada um recebe a via. `lionchat_signature_envelopes_reject_proofs`
+  (`participant_id`, `reason` obrigatório, `seen_event_id`): a pessoa recebe no canal dela o pedido de documento novo com
+  o motivo. As duas MANDAM mensagem ao cliente — confirme com o usuário antes. 422: `fora_do_momento` (contrato não está
+  esperando aprovação), `sem_documentos`, `motivo_obrigatorio`, `documentos_mudaram` (a pessoa mandou outro depois do
+  que foi visto — leia `_proofs` de novo). Quem pode: administrador ou `signature_manage`.
+
+## Confirmar pelo WhatsApp (28/10)
+Quem recebe o link pelo WhatsApp pode confirmar que é ela mandando uma frase pronta (com um código `CT-XXXXXX`) para o
+WhatsApp do contrato, em vez de digitar o código de 6 dígitos — resolve a caixa oficial com a janela de 24 h fechada.
+Só vale do telefone da pessoa e na caixa do contrato. A mensagem aparece na conversa, mas a IA, os fluxos e as
+automações não respondem a ela. Não há ferramenta: é só a página da pessoa.
+
+## Link do contrato para divulgar (28/10)
+- No modelo, `roles_layout.public_link: {enabled: true, inbox_id: <caixa de WhatsApp da conta>}`. A leitura devolve
+  `{enabled, inbox_id, path}` — o endereço é o domínio da instalação + `path` (`/contrato/<código>`). Mande
+  `regenerate: true` para trocar o código (o endereço antigo para de funcionar). Salvar sem `regenerate` mantém o
+  mesmo endereço; desligar e religar também.
+- Só para modelo com UM assinante principal e sem `sender_signs` (422 com `public_link` no texto do erro), e só caixa de
+  WhatsApp (oficial ou QR Code).
+- Quem abre o endereço manda a mensagem pronta pelo WhatsApp; o contrato dela nasce sozinho no jeito Formulário, na
+  conversa dela (`additional_attributes.link_padrao: true`). Se o modelo tem testemunha, o formulário pergunta nome e
+  WhatsApp de cada uma. A mesma pessoa pedindo de novo em 24 h recebe o mesmo contrato.
+- **Limite do mês:** o contrato do link só conta depois que a pessoa confirma que é ela. Quem abre e some não gasta vaga.
+
 ## Como mandar um contrato (receita)
 1. `lionchat_signature_documents_list` → escolha o modelo (ou crie um `text` com `signature_documents_create`;
    variáveis em `signature_documents_field_catalog`).
@@ -73,19 +138,24 @@ baixar na tela do documento. O código de 6 dígitos de quem assina por e-mail c
 - **Fila única de conversão do Word**: uma conversão por vez em toda a instalação (todas as contas); pela tela espera-se até 10 s, automação/macro/fluxo/formulário até 2 s.
   Passou disso o envio/prévia volta `422 fila_cheia` — é só repetir em instantes (o modelo está bom).
 - **Limite mensal** (`signature_envelopes_limits`): cada contrato criado consome 1 vaga; cancelar não devolve.
+  Exceção (28/10): o contrato que nasce do link do modelo só conta depois que a pessoa confirma. O teto por conta é
+  ajustado pelo operador da plataforma (fora do MCP).
 - **PDFs** (original, assinado, evidências) e o **QR de conferência** só existem pela tela/download autenticado —
   não há ferramenta que devolva os bytes. O `sealed_sha256` é o hash do documento final. Exceção desde 15/10: a via
   assinada vira anexo da mensagem na conversa de quem assinou por WhatsApp, então aparece nas ferramentas de mensagens
   da conversa (`conversations_messages_*`).
 - **Só pela tela, de propósito** (existem na API, mas NÃO como ferramenta): importar um Word (`import_docx`),
-  pré-visualizar modelo ou rascunho (`preview`, `preview_draft`) e baixar PDF (`download`). O conector não envia
-  arquivo nem recebe PDF — não prometa "vou gerar a prévia" ou "vou baixar o assinado"; oriente a tela.
+  pré-visualizar modelo ou rascunho (`preview`, `preview_draft`) e baixar PDF (`download`). Nesta área o conector
+  não sobe o Word do modelo nem baixa o PDF — não prometa "vou gerar a prévia" ou "vou baixar o assinado"; oriente a tela.
 - **Assinar no painel** ("eu também assino", 08/09): `lionchat_signature_envelopes_sign_as_sender` assina como o
   REMETENTE (a pessoa do token) — nunca no lugar do cliente. Manda `signature_image` (PNG em base64 com prefixo
-  `data:image/png;base64,...`), opcional `location {latitude, longitude, accuracy}` (vai pra prova) e
-  `remember_drawing`. 422: `nao_e_sua` (não é o remetente deste contrato), `ja_assinado`, `sem_desenho`. Era a
+  `data:image/png;base64,...`), opcional `location {latitude, longitude, accuracy}` (vai pra prova),
+  `remember_drawing` e (28/10) `signature_method` (`drawn` ou `typed`) + `typed_name` — a folha de assinaturas diz
+  "Assinatura desenhada à mão" ou "Assinatura digitada: <nome>"; sem o campo, não diz nada. 422: `nao_e_sua` (não é o remetente deste contrato), `ja_assinado`, `sem_desenho`. Era a
   última que faltava? o contrato fecha e o PDF final é gerado em seguida. Os que esperam você: `status=falta_eu`.
-- **Envio por outros caminhos**: ação `send_signature_document` no FlowBuilder, na Macro e na Automação;
+- **Envio por outros caminhos**: ação `send_signature_document` no FlowBuilder (28/10: `collection` `ready`/`form`,
+  `message` junto do link e `send_link: false` para só gerar; o contrato criado vira `{{contrato.*}}`, com
+  `{{contrato.link}}`, para os blocos seguintes), na Macro e na Automação;
   bloco `generate_contract` no Formulário público (gera pelas respostas e manda o link). Gatilhos do Flow
   `signature_*` (8 acontecimentos) trazem `{{contrato.*}}` — ver `lionchat_flows_schema_reference`.
 

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

@@ -842,17 +842,35 @@ automática. Ver a seção de variáveis de conta acima.
 2. `reports_list_*` (agent_overview) com `since=7d_ago`, `until=now`
 3. Sintetize: agente X com Y resoluções, tempo médio Z
 
-### "Enviar mensagem com anexo (imagem/arquivo)"
-1. `upload_create` (a partir de arquivo OU de uma URL) → resposta traz `file_url` e `blob_id`
+### "Enviar mensagem com anexo (foto, vídeo, áudio, PDF, documento)"
+1. `upload_create` com `external_url` (link público de DOWNLOAD do arquivo) → resposta traz `file_url` e `blob_id`.
+   Pelo conector o arquivo sempre vai POR LINK — não existe envio direto do computador.
 2. `conversations_messages_create` passando o `blob_id` (signed_id) dentro do array `attachments`:
    ```json
    { "content": "Segue o documento", "message_type": "outgoing", "attachments": ["<blob_id>"] }
    ```
    Cada item de `attachments` é o `blob_id` retornado pelo upload. Pode mandar vários.
 3. O mesmo padrão vale pra anexar mídia num card do Kanban (use o `blob_id` no campo de anexo do card).
-4. **Anexo de MENSAGEM aceita QUALQUER tipo de arquivo (novo 15/08)** — só o TAMANHO reprova. Se
-   houver dúvida sobre um arquivo grande, confira antes com `lionchat_upload_limits_show` (segue
-   sendo a fonte dos tetos).
+4. **Tipos aceitos por link (23/10/2026):** foto, vídeo, áudio e documentos (PDF, Word, Excel, CSV, ZIP...). Até
+   23/10 o link só aceitava foto e vídeo — se uma resposta antiga sua disse que PDF não dava, isso mudou. Áudio e
+   documento respeitam o teto por tipo (`lionchat_upload_limits_show`).
+5. **Link que abre uma PÁGINA é recusado** ("O link abre uma página, não o arquivo"): é o caso do link de
+   visualização do Google Drive (`.../file/d/<ID>/view`). Use o download direto
+   `https://drive.google.com/uc?export=download&id=<ID>` — e o arquivo precisa estar com acesso "qualquer pessoa com o
+   link". Na dúvida, confira antes com `lionchat_upload_validate` (`valid=true` = vai funcionar).
+6. Funciona igual na conversa de um **grupo** do WhatsApp (caixa QR Code): a mensagem com anexo chega no grupo.
+
+### "Mandar um relatório em PDF todo dia num grupo do WhatsApp"
+1. Leia os números com as ferramentas de relatório (`lionchat_reports_summary`, `lionchat_custom_dashboards_widget_data`,
+   `lionchat_conversations_meta`...) e monte o PDF do seu lado.
+2. Publique o PDF num link de download público (ex.: pasta do Google Drive com acesso "qualquer pessoa com o link" —
+   o link de visualização não serve, veja o item 5 acima).
+3. Ache a conversa do grupo: `lionchat_conversations_list` na caixa WhatsApp QR Code (grupo só existe nela) ou busca
+   pelo nome do grupo.
+4. `upload_create` com o link → `conversations_messages_create` na conversa do grupo com o `blob_id` em `attachments`.
+5. **O conector não agenda nada**: "todo dia" depende de uma tarefa agendada do lado de quem usa o conector. Se texto
+   basta, prefira `lionchat_report_alerts_create` — o próprio servidor manda o resumo diário de um relatório
+   personalizado no grupo, sem depender de ninguém (siga o fluxo seguro da descrição: criar desligado, prévia, ligar).
 
 ## Cuidados com tools de criação
 

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

@@ -298,7 +298,9 @@ Funnel
 ├── account_id (FK)
 ├── name
 ├── stages (jsonb: hash com slug_etapa => { name, color, position, description, checklist_templates })
-├── settings (jsonb: { agents: [], goals: [], automations: [{trigger_type, action, action_config, enabled}] })
+├── settings (jsonb: { agents: [], goals: [], automations: [{trigger_type, action, action_config, enabled}] };
+│     `automations[].action` inclui `create_task` (20/10/2026). `settings.removed_stages` = etapas já excluídas,
+│     mantida só pelo servidor — enviada pela API é ignorada)
 ├── 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,
@@ -346,6 +348,14 @@ KanbanItemSnooze (kanban_item_snoozes — 11/10/2026: ate quando o card esta ADI
 ├── snoozed_by_id (quem adiou; nulo = automacao, macro ou fluxo)
 └── created_at / updated_at
 
+KanbanStageRemoval (kanban_stage_removals — 20/10/2026: a exclusão de etapa EM ANDAMENTO; sem chave estrangeira)
+├── account_id, funnel_id (funil de ORIGEM), stage_key (a etapa excluída)
+├── to_funnel_id, to_stage (destino dos cards; nulos quando a etapa estava vazia e saiu pelo Salvar do funil)
+├── user_id (quem pediu), status (running | done), moved_count
+├── started_at / last_seen_at / finished_at
+└── Um só `running` por etapa: é ele que dá o 409 STAGE_REMOVAL_IN_PROGRESS a quem tenta excluir a mesma etapa
+    ao mesmo tempo. A IA NÃO lê nem grava esta tabela; ela só chama `lionchat_funnels_remove_stage` e repete
+
 Item do checklist (elemento do array jsonb `checklist`)
 ├── id (uuid string)
 ├── text
@@ -504,8 +514,21 @@ AccountTask (agenda interna)
 ├── meeting_url (string, sala de reunião call/meeting)
 ├── guest_emails (jsonb array, convidados extras — máx 20)
 ├── conversation_id / contact_id / linked_kanban_item_id (FK opcionais)
+├── kanban_item_id (FK opcional → KanbanItem, 20/10/2026) — a tarefa PRESA ao card (aparece na aba Tarefas do card).
+│   NÃO confunda com `linked_kanban_item_id` (card apenas relacionado, não dono da tarefa). A API devolve também
+│   `kanban_item_title` (só leitura). Agendamento (Booking), sessão de programa e evento do Google NÃO podem ser
+│   presos a card (422). Apagar o card apaga só a tarefa SIMPLES presa a ele (sem conversa, contato, agendamento, sessão de programa,
+│   anexo, que não veio do Google e não é somente leitura); as outras se soltam e ficam. A tarefa automática de card
+│   COM conversa grava a conversa e por isso sobrevive à exclusão do card (fica na conversa)
+├── occupies_agenda (boolean, padrão true, 20/10/2026) — se a tarefa bloqueia o horário na Agenda; false = lembrete
+│   que não bloqueia (o padrão da regra "Criar tarefa" é false)
+├── automation_event_key (string, só leitura, 20/10/2026) — chave de "uma tarefa por acontecimento" da tarefa
+│   automática (`card:<id>:rule:...` no funil, `flow:<sessão>:<bloco>:<item>:<passagem>` no fluxo); índice único por
+│   conta. Tarefa criada por gente fica com ela nula
 ├── booked_by (polimórfico User/Contact/Captain::Assistant) / booked_by_name / booking_source
 │   (painel|link|ia|sistema|fluxo) — QUEM agendou e por onde (14/09)
+│   Tarefa AUTOMÁTICA (20/10): pela automação do funil, `booked_by` = o Funil e `booking_source` = `sistema`;
+│   pelo bloco "Criar tarefa" de um fluxo, `booked_by` = o Fluxo e `booking_source` = `fluxo`
 ├── attendance (enum attended=0 / no_show=1, NULO = nada registrado — CARIMBO, não muda status)
 │   / attendance_by (polimórfico) / attendance_source — quem marcou Compareceu/Faltou (14/09)
 ├── selo (SÓ LEITURA, calculado — 17/09): o rótulo ÚNICO que a tela mostra ao lado da tarefa, juntando
@@ -729,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`:**