@lionchat/mcp-server 1.19.2 → 1.21.0

package/dist/docs/instructions.md

@@ -19,9 +19,11 @@ Comprovado em produção (24/07): a sessão que dizia "não há função de list
   kanban_items, funnels, flows, flow_tools, campaigns, macros, automation_rules, agents, teams,
   inboxes, labels, canned_responses, reports, sla, csat, captain_assistants, captain_documents,
   scheduled_messages, custom_attributes, webhooks, eclinica_integrations, tasks, notifications,
-  lead_forms (Formulários públicos de captação).
-- **Fora do MCP por decisão do dono (19/08): assinatura, plano, fatura, forma de pagamento, cartão,
-  saldo e recarga.** Não existem ferramentas dessas áreas e não devem ser criadas. Se o usuário
+  lead_forms (Formulários públicos de captação), signature_documents / signature_envelopes
+  (assinatura ELETRÔNICA de contratos — modelos e contratos enviados).
+- **Fora do MCP por decisão do dono (19/08): assinatura DO PLANO (cobrança), plano, fatura, forma de
+  pagamento, cartão, saldo e recarga.** (A assinatura ELETRÔNICA de contratos é outra coisa e TEM
+  ferramentas: `lionchat_signature_*`.) Não existem ferramentas dessas áreas e não devem ser criadas. Se o usuário
   pedir, diga que isso se resolve no painel, na área de assinatura da conta — não tente por
   ferramenta nem por chamada direta.
 - Só depois de pesquisar e não encontrar é que se pode dizer que a função não existe.
@@ -223,6 +225,17 @@ lionchat_conversations_messages_list (conversation_id: 123)
 3. lionchat_inboxes_public_conversations_create (vincula contato à inbox)
 ```
 
+**Telefone com ou sem o nono dígito (desde 05/09/2026):** a busca do passo 1 acha o contato
+mesmo que ele esteja salvo na OUTRA forma do celular brasileiro (com o 9 quando você busca sem, e
+vice-versa). Não precisa buscar duas vezes. Se mesmo assim `lionchat_contacts_create` devolver 422
+com `attributes: ["phone_number"]`, o contato já existe — busque de novo e ATUALIZE em vez de criar.
+Nunca tente "resolver" trocando a forma do número no create: a criação recusa as duas formas de
+propósito (a recusa protege contra ficha em dobro).
+**Atenção:** como a busca e o `contacts_filter` agora enxergam as duas formas, uma pessoa que tenha
+ficha duplicada pode voltar como **2 resultados**. Nunca pegue o primeiro às cegas para
+`contacts_update` — confira nome/e-mail ou pergunte ao usuário qual é a ficha certa. A lupa geral
+(`lionchat_search_list`) NÃO tem essa tolerância: para telefone, use `lionchat_contacts_search`.
+
 ### Criar funil (kanban) novo com etapas
 
 **FUNIL = KANBAN = pipeline = board — são a MESMA coisa no LionChat.** Quando o usuário pedir "cria um kanban", "monta um pipeline" ou "cria um funil", a ferramenta é `lionchat_funnels_create` (não existe endpoint separado de "criar kanban").
@@ -372,13 +385,14 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 |---|---|---|
 | 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) |
 | 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 / 14 s). É a substituta certa do `lionchat_conversations_search` |
+| 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` |
 | Não sei se o termo é nome de alguém ou algo dito no papo | `lionchat_search_search` (`/search`) | Cobre os dois numa chamada. Opção mais segura quando a intenção é ambígua |
 | (qualquer busca) termo com menos de 3 caracteres | — | Volta **vazio de propósito** em todas as buscas. Vazio ≠ "não existe": quer dizer que a busca não rodou. Refaça com 3+ caracteres. Só-dígitos é isento nas rotas `/search/*`, mas **não** no `lionchat_conversations_search` legado |
 | Só a contagem / números | `lionchat_conversations_meta` / `lionchat_reports_summary` | Não liste o conteúdo completo |
 | 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) |
 | **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 |

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

@@ -0,0 +1,75 @@
+# Assinatura eletrônica de contratos
+
+**Não confundir com "assinatura" de PLANO/cobrança** (fatura, cartão, saldo) — essa área fica fora do MCP.
+Aqui é a **assinatura eletrônica de documentos**: o cliente assina um contrato pelo WhatsApp (ou e-mail),
+com código de uso único, e o LionChat guarda a prova (IP, aparelho, localização, hash, PDF selado).
+Feature `document_signing` (ligada por conta; 403 `feature_disabled` quando desligada).
+
+## As três camadas
+
+| 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` |
+| **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 |
+| `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 |
+| `falta_eu` | — | contratos abertos em que o usuário do token é o remetente e ainda não assinou |
+
+Participante: `pending` → `viewed` → `verified` (confirmou o código) → `signed` | `refused`.
+
+## 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` ·
+`sealed` (documento final gerado, `sealed_sha256`) · `refused` · `cancelled` · `expired` · `delivery_failed`
+(motivo em `delivery.failed[]`) · `reminded` · `resent`. Tudo append-only — é o relatório de evidências.
+
+## 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`).
+2. Confira a ficha: toda `{{variável}}` do modelo precisa ter valor no contato (nome, CPF, endereço…) —
+   senão o envio volta `422 variaveis_sem_valor` com a lista do que falta.
+3. `lionchat_signature_envelopes_create` com `signature_document_id`, `contact_id` e `participants`
+   (`[{name, role: 'signer', phone, delivery_channel: 'whatsapp', contact_id}]`; testemunha = mais um item
+   com `role: 'witness'` e o telefone dela).
+4. `422 escolher_caixa` → a pessoa conversa em mais de uma caixa de WhatsApp: repita com `inbox_id`.
+5. Acompanhe com `signature_envelopes_show` (linha do tempo) ou `signature_envelopes_list`
+   (`contact_id`, `status`, `q`). Não chegou? `resend`. Errou? `cancel` (admin). Falta a SUA assinatura
+   (modelo com "eu também assino")? `signature_envelopes_sign_as_sender` — ver regra abaixo.
+
+## Regras que valem sempre
+- **Quem pode**: administrador ou cargo personalizado com "Gerenciar Assinaturas" (`signature_manage`) — vale para
+  criar/editar modelo, prévia, enviar, reenviar, baixar e "eu também assino" (403 sem a chave). A LISTA de modelos e a
+  leitura de um modelo continuam abertas a qualquer membro. Cancelar contrato e apagar modelo: só administrador.
+- **Trava sagrada**: campo do modelo sem valor na ficha bloqueia o envio. Preencher a ficha primeiro.
+- **Validade** (`roles_layout.validity_days`, padrão 7) conta do ENVIO; `{{document.deadline}}` imprime a data no
+  texto; passou = `expired` (cron de hora em hora). **Lembrete** (`reminder_days`, padrão 2, 0 = off): quem não
+  assinou recebe o link de novo a cada N dias.
+- **Conversor de Word** é um serviço separado (docx-converter). Fora do ar = `422 conversor_indisponivel` na prévia e no envio de modelo Word — é o serviço, não o arquivo; repetir em instantes. Modelos `text` e `file` não passam por ele.
+- **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.
+- **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.
+- **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.
+- **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
+  ú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;
+  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`.
+
+## Onde o cliente vê
+Menu **Assinaturas** (modelos e contratos, filtros, "Falta você assinar"), aba **Contratos** na ficha do contato,
+pílulas na conversa a cada acontecimento e avisos no sininho para quem enviou.

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

@@ -160,11 +160,11 @@ Travas que valem conhecer (não dá pra desligar):
 ## Limite do prompt e cache OpenAI (2026-05-22)
 
 - `config.instructions` (system prompt do agente) aceita até **20.000 caracteres** (antes 10k). Acima de 15k, o frontend mostra aviso "lost in the middle" — prefira colocar instruções críticas no início ou final.
-- **Cache automático** ativo em todos os 16 modelos oferecidos na plataforma. Desconto 50-75% no input cachado, sem configuração. Reuso do prompt do agente em múltiplas conversas maximiza a economia.
+- **Cache automático** ativo em todos os 19 modelos oferecidos na plataforma. Desconto 50-75% no input cachado, sem configuração. Reuso do prompt do agente em múltiplas conversas maximiza a economia.
 
 ### Lista real de modelos (`config.model`)
 
-Estes são os 16 valores que o seletor de modelo do painel oferece (`ModelSelector.vue`). Só recomende
+Estes são os 19 valores que o seletor de modelo do painel oferece (`ModelSelector.vue`). Só recomende
 valores desta lista:
 
 | Faixa | Modelos |
@@ -172,18 +172,21 @@ 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`, `o1`, `o3` |
+| Premium | `gpt-5`, `gpt-5.2`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`, `o1`, `o3` |
 
 **`GPT-5.2 Pro` não existe.** O valor válido é `gpt-5.2`, sem "Pro".
 
-> **PERIGO — família `gpt-5.6` (`gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`): REMOVIDA em 29/07/2026.**
-> Esses modelos **recusam function tools** em `/v1/chat/completions` (erro 400 real: "Function tools with
-> reasoning_effort are not supported"). Como o AI Agente usa ferramentas em **toda** resposta, 100% das
-> chamadas falhavam e a IA ficava **MUDA** — sem erro na tela, sem resposta. Ficou 2 semanas invisível.
-> **Nunca sugira, nunca grave** um `gpt-5.6` — nem se o cliente pedir "o mais novo/mais forte".
+> **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
+> modelo muda de canal). Podem ser gravados em `config.model` do assistente, no Copilot e no bloco de IA do
+> Flow. **Recusam temperatura personalizada: `config.temperature` é ignorada** (só o padrão). O `sol` custa
+> ~5x o `luna` — recomende o `luna` salvo pedido explícito. **NUNCA no bloco de IA do Formulário de Lead**
+> (teto de 15 s; o servidor exclui e cai no fallback).
 >
-> O campo `config.model` **não tem lista branca no servidor**: ele é `store_accessor` do `config` e
-> aceita qualquer texto sem validar. Modelo inválido salva com 200 e só quebra na hora de responder.
+> Desde 09/2026 o campo `config.model` **tem lista branca no servidor** (`LlmConstants::SELECTABLE_MODELS`):
+> trocar para um modelo fora da lista devolve **422** (`model is not included in the list`). Registro
+> antigo com modelo fora da lista continua salvando os outros campos; só a troca é recusada.
 > 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".
 
@@ -387,6 +390,40 @@ integração conectada na conta (senão é pulado em silêncio — confira as li
 (o que iniciou o fluxo ou o mais recente da conversa); sem card, o registro NÃO aparece nas telas de
 eventos do Funil (só no histórico do fluxo). Formato completo no `flowbuilder-design-guide`.
 
+### Meta CAPI — lead que chegou por ANÚNCIO DE WHATSAPP (2026-09-10)
+
+Quem chegou pelo botão de WhatsApp de um anúncio (a conversa carrega `ctwa_clid` e a caixa é a
+oficial, com WABA) sai pra Meta como evento de MENSAGEM (`action_source: business_messaging`) — e a
+Meta só aceita isso num **dataset vinculado à WABA**, nunca no pixel do site (recusa 2804132). Até
+10/09 100% desses eventos caíam no plano B (saíam como site) sem ninguém ver. Regras pro MCP:
+
+- **Vincular a caixa primeiro:** `lionchat_inboxes_capi_dataset_link` (POST `/inboxes/{id}/capi_dataset`).
+  Idempotente, vale para todos os números da mesma WABA, usa a chave da PRÓPRIA caixa (a do pixel não
+  serve). O id fica em `provider_config.capi_dataset_id` (visível em `lionchat_inboxes_show` para admin).
+  Sem o vínculo os eventos de anúncio saem como site com `fallback_reason: lionchat:dataset_nao_configurado`.
+- **Nome do evento em mensagem = SÓ 14:** `LeadSubmitted`, `QualifiedLead`, `ViewContent`, `AddToCart`, `InitiateCheckout`, `Purchase`, `OrderCreated`, `OrderShipped`, `OrderDelivered`, `OrderCanceled`, `OrderReturned`, `CartAbandoned`, `RatingProvided`, `ReviewProvided`.
+  O evento de SITE continua com o nome que o cliente quiser. A escolha de WhatsApp mora em
+  `messaging_name` (etapa e `won` do `meta_events_config`, tool `lionchat_funnels_meta_events_config`),
+  em `messaging_event_names.meta` (bloco `send_conversion` do fluxo) e em `messaging_event_name`
+  (disparo manual `lionchat_kanban_items_meta_capi_fire`). Tri-estado: chave AUSENTE = automático
+  (Lead/Contact → LeadSubmitted, Purchase → Purchase, InitiateCheckout → InitiateCheckout; sem sugestão
+  o lead de anúncio sai como site com motivo), `''` = não enviar como WhatsApp, um dos 14 = escolha.
+  Nome fora dos 14 é descartado no funil e dá 422 no disparo manual. `lost` (Perdido) é sempre site —
+  não existe evento de "perdido" em mensagens. O nome interno do cliente vai em `custom_data.internal_event`.
+- **Diagnóstico "por que a venda não contou como conversão de WhatsApp?":**
+  `lionchat_funnels_meta_capi_events_list` com `degraded=true` e ler `fallback_reason` + `action_source`.
+  Motivos nossos: `lionchat:dataset_nao_configurado` (falta o vínculo), `lionchat:caixa_token_recusado`
+  (a Meta recusou a chave da caixa — reconectar a caixa), `lionchat:caixa_nao_encontrada`,
+  `lionchat:caixa_sem_token`, `lionchat:dataset_id_invalido`, `lionchat:desligado_pelo_cliente`,
+  `lionchat:nome_sem_equivalente_whatsapp`; da Meta: `"<subcode>: <mensagem>"` (ex.: 2804087 = clique
+  do anúncio inválido/expirado).
+- Recusa ao vincular (422 com `subcode`, ex.: 2804116 / "whatsapp_business_manage_events"): a chave da
+  caixa não tem a permissão — reconectar a caixa pelo Cadastro Incorporado da Meta; nunca pedir o token
+  do pixel para isso. Um 401/403 da caixa NUNCA desliga o pixel da conta (site, formulário e agenda
+  continuam) — o evento de anúncio apenas sai como site com o motivo.
+- NUNCA prometer que eventos antigos voltam: o plano B marca como enviado (não há retry) e a Meta só
+  aceita evento com até 7 dias.
+
 ### Meta Lead — token de anúncios de OUTRO app (2026-09-01)
 
 `lionchat_meta_lead_validate_token` pode voltar `app_verified: false` com `expires_at` nulo: é token
@@ -690,7 +727,7 @@ automática. Ver a seção de variáveis de conta acima.
 
 - **Tipo de atributo `time` (Hora 24h):** ao criar custom attribute com `attribute_display_type: "time"` (ou o numérico `9`), o valor canônico é `"HH:MM"` 24h e o fuso mora na definição (`attribute_timezone`, IANA, default `America/Sao_Paulo`). Uso principal: alimentar o campo Horário do node `wait` (modo date, `waitTimeMode: "variable"`).
 - **Tipo de atributo `datetime` (Data e Hora, novo 2026-07-18):** `attribute_display_type: "datetime"` (ou numérico `10`), com `attribute_timezone` (default `America/Sao_Paulo`). Guarda data+hora juntas em ISO com offset (`"2026-07-18T14:55:00-03:00"`); exibe `"DD/MM/AAAA - HH:MM"`. Um porteiro no backend aceita e converte vários formatos de entrada (ISO/UTC/BR/AM-PM/unix). **ATENÇÃO ao montar flows:** o tipo `datetime` NÃO é selecionável no Gatilho de Data nem nos campos Data/Horário do node `wait` — esses continuam exigindo `date`(5) pra data e `time`(9) pra hora, SEPARADOS. O `datetime` é, por ora, tipo de armazenamento/exibição (sidebar + mensagens humanas), não fonte de entrada de fluxo. Em condição, atributo `datetime` é tratado como string (compara o ISO cru).
-- **Timeout de flow `ai_tool` com node `api`:** sobe sozinho de 20s pro teto de 45s quando ainda está no padrão — não precisa configurar nada; só evite setar `execution_timeout_ms` custom se quiser manter o auto-ajuste.
+- **Timeout de flow `ai_tool` com node `api`:** sobe sozinho de 20s pro teto de 45s quando ainda está no padrão e, desde 10/09/2026, DESCE de volta pro teto quando o último node `api` é apagado (antes o valor gravado ficava acima do teto e o flow não salvava mais — o 422 vinha como "configuração incompleta" sem nenhum bloco vermelho). Não precisa configurar nada; só evite setar `execution_timeout_ms` custom se quiser manter o auto-ajuste. Valor acima do teto enviado por API/MCP continua recusado.
 - **Teste do node `api`:** o resultado do último teste fica salvo no servidor (pin, TTL 30 dias) — sobrevive a trocar de navegador/máquina. Isso é recurso do editor humano; não há tool MCP pra isso.
 
 ## Status codes a respeitar

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

@@ -704,6 +704,7 @@ Todos os formatos abaixo foram conferidos linha a linha em `app/services/action_
 | `assign_agent` | `[70]` — o agente precisa ser membro da caixa. `["nil"]` desatribui |
 | `assign_team` | `[3]`. `["nil"]` desatribui |
 | `assign_captain_assistant` | `[17]` ou `[{"assistant_id": 17, "proactive": true}]` — `proactive` false = a IA assume mas nao fala na hora |
+| `deactivate_captain` | `[]` — desliga o AI Agente da conversa (novo 10/09/2026; a macro também tem) |
 | `send_email_to_team` | `[{"team_ids": [1], "message": "texto"}]` |
 | `send_webhook_event` | `["https://..."]` |
 | `send_attachment` | `[blob_ids]` — so funciona se a regra ja tiver arquivo anexado; nao da pra montar so por API |
@@ -713,7 +714,7 @@ Todos os formatos abaixo foram conferidos linha a linha em `app/services/action_
 | `mute_conversation` | `[]` |
 | `snooze_conversation` | `[]` |
 | `resolve_conversation` / `open_conversation` / `pending_conversation` | `[]` |
-| `update_contact_attribute` / `update_conversation_attribute` | `[{"attribute_key": "chave", "value": "texto ou {{contact.phone_number}}"}]` |
+| `update_contact_attribute` / `update_conversation_attribute` | `[{"attribute_key": "chave", "value": "texto ou {{contact.phone_number}}"}]` — chave PROTEGIDA é recusada na execução e fica só no log (10/09/2026): prefixos `waha_whatsapp_`, `whatsapp_`, `origin_`, `ctwa_`, `meta_lead_`, `lt_` e atributos de sistema como `utm_*`/`gclid`. Vale pra macro e automação |
 | `create_kanban_item` | `[{"funnel_id": 31, "funnel_stage": "prospeccao", "allow_duplicates": false}]` |
 | `move_kanban_item_to_stage` | `[{"funnel_id": 31, "funnel_stage": "qualificacao"}]` |
 | `assign_agent_to_kanban_item` | `[{"funnel_id": 31, "agent_id": 70, "mode": "add"}]` — `mode` aceita `add` (padrao) ou `remove_all` |

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

@@ -196,12 +196,23 @@ Funnel
 ├── 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)
-├── meta_events_config (jsonb: won/lost/stages → Meta Pixel/CAPI events)
+├── 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;
+│     só em stages e won, nunca em lost)
 ├── archived (bool)
 ├── active (bool)
 ├── position (int, ordem entre funis)
 └── created_at
 
+MetaCapiEvent (meta_capi_events — cada envio de conversão pro Meta)
+├── event_name (nome INTERNO, o que o cliente escolheu), event_id (idempotência), status (pending/sent/failed/duplicate)
+├── trigger_type, kanban_item_id, contact_id, conversation_id, funnel_id, meta_pixel_integration_id
+├── inbox_id (2026-09-10: a caixa oficial de onde saiu a WABA — o envio de anúncio de WhatsApp usa o dataset e a chave DESSA caixa)
+├── fallback_reason (2026-09-10: preenchido quando um evento de anúncio de WhatsApp saiu como SITE — plano B; NULL = não degradou)
+├── payload_sent (jsonb: data[0].action_source = website | business_messaging; data[0].event_name = o nome que FOI pra Meta)
+└── response_body (jsonb: resposta da Meta; `fallback_from` = a recusa original quando houve plano B)
+
 KanbanItem
 ├── id (PK)
 ├── account_id (FK)
@@ -341,6 +352,17 @@ Macro
 └── visibility (personal/global)
 ```
 
+**Macro — ações e freios (10/09/2026).** `actions` aceita 40 nomes: todos os das automações (mesmos
+`action_params`, ver a tabela em conversation-flows.md) mais os que só a macro tem — `mark_unread` (`[]`),
+`add_contact_label`/`remove_contact_label` (`[titulos]`, etiqueta do CONTATO), `distribute_agents`
+(`[agent_ids]`, rodízio de verdade), `update_card_attribute` (`[{funnel_id, attribute_key, value}]`),
+`add_card_checklist` (`[{funnel_id, checklist_template_ids}]`), `add_card_offer` (`[{funnel_id, offer_ids}]`)
+e `send_conversion` (`[{destinations, event_names, value}]` — só administrador ou cargo com
+`marketing_integrations_manage` consegue SALVAR a macro; executar segue livre; teto de 50 conversões por
+execução). Atributo protegido em `update_*_attribute` é recusado na execução (só no log). Executar
+(`lionchat_macros_execute`): até 100 conversas por chamada, a mesma conversa em 5 s é pulada em silêncio,
+30 execuções por minuto por usuário (429). A mensagem de `send_canned_response` sai assinada por quem executou.
+
 ## Agenda / Tarefas / Booking
 
 ```
@@ -436,6 +458,11 @@ daquele tipo no calendário; vazio = cor do agente. A tarefa devolve `booking_co
 `cliente_alteracao_pagamento`, `odontograma_finalizado`, `inclusao_procedimento`
 (capturados ao vivo, não documentados pelo e-Clínica).
 
+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
+relatório e as tools da e-Clínica valem assim que a integração existe. Contas que já tinham integração
+receberam o recurso no deploy (migração).
+
 Os 3 últimos são do perfil ODONTOLÓGICO: `agendamento_aguardando` = a recepção marcou a
 chegada do paciente na clínica (grava a hora da chegada e `eclinica_status_agendamento = aguardando`);
 `odontograma_aprovado` = plano de tratamento aprovado (grava o cabeçalho do odontograma);
@@ -468,6 +495,8 @@ Atributos de sistema no CONTATO (prefixo `eclinica_`, protegidos, usáveis como
 | `eclinica_data_consulta` | date | Data da consulta, ISO |
 | `eclinica_hora_consulta` | **time** | Hora da consulta 24h `"HH:MM"` (novo 2026-07-06) |
 | `eclinica_hora_final` | **time** | Hora final da consulta (novo 2026-07-27) |
+| `eclinica_link_confirmacao` | **link** | Link ecli.co para o paciente confirmar/cancelar a ÚLTIMA consulta (novo 2026-09-08; só existe quando a unidade aprendeu o padrão na aba Unidades). No LEMBRETE use a variável `{{link_confirmacao}}` do fluxo (ou `{{agendamento.link_confirmacao}}` na automação): é da consulta certa — a ficha aponta para a última, e quem tem duas marcadas receberia o link errado |
+| `eclinica_paciente_nome` | text | Nome do PACIENTE como está no cadastro da e-Clínica (novo 2026-09-09). O nome do contato pode ser o do WhatsApp (mãe que agenda o filho pelo celular dela) — por isso NUNCA use `{{contact.name}}` nas mensagens da clínica. Nos fluxos por evento: `{{ contact.custom_attribute.eclinica_paciente_nome \| default: contact.name \| primeiro_nome }}`; no LEMBRETE use a variável `{{ paciente_nome \| default: contact.name \| primeiro_nome }}` (por consulta) ou `{{agendamento.paciente_nome}}` na automação. `primeiro_nome` = primeira palavra com inicial maiúscula. |
 | `eclinica_status_agendamento` | text | `agendado` / `aguardando` (paciente chegou) / `no_show` / `atendido` / `desmarcado`. Vem do TIPO do evento, nunca da letra da situação. **Estado terminal do MESMO agendamento não volta pra `agendado`** (2026-08-20): a e-Clínica manda `agendamento_alterado` a cada edição da consulta, inclusive depois da chegada/atendimento, e isso NÃO reabre o status. Consulta com `eclinica_idagenda` DIFERENTE nasce `agendado` |
 | `eclinica_situacao` | text | Situação do agendamento no painel, **POR EXTENSO** (2026-08-21, legenda oficial da e-Clínica): AGUARDANDO, NA CADEIRA, PASSAR FINANCEIRO, AGENDAR RETORNO, ATENDIDO, CONFIRMADO, CONFIRMADO PELO LINK, CONFIRMADO PELA API, FALTA, DESMARCADO, CANCELADO PELO LINK, CANCELADO PELA API. Antes guardava a letra crua (`A`, `C`…). Código nunca visto aparece como veio |
 | `eclinica_compromisso` | text | Tipo da consulta — TEXTO LIVRE da recepção (ex: Consulta, Retorno) |
@@ -590,6 +619,11 @@ MetaLeadIntegration (Facebook Lead Ads)
 ├── facebook_page_id (FK polimórfico)
 ├── status (active/token_expired/paused)
 └── meta_lead_forms (has_many)
+    → cada lead vira CONTATO com os atributos meta_lead_* (form_id/form_name, campaign_id/name,
+      adset_id/name, ad_id/name, creative_id/name, platform, account_id/name; definidos por conta como
+      atributo de contato). Filtráveis em contacts_filter como atributo personalizado; desde 10/09/2026
+      também no filtro da tela de contatos e no painel "Atributos de Campanha" da conversa
+      (meta_lead_form_name aparece como "Origem - Formulário")
 
 LeadForm (Formulário público de captação — feature flag lead_forms, por conta)
 ├── account_id (FK)
@@ -724,3 +758,20 @@ Os limites que a API devolve (`resource_limits.*` da conta, `email_usage.limit`,
 duas contas no MESMO plano podem ter limites diferentes — não é defeito. Limite `0` significa
 ILIMITADO em toda a plataforma. A contratação/remoção de adicionais é feita SÓ pela tela de
 Cobrança do painel (não há ferramenta MCP para isso, por decisão do dono).
+
+## Assinatura eletrônica de contratos (04/09)
+
+```
+SignatureDocument (modelo)  1 ──── N  SignatureEnvelope (contrato de UMA pessoa)  1 ──── N  SignatureParticipant
+   name, kind (text|file|word)            title, status, sent_at, expires_at,                name, role (signer|witness|sender),
+   body ({{variáveis}}), tags,             contact_id, conversation_id,                       status, phone/email, delivery_channel,
+   roles_layout {signers, witnesses,       original_sha256, sealed_sha256,                    conversation_id (a conversa DELE),
+   sender_signs, require_id_photo,         created_by (quem mandou)                           public_url, signed_at, viewed_at
+   validity_days, reminder_days}                │
+   progress (contagem por balde)                └── N  SignatureEvent (append-only: kind, occurred_at, ip, user_agent, detail)
+```
+- Contrato aponta pro contato (`contact_id`, nulifica se a ficha for apagada — a prova sobrevive) e pra conversa
+  do titular; cada participante tem a PRÓPRIA conversa (testemunha na dela).
+- `roles_layout` é jsonb aberto e MESCLADO no update; `progress` é calculado (aguardando/visualizado/assinado/encerrado).
+- Feature por conta: `document_signing`. Limite mensal em `usage_limits.signature_requests_per_month` (0 = ilimitado).
+- Detalhe completo: resource `lionchat://docs/assinatura-eletronica`.

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

@@ -79,7 +79,7 @@ Mesmo shape de condição. 15/página.
 |---|---|
 | `id` (id interno do contato) | equal_to, not_equal_to |
 | `name`, `email`, `identifier`, `city`, `company`, `profession` | equal_to, not_equal_to, contains, does_not_contain |
-| `phone_number` | + starts_with (busca por DDD/prefixo) — **corrigido na atualização de 26/07/2026**; em instalação anterior devolve SEMPRE lista vazia (virava igualdade exata). Vazio com prefixo que existe = instalação antiga |
+| `phone_number` | + starts_with (busca por DDD/prefixo) — **corrigido na atualização de 26/07/2026**; em instalação anterior devolve SEMPRE lista vazia (virava igualdade exata). Vazio com prefixo que existe = instalação antiga. **`equal_to`/`not_equal_to` casam as DUAS formas do celular BR (com e sem o 9º dígito) desde 05/09/2026** — mande `+5541999887766` ou `+554199887766`, os dois acham a mesma ficha; `not_equal_to` exclui as duas. Termo que não é celular BR completo (fixo, estrangeiro, trecho) segue exato |
 | `cpf`, `cnpj`, `rg` (cadastral) | equal_to, not_equal_to, contains, does_not_contain, is_present, is_not_present |
 | `country_code` | equal_to, not_equal_to |
 | `labels` | equal_to, not_equal_to, is_present, is_not_present |

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

@@ -529,7 +529,7 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 | `add_card_offer` | `{ offer_id, use_custom_value?, custom_value?, funnel_id?, card_source? }` | Adiciona uma OFERTA (produto/serviço) ao card. `offer_id` de `offers_list`. `use_custom_value: true` + `custom_value` grava um valor personalizado na oferta; senão usa o valor cadastrado. O total do card recalcula sozinho (soma das ofertas). Respeita `card_source` (funnel só localiza o card) |
 | `send_webhook` | `{ url, headers?, body? }` | Dispara webhook externo |
 | `start_flow` | `{ flow_id }` | Inicia outro fluxo. **NÃO encerra o fluxo de origem** (desde 31/08): se houver bloco ligado depois dele, o fluxo SEGUE normalmente. Sendo o último do desenho, o fluxo termina ali como sempre. |
-| `send_conversion` (novo 2026-09-01; `event_names` 2026-09-02) | `{ destinations: ['meta'\|'ga4'\|'google_ads'], event_names: { meta?, google_ads?, ga4? }, event_name (reserva), value? }` | Manda o evento de conversão pro Meta (CAPI), Google Ads e/ou GA4 — o mesmo caminho do Funil, de dentro do fluxo. Aba Sistema (só flow `conversation`). Ver bloco próprio abaixo |
+| `send_conversion` (novo 2026-09-01; `event_names` 2026-09-02; `messaging_event_names` 2026-09-10) | `{ destinations: ['meta'\|'ga4'\|'google_ads'], event_names: { meta?, google_ads?, ga4? }, messaging_event_names: { meta? }, event_name (reserva), value? }` | Manda o evento de conversão pro Meta (CAPI), Google Ads e/ou GA4 — o mesmo caminho do Funil, de dentro do fluxo. Aba Sistema (só flow `conversation`). Ver bloco próprio abaixo |
 | `deactivate_flow` ou `disable_flow` | `{}` | Encerra fluxo atual |
 | `update_attribute` | `{ attr_source: 'contact'\|'conversation'\|'card', attr_key, attr_value }` | Seta custom_attribute (ver abaixo) |
 | `assign_captain` (ou `assign_captain_assistant`) | `{ assistant_id }` | Atribui IA Captain |
@@ -542,7 +542,7 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 **`send_conversion` — Enviar conversão (2026-09-01):**
 
 ```json
-{ "key": "send_conversion", "config": { "destinations": ["meta", "google_ads"], "event_names": { "meta": "Lead", "google_ads": "Contact" }, "event_name": "Lead", "value": "1500,50" } }
+{ "key": "send_conversion", "config": { "destinations": ["meta", "google_ads"], "event_names": { "meta": "Lead", "google_ads": "Contact" }, "messaging_event_names": { "meta": "QualifiedLead" }, "event_name": "Lead", "value": "1500,50" } }
 ```
 
 - `destinations`: array com `meta`, `ga4` e/ou `google_ads` — **OBRIGATÓRIO e não vazio** (vazio = a ação
@@ -555,6 +555,15 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
   Chave presente e em branco = aquele destino é PULADO ("sem nome de evento"); chave ausente cai em `event_name`.
   Google Ads só envia evento que tenha ação mapeada na integração; a tela lista Meta (padrão + personalizados
   da conta) e Google Ads (mapeados), GA4 é livre. Grave sempre `event_names` E `event_name` (= primeiro nome).
+- `messaging_event_names` (**desde 2026-09-10**, só a chave `meta`): o evento de **ANÚNCIO DE WHATSAPP**. Quem chegou
+  por anúncio de WhatsApp (clique para o WhatsApp, caixa oficial vinculada à Meta) sai como `business_messaging`, e
+  nesse caso a Meta só aceita 14 nomes: `LeadSubmitted`, `QualifiedLead`, `ViewContent`, `AddToCart`,
+  `InitiateCheckout`, `Purchase`, `OrderCreated`, `OrderShipped`, `OrderDelivered`, `OrderCanceled`, `OrderReturned`,
+  `CartAbandoned`, `RatingProvided`, `ReviewProvided`. Tri-estado: chave **ausente** = automático (sugestão pelo
+  evento de site: Lead/Contact → LeadSubmitted, Purchase → Purchase, InitiateCheckout → InitiateCheckout; sem sugestão
+  o lead de anúncio sai como site com `fallback_reason`); `""` = não enviar como WhatsApp (sai como site); um dos
+  14 = escolha. Nome fora da lista é ignorado (vira automático). Não afeta GA4/Google Ads. O nome interno do
+  cliente (`event_names.meta`) vai em `custom_data.internal_event`.
 - `event_name`: reserva/compatibilidade (fluxos de antes de 02/09), só letras/números/sublinhado (até 40; ex.: `Lead`, `Schedule`,
   `Purchase`); aceita variável `{{ }}`. No **Google Ads** o nome precisa estar mapeado no
   `conversion_action_map` da integração, senão é pulado.
@@ -672,13 +681,15 @@ aiModel nos modos novos (proteção de nós antigos que carregam aiModel de defa
 padrão da conta).
 Exemplo: `{"aiMode":"sentiment","aiAssistantId":"12","aiModel":"gpt-4.1-mini","aiModelExplicit":true}`.
 
-**A whitelist (`FlowBuilder::RawLlmService::SUPPORTED_MODELS`) é uma lista FECHADA de 16 nomes, SEM
+**A whitelist (`FlowBuilder::RawLlmService::SUPPORTED_MODELS`) é uma lista FECHADA de 19 nomes, SEM
 curinga** — não existe "a família gpt-5 inteira":
 `gpt-4o-mini`, `gpt-4o`, `gpt-4.1-nano`, `gpt-4.1-mini`, `gpt-4.1`, `gpt-5-mini`, `gpt-5`,
-`gpt-5.2`, `gpt-5.4-nano`, `gpt-5.4-mini`, `gpt-5.4`, `gpt-5.5`, `o1`, `o3`, `o3-mini`, `o4-mini`.
-A família **`gpt-5.6` (luna/terra/sol) foi REMOVIDA em 2026-07-29**: ela recusa function tools
-(erro 400 na OpenAI), o que deixava o Agente de IA **mudo em 100% das chamadas** — saiu também daqui
-pra não ser oferecida numa tela e faltar na outra. Também não existem `o1-mini`, `gpt-4.5-preview`,
+`gpt-5.2`, `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`.
+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**
+(teto de 15 s — o servidor exclui e usa o fallback). Também não existem `o1-mini`, `gpt-4.5-preview`,
 `gpt-5.2-pro` nem `gpt-5.5-pro` (a OpenAI recusa).
 
 **OBRIGATÓRIO via API — `aiAssistantId`:** os modos `generate`/`intent`/`sentiment`/`extract`
@@ -1020,6 +1031,7 @@ O campo `flow_type` (definido na criação, IMUTÁVEL depois) decide a natureza
 | Campos extra | — | `tool_name` (snake_case, `[a-z][a-z0-9_]`, max 50) + `tool_description` (max 500) OBRIGATÓRIOS |
 | Retorno | manda mensagens | retorna dado estruturado ao LLM via node `end` |
 | Nodes permitidos | todos | `start`, `end`, `api`, `condition`, `set_variable`, `ai`, `note`, `randomizer`, `action`, `send_message` |
+| Aviso de espera (10/09/2026) | — | enquanto a ferramenta roda, o cliente recebe "Só um momento, estou verificando isso pra você...". Cada ferramenta escolhe o seu no node `start`: `data.toolWaitMessageEnabled` (`false` desliga; AUSENTE = ligado — só um `false` de verdade desliga, `""` ou lixo mantém ligado) e `data.toolWaitMessageText` (texto próprio, até 1000 caracteres; vazio = frase padrão). Vive no `flow_data` e viaja no snapshot de versão; ferramenta já existente não muda de comportamento |
 
 Se o cliente pediu "uma ferramenta que a IA usa pra consultar X / calcular Y", é `ai_tool`. Se pediu "quando chega mensagem, faça Z", é `conversation`. Na dúvida, `conversation`.
 
@@ -1128,15 +1140,35 @@ Dois atalhos: `{{trigger}}` devolve o contexto INTEIRO em JSON e `{{trigger.data
 sem os metadados — úteis pra jogar tudo dentro de um node `ai` ou `api`. Bloco (Hash/Array) inteiro
 sai em JSON; valor simples sai cru.
 
-**O que o histórico mostra e NÃO é variável (22/08/2026).** O passo Início do histórico de execução
-passou a exibir, em todo gatilho, o contato (nome, telefone, e-mail), a conversa (número, canal, caixa)
-e os fatos do que disparou: etiqueta, responsável/equipe (ou "removido"), card (título, funil, etapa
-anterior → etapa), política de SLA, grupo, nome do formulário e do marco, anúncio/formulário/campanha
-do Meta Lead (+ as respostas, em bloco próprio), produto/oferta/meio de pagamento do gateway, evento/
-unidade/data/hora/compromisso da e-Clínica, tecla do TopSend, e os dados do agendamento. Esses fatos
-ficam numa área só-de-log (`_trigger_facts`) — **não existem como `{{trigger.*}}`** e não entram em
-`{{trigger.data}}`. Se o cliente precisar de um deles no fluxo, use a variável de origem quando
-existir (`{{booking.*}}`, `{{form_*}}`, `{{contact.*}}`, atributos do contato gravados pela integração).
+**Os fatos do que disparou VIRARAM variáveis (08/09/2026).** Desde 22/08 o passo Início do histórico
+mostra, em todo gatilho, o contato, a conversa e os fatos do que disparou. Desde 08/09 esses fatos
+também RESOLVEM como `{{trigger.<bloco>.<campo>}}` (contexto do gatilho vence o fato na mesma chave).
+Eles continuam FORA de `{{trigger.data}}` e de `{{trigger}}` — fluxo já em produção não muda de conteúdo.
+
+Oferecidos no autocompletar (só quando o bloco Início tem o gatilho que os preenche):
+
+| Gatilhos do Início | Variáveis |
+|---|---|
+| `card_created`, `card_moved`, `card_won`, `card_lost`, `card_attribute_changed` | `{{trigger.kanban.title}}`, `{{trigger.kanban.funnel_name}}`, `{{trigger.kanban.stage_name}}`, `{{trigger.kanban.stage}}` (código da etapa) |
+| `card_moved` | `{{trigger.kanban.previous_stage_name}}`, `{{trigger.kanban.previous_stage}}` |
+| `card_won`, `card_lost` | `{{trigger.kanban.status}}` (`won`/`lost`) |
+| `label_added`, `label_removed` | `{{trigger.label.name}}` |
+| `assignee_changed` | `{{trigger.assignee.name}}` (vazio = responsável removido) |
+| `team_changed` | `{{trigger.team.name}}` (vazio = equipe removida) |
+| `sla_missed` | `{{trigger.sla.policy_name}}`, `{{trigger.sla.type}}` (`frt`/`nrt`/`rt`) |
+| `group_participant_joined`, `group_participant_left` | `{{trigger.group.name}}`, `{{trigger.group.id}}` |
+
+Resolvem mas NÃO aparecem no seletor (produtor único — só o gatilho daquela integração preenche):
+`{{trigger.attribute.name}}`/`current_value` (atributo do contato entrou no valor), `{{trigger.form.name}}`/
+`milestone`, `{{trigger.payment.gateway|event|product|offer|method|status|amount}}`,
+`{{trigger.eclinica.event|unit|date|time|compromisso|idagenda}}`, `{{trigger.lead.form|page|ad|adset|campaign|platform}}`
+(nome do anúncio, não dado de pessoa), `{{trigger.dtmf.key|campaign}}`, `{{trigger.reminder.date|time|compromisso|unit|days_before}}`,
+além de `{{trigger.kanban.id}}`/`funnel_id` (use `{{trigger.kanban_item_id}}`/`{{trigger.funnel_id}}`),
+`{{trigger.assignee.id}}`, `{{trigger.team.id}}`, `{{trigger.kanban.previous_status}}` e
+`{{trigger.group.participants_count}}`. As RESPOSTAS do lead do Meta não viram variável (só aparecem no
+histórico). Sessões anteriores a 22/08 não têm fatos gravados: essas variáveis saem vazias nelas.
+O bloco do card chama-se `kanban` — nunca `card`. Se o cliente precisar de um dado que não está aqui,
+use a variável de origem quando existir (`{{booking.*}}`, `{{form_*}}`, `{{contact.*}}`).
 
 **NÃO duplique o que já tem variável própria.** `{{contact.name}}`, `{{conversation.status}}`,
 `{{inbox.name}}` e os atributos `ctwa_*` continuam existindo e são a forma canônica. O `{{trigger.*}}`

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

@@ -23,7 +23,7 @@ caixa de WhatsApp vinculada e (opcionalmente) dispara um fluxo do FlowBuilder no
   responde 404** — ninguém consegue preencher. As tools de dashboard (listar, criar, editar,
   publicar, ver respostas, simular) **funcionam mesmo assim**. Dá pra montar tudo antes de ligar a
   flag; não adianta divulgar o link antes.
-- **Escrita é só de administrador.** `create`, `update`, `destroy`, `publish`, `duplicate` e
+- **Escrita é de administrador ou de cargo personalizado com "Gerenciar Formulários" (`lead_form_manage`).** `create`, `update`, `destroy`, `publish`, `duplicate` e
   `check_embed` passam por `check_admin_authorization?`; usuário não-admin recebe **401**. Leitura
   (`list`, `show`, `stats`, `responses`) e o **simulador** (`test_run`) são liberados a qualquer
   agente da conta.
@@ -194,6 +194,7 @@ whitelist do `metadata` segue sem ela) — a decisão é do servidor.
 | `end` | `title, description, redirect_url, button_label, image, video_url` | — | sim |
 | `api_request` | `label, method, url, headers, body, timeout` | `success`, `error` | não (mostra bloco de espera) |
 | `ai` | `label, mode, prompt, categories, include_answers, model` | modo `generate`: `success`, `error` / modo `classify`: um `cat_<id>` por categoria + `other` | não (mostra bloco de espera) |
+| `generate_contract` | `label, document_id, send_link` | `success`, `error` | não (mostra bloco de espera) |
 
 **Chave fora da lista não é lida pelo motor** e o editor a **remove no próximo salvamento pela
 tela**. Escrever um campo inventado pela API não gera erro nenhum — ele simplesmente não faz nada e
@@ -318,6 +319,16 @@ respostas já dadas como contexto. `model` é validado contra a lista suportada;
 da conta. A IA usa a **chave da própria conta** — conta sem chave faz o bloco sair pela saída de
 erro.
 
+**`generate_contract`** (04/09 — bloco "Gerar contrato", feature `document_signing`): gera o CONTRATO de
+assinatura eletrônica daquela pessoa a partir de um modelo (`document_id` = id de
+`lionchat_signature_documents_list`) com os dados da FICHA — mapeie as perguntas com `map_to` para os
+campos que o modelo usa (nome, CPF, endereço…); campo sem valor = saída `error` com o motivo
+(`variaveis_sem_valor: contact.cpf`). `send_link` (padrão `true`) manda o link de assinatura no WhatsApp da
+pessoa (conversa da caixa vinculada); `false` deixa o contrato pronto e você manda `{{contrato.<node_id>.link}}`
+pelo bloco `send_message`. Roda DEPOIS do vínculo do contato, como efeito (bloco de espera), dentro dos
+orçamentos do formulário (200 contratos/formulário/dia, 2.000/conta/dia). Consome 1 vaga do limite mensal
+de contratos. Saídas: `success` (contrato criado) e `error`.
+
 ### Variáveis
 
 | Variável | O que traz | Onde vale |
@@ -326,6 +337,7 @@ erro.
 | `{{contact.name}}` `{{contact.phone}}` `{{contact.email}}` | O que a pessoa respondeu (a ficha é reserva) | idem |
 | `{{api.<node_id>.<caminho>}}` | Um pedaço da resposta de uma consulta | idem |
 | `{{ia.<node_id>}}` | O texto que a IA gerou naquele bloco | idem |
+| `{{contrato.<node_id>.link}}` `.titulo` `.prazo` `.id` `.status` | O contrato gerado pelo bloco Gerar contrato (endereço de assinatura, título, data-limite) | mensagem, prompt, valores |
 | `{{var.<nome>}}` | Variável criada pelo bloco Definir variável | idem |
 | `{{conta.<variável>}}` | Variável da conta (cofre) | cabeçalho e CORPO de `api_request` (com segredo); em `set_variable` e no valor das Ações só as NÃO-secretas |
 

package/dist/docs/resources/glossary.md

@@ -497,6 +497,21 @@ Ao disparar uma conversão pro Meta (Conversions API), o valor agora carrega uma
 tanto no disparo individual da conversão quanto na configuração do funil (valor padrão herdado pelos
 cards daquele funil).
 
+## Meta CAPI — evento de anúncio de WhatsApp, dataset da WABA e plano B (2026-09-10)
+
+- **Evento de anúncio de WhatsApp** (`action_source: business_messaging`): conversão de quem chegou
+  pelo botão de WhatsApp de um anúncio (conversa com `ctwa_clid` numa caixa oficial). A Meta só
+  aceita 14 nomes nele (`LeadSubmitted`, `QualifiedLead`, `ViewContent`, `AddToCart`, `InitiateCheckout`, `Purchase`, `OrderCreated`, `OrderShipped`, `OrderDelivered`, `OrderCanceled`, `OrderReturned`, `CartAbandoned`, `RatingProvided`, `ReviewProvided`) e só num dataset vinculado à WABA.
+- **Dataset da WABA** (`provider_config.capi_dataset_id` da caixa oficial): destino desses eventos,
+  criado/recuperado pelo botão "Vincular à Meta" (`lionchat_inboxes_capi_dataset_link`) com a chave da
+  própria caixa. Um por conta do WhatsApp Business; vale para todos os números dela.
+- **`messaging_name` / `messaging_event_names.meta` / `messaging_event_name`**: a escolha do evento de
+  WhatsApp (funil / fluxo / disparo manual). Tri-estado: ausente = automático, `''` = não enviar como
+  WhatsApp, um dos 14 = escolha.
+- **Plano B** (`fallback_reason` no `meta_capi_events`): o evento de anúncio saiu como SITE. O motivo
+  fica gravado (`lionchat:*` nosso ou `"<subcode>: <mensagem>"` da Meta); na tela é o selo âmbar
+  "site (plano B)" e o filtro "Só plano B" (`degraded=true` na API).
+
 ## Idiomas da plataforma (2026-06)
 
 A plataforma opera com 6 idiomas: `en`, `es`, `fr`, `it`, `pt`, `pt_BR` (default das contas
@@ -566,7 +581,7 @@ com data futura ou `has_imported_history` fecharia a janela de 24h daquela conve
 |---|---|---|
 | `medium` | caixa (`inboxes_list`/`_show`) | sub-tipo do canal. Numa caixa de Página do Facebook diz se ela é Messenger ou **só Instagram** — é o que separa os dois |
 | `content` | mensagem | já vem no formato de exibição (mensagem apagada mostra o aviso, não o texto cru) |
-| `last_incoming_message_at` | conversa | data da última mensagem VIVA do cliente (unix). Use para saber se a janela de 24h está aberta — não confie na data da conversa, que pode vir de histórico importado |
+| `last_incoming_message_at` | conversa | data da última mensagem VIVA do cliente (unix). Use para saber se a janela de 24h está aberta — não confie na data da conversa, que pode vir de histórico importado. Mensagem que a Meta entregou ATRASADA (reentrega depois de uma queda) conta pela hora de ENVIO da Meta, não pela chegada (08/09): o campo, `can_reply` e a tela seguem a mesma régua que a Meta usa pra recusar |
 
 ## Formulário público: código para incorporar no site (02/09/2026)
 
@@ -584,3 +599,22 @@ A gravação permanente só nasce cerca de 24h depois da ligação. O card agora
 conversa). Quem atendeu voltou a aparecer nas recebidas. Se o cliente diz que o botão de ouvir não
 funciona numa ligação de hoje, o mais provável é que o arquivo permanente ainda não exista — a
 reconferência resolve sozinha dentro de 36h.
+
+## Assinatura eletrônica de contratos (04/09)
+
+### `status` do contrato (`signature_envelopes`)
+| Valor | Balde de filtro | Significado |
+|---|---|---|
+| `draft` | aguardando | criado sem nenhuma entrega (falhou) — use `resend` |
+| `sent` | aguardando | link entregue, ninguém abriu ainda |
+| `viewed` | visualizado | alguém abriu o link |
+| `partially_signed` | visualizado | parte das pessoas assinou |
+| `signed_pending_seal` | assinado | todos assinaram; o documento final está sendo gerado |
+| `signed` | assinado | documento final pronto (`sealed_sha256`) |
+| `refused` / `cancelled` / `expired` | encerrado | recusado / cancelado pela equipe / prazo venceu |
+
+### `role` do participante: `signer` (titular), `witness` (testemunha), `sender` (remetente — assina no painel).
+### `status` do participante: `pending` → `viewed` → `verified` → `signed` | `refused`.
+### Erros do envio (`signature_envelopes_create`): `variaveis_sem_valor` (+ `missing[]`), `escolher_caixa` (+ `inboxes[]`),
+`entrega_falhou`, `sem_caixa_whatsapp`, `telefone_invalido`, `limite_do_mes`, `cpf_invalido`, `funcionalidade_desligada`,
+`fila_cheia` (fila única de conversão do Word cheia — repetir em instantes), `conversor_indisponivel` (o serviço de conversão de Word não respondeu — repetir em instantes).