@lionchat/mcp-server 1.23.0 → 1.25.0

package/dist/docs/instructions.md

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

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

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

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

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

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

@@ -172,10 +172,13 @@ valores desta lista:
 | Econômicos / rápidos | `gpt-4.1-nano`, `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-5.4-nano`, `gpt-5.4-mini` |
 | Intermediários | `gpt-4o`, `gpt-4.1`, `gpt-5-mini`, `gpt-5.4` |
 | Raciocínio | `o3-mini`, `o4-mini` |
-| Premium | `gpt-5`, `gpt-5.2`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`, `o1`, `o3` |
+| Premium | `gpt-5`, `gpt-5.2`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-6-sol`, `o1`, `o3` |
+| Custo-benefício (nova geração) | `gpt-6-luna` — US$ 0,10/0,50 por 1M tokens, raciocínio, sem temperatura; liberado em 23/09/2026 |
 
 **`GPT-5.2 Pro` não existe.** O valor válido é `gpt-5.2`, sem "Pro".
 
+> **Família `gpt-6` (`gpt-6-luna`, `gpt-6-sol`) — LIBERADA em 23/09/2026**, pelo mesmo trilho do `gpt-5.6`: sem temperatura e fora do bloco de IA do Formulário de Lead. `gpt-6-astra` NÃO está disponível.
+>
 > **Família `gpt-5.6` (`gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`) — LIBERADA em 09/2026.**
 > Foi removida em 29/07/2026 porque recusa function tools no canal antigo da OpenAI e deixava a IA MUDA.
 > Desde 09/2026 o servidor fala com esses três pela porta `/v1/responses` (só para eles — nenhum outro
@@ -190,6 +193,47 @@ valores desta lista:
 > Desde 29/07 o erro vira uma **nota privada em português** na conversa (`llm_request_rejected`) — é o
 > primeiro lugar a olhar quando "a IA parou de responder logo depois de mexerem nas configurações".
 
+## Ligação por IA — Agentes de ligação (2026-09-24)
+
+A ligação por voz **saiu do agente de texto**. Desde 24/09 ela mora em **Agentes de ligação**, uma área
+própria: cada agente de ligação tem um objetivo e **não ocupa vaga de IA do plano**. As chaves antigas
+`config.call_*` do `captain_assistants_update` **não existem mais** — mandar elas não tem efeito.
+
+| Ferramenta | Para quê |
+|---|---|
+| `captain_call_agents_list` | lista os agentes de ligação e `meta.dial_inboxes` (caixas que podem ligar) |
+| `captain_call_agents_create` / `_update` / `_duplicate` / `_destroy` | cadastro |
+| `captain_call_test_phones_list` / `_create` / `_destroy` | números autorizados a receber ligação de teste |
+| `captain_call_agents_test_call` | **liga de verdade** para um número de teste cadastrado |
+| `captain_call_agents_test_call_status` | tocando / atendeu / não atendeu, e em qual conversa ficou |
+
+Campos do agente de ligação: `name`, `objective` (roteiro, até 4000), `first_message` (até 400), `style`
+(jeito de falar, até 1200), `voice_provider` (`openai` padrão ou `elevenlabs`), `engine` (`gptlive` padrão
+ou `realtime`, só na OpenAI), `voice_id`, `elevenlabs_agent_id` (obrigatório na ElevenLabs),
+`max_duration_seconds` (30 a 600, padrão 180) e **`captain_assistant_id`**.
+
+**Como a ligação trabalha (GPT-Live).** A voz conversa e **só consulta** agenda (horários livres, agenda do
+atendente, quem está trabalhando). Quando o cliente pede algo que precisa ser FEITO — mandar link,
+endereço ou proposta pelo WhatsApp, mover o card, anotar — a voz **repassa** ao agente de texto de
+`captain_assistant_id`, diz "já pedi, vai chegar no seu WhatsApp" e **segue a conversa** (nunca diz "já
+mandei"). O agente de texto executa na conversa daquele contato, com as ferramentas e a configuração
+DELE, e decide se escreve ao cliente. Regras fixas desse pedido: roda mesmo com atendente humano na
+conversa ou com a IA pausada; não liga a IA na conversa nem mexe na IA que já estava lá; não passa para
+humano, não encerra, não transfere e não agenda retorno (fluxos rodam completos); no máximo 3 pedidos
+por ligação; caixa oficial fora da janela de 24h faz as ações mas não escreve.
+Sem `captain_assistant_id` (ou no motor `realtime`/ElevenLabs), a voz **só conversa**.
+
+**Voz.** É **própria** do agente de ligação — não mexe na voz do áudio da IA no WhatsApp
+(`config.voice_provider`/`config.voice_id` do agente de texto continuam sendo só do WhatsApp). No GPT-Live
+use `captain_voices_list` com `engine=gptlive`: aceita alloy, ash, ballad, coral, echo, sage, shimmer, verse,
+**marin** e **cedar** (as duas mais naturais de telefone); voz fora disso cai na marin.
+
+**Ligação de teste.** Só para número **cadastrado** em `captain_call_test_phones` (o telefone nunca vai no
+corpo, só o id). Cria contato e conversa de verdade, pode disparar automações de "conversa criada" e fica
+gravada. Limite de 10 por hora na conta. Precisa da Ligação com IA liberada na conta e da linha da caixa
+conectada; recusa volta 422 com o motivo em `message`. Depois que a ligação termina, a transcrição do
+próprio fornecedor aparece no card da ligação.
+
 ## Follow-up automático multi-etapa (2026-06)
 
 O follow-up do AI Agente agora suporta **cadência de até 3 etapas** via `config.follow_up_steps`:
@@ -341,7 +385,7 @@ Como a coleta de dados/cenários funciona hoje (importante pra diagnosticar "IA
 
 As instruções aceitam variáveis Liquid `{{ }}` que chegam JÁ PREENCHIDAS com os dados reais do contato/conversa do atendimento — vale pra instrução base do assistente (`config.instructions`) e pra instrução de cada cenário (`scenario.instruction`). O texto é gravado como está (sem sanitização); cap de 20.000 chars na base.
 
-- Contato: `{{contact.name}}`, `{{contact.first_name}}`, `{{contact.last_name}}`, `{{contact.email}}`, `{{contact.phone}}`, `{{contact.cpf}}`, `{{contact.cnpj}}`, `{{contact.rg}}`, `{{contact.date_of_birth}}`, `{{contact.profession}}`, `{{contact.address.city}}` (e `.cep`/`.street`/`.number`/`.neighborhood`/`.state`...), `{{contact.custom_attribute.<chave>}}`.
+- Contato: `{{contact.name}}`, `{{contact.first_name}}`, `{{contact.last_name}}`, `{{contact.email}}`, `{{contact.phone}}`, `{{contact.cpf}}`, `{{contact.cnpj}}`, `{{contact.rg}}`, `{{contact.date_of_birth}}`, `{{contact.profession}}`, `{{contact.company_name}}` (Empresa), `{{contact.job_title}}` (Cargo), `{{contact.address.city}}` (e `.cep`/`.street`/`.number`/`.neighborhood`/`.state`...), `{{contact.custom_attribute.<chave>}}`.
 - Conversa: `{{conversation.display_id}}`, `{{conversation.custom_attribute.<chave>}}`.
 - Variável sem valor sai vazia (não quebra). Texto SEM `{{` sai idêntico (preserva o cache do prompt) — só use variável quando agregar. Erro de digitação (filtro inválido, `{{` sem fechar) degrada suave: o pedaço com erro sai vazio e o resto das variáveis continua resolvendo (exceção: bloco `{% %}` sem fechar ainda cai pra texto cru).
 - Conta (2026-07): `{{account.custom_attribute.<chave>}}` (slogan, endereço...) AGORA resolve nas instruções e cenários — MAS só os atributos de conta que você DEFINIU (via `account_variables_create`); campos internos de faturamento e secrets NUNCA aparecem no autocomplete nem resolvem. O editor de Instruções/Cenários já sugere essas variáveis de conta ao digitar `{{`.
@@ -463,7 +507,13 @@ puxados. Se a ativação reclamar de sample, NÃO é bloqueio — a integração
 - `ContactLabel` `{id}` — etiqueta de CONTATO (novo)
 - `ContactAttribute` `{key, value}` — atributo do contato (novo)
 - `CardAttribute` `{key, value}` — atributo do card Kanban (novo)
-- `AgentTeam` `{assignee_ids:[], team_ids:[]}` — responsável atual OU time da conversa (novo)
+- `AgentTeam` `{assignee_ids:[], team_ids:[], assignee_mode?, team_mode?}` — responsável atual OU time da
+  conversa. **Modos (24/09/2026):** `assignee_mode:'none'` = conversa SEM responsável ("Sem atendente"),
+  `'any'` = com qualquer responsável; `team_mode:'none'|'any'` igual para time. Ausente/`'specific'` = usa os
+  ids (comportamento de sempre). Vale QUALQUER conversa do contato, de qualquer status. Atendente e time
+  SEMPRE somam (um OU outro) — inclusive em blocos `AgentTeam` separados, que viram UMA seção só; o
+  `audience_mode:'all'` cruza o AgentTeam com as OUTRAS seções (etiqueta, funil, atributo), não atendente com
+  time. "Sem atendente E com time" não é montável hoje. Mesmos modos na `exclusion`.
 
 O campo `audience_mode` define a combinação ENTRE seções:
 - `"sum"` (default): união — contato em QUALQUER seção entra

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

@@ -149,7 +149,12 @@ Company
 ├── id (PK)
 ├── account_id (FK)
 ├── name
-└── domain
+├── domain
+├── description
+├── contacts_count
+├── avatar (foto)
+├── additional_attributes (jsonb: legal_name, cnpj, phone, email, address{...}, social_profiles{...}; 2026-09-25)
+└── last_activity_at (ultima vez que um contato da empresa teve atividade; 2026-09-25)
 
 AttributeChange (histórico de alterações de atributo — 2026-09-11)
 ├── id (PK)
@@ -173,9 +178,34 @@ não gera; chaves protegidas (rastreio `utm_*`/`gclid`, `waha_*`, `eclinica_*`,
 nascimento e documentos vêm mascarados (`masked: true`) para quem não é administrador. Retenção 180 dias.
 
 **`additional_attributes` vs `custom_attributes` no Contato:**
-- `additional_attributes` (jsonb): campos do sistema porém **EDITÁVEIS via API** (`permitted_params` permite `additional_attributes: {}`). Guarda chaves padrão como `city`, `company`, `country_code` — que são as chaves filtráveis em `lib/filters/filter_keys.yml` (tipo `additional_attributes`). NÃO é não-editável.
+- `additional_attributes` (jsonb): campos do sistema porém **EDITÁVEIS via API** (`permitted_params` permite `additional_attributes: {}`). Guarda chaves padrão como `city`, `company_name` (o campo "Empresa" da ficha), `job_title` (o "Cargo", 2026-09-25) e `country_code`. NÃO é não-editável.
 - `custom_attributes` (jsonb): dado de negócio livre, definido pelo cliente via Atributos Customizados.
 
+**Empresas (2026-09-25):** o contato pode estar ligado a UMA empresa (`company_id`). Ligar/tirar:
+`lionchat_contacts_update` com `company_id` (empresa da mesma conta; vazio/null tira; se a chave nao for
+enviada nada muda) ou `lionchat_companies_contacts_create` / `_destroy`. Regra do texto
+`additional_attributes.company_name`: escolher a empresa faz ele virar o nome da empresa; tirar so apaga se
+ele ainda era o nome dela; renomear a empresa so troca nos contatos que ainda tinham o nome antigo. **Empresa e
+vinculo sao SEMPRE manuais** (25/09): o sistema NAO cria empresa nem vincula contato pelo dominio do e-mail.
+**Teto: 100 contatos por empresa** — o 101o e recusado (422, "Esta empresa ja tem 100 contatos...") por qualquer
+caminho (ficha, `lionchat_companies_contacts_create`, `lionchat_contacts_update`/`_create` com `company_id`);
+tire alguem antes de colocar outro. O cargo da
+pessoa na empresa e `additional_attributes.job_title`. A pagina da empresa junta os contatos
+(`lionchat_companies_contacts_list`), as anotacoes (`lionchat_companies_notes_list`: as da PROPRIA empresa,
+`kind: company`, + as dos contatos, `kind: contact`), as conversas (`lionchat_companies_conversations_list`,
+filtradas pelo que o usuario pode ver), os documentos de todos os contatos (`lionchat_companies_documents_list`,
+so leitura, cada item com `contacts[]` — o mesmo arquivo mandado a varios contatos vem UMA vez) e os compromissos
+(`lionchat_companies_tasks_list`) e os cards do Kanban dos contatos (`lionchat_companies_kanban_items_list`, cada
+card com `contacts[{id,name}]`, so os que o usuario ve no quadro). No card do quadro,
+`conversation.contact.company_id`/`company_name` dizem a empresa do contato do card. Contratos dos contatos: `lionchat_signature_envelopes_list` com `company_id`.
+Anotacao da empresa: `lionchat_companies_notes_create` / `_update` / `_destroy` (`{note:{content}}`; qualquer
+atendente). Cadastro da empresa (25/09): `lionchat_companies_create`/`_update` aceitam
+`additional_attributes` com `legal_name`, `cnpj` (validado; grava so digitos), `phone`, `email`,
+`address{cep,street,number,complement,neighborhood,city,state,country}` e
+`social_profiles{linkedin,facebook,instagram,telegram,tiktok,twitter,github}`. MESCLA: mande so o que muda;
+valor vazio apaga aquela chave. Excluir empresa: so administrador; os contatos ficam, so deixam de estar na empresa (as anotacoes da
+empresa vao junto).
+
 **Dados cadastrais (`additional_attributes.cadastral`):** CPF, CNPJ, RG, passaporte, nascimento,
 gênero, estado civil, profissão e endereço completo moram em `additional_attributes->cadastral`.
 São **IMUTÁVEIS por padrão** (primeira escrita vale) — alterar exige `force_update: true`, que SÓ
@@ -215,7 +245,8 @@ Funnel
 ├── name
 ├── stages (jsonb: hash com slug_etapa => { name, color, position, description, checklist_templates })
 ├── settings (jsonb: { agents: [], goals: [], automations: [{trigger_type, action, action_config, enabled}] })
-├── global_custom_attributes (jsonb array)
+├── global_custom_attributes (jsonb array — NENHUMA tela lê este campo do funil; os campos da aba do card
+│     são os do KanbanConfig acima)
 ├── meta_events_config (jsonb: won/lost/stages → Meta Pixel/CAPI events; cada bloco: enabled, name,
 │     is_standard, value_strategy, value_fixed, currency, messaging_name — este último é o evento de
 │     ANÚNCIO DE WHATSAPP, tri-estado: ausente = automático, '' = não enviar, um dos 14 nomes da Meta;
@@ -241,9 +272,10 @@ KanbanItem
 ├── stage_entered_at (datetime)
 ├── position (int, ordem dentro da etapa)
 ├── conversation_display_id (FK opcional → Conversation.display_id)
-├── item_details (jsonb)
-├── custom_attributes (jsonb)
-├── assigned_agents (jsonb array)
+├── item_details (jsonb — os campos da aba Campos ficam em item_details.custom_attributes, LISTA de
+│     {name, type, value}; nunca objeto {chave: valor})
+├── custom_attributes (jsonb — coluna que NENHUMA tela mostra; nao confundir com a lista acima)
+├── assigned_agents (jsonb array — para gravar: lista de NUMEROS [5, 12])
 ├── linked_conversations (jsonb array de { display_id })
 ├── checklist (jsonb array de itens — NAO e tabela separada; ver abaixo)
 ├── activities (jsonb)
@@ -492,7 +524,7 @@ daquele tipo no calendário; vazio = cor do agente. A tarefa devolve `booking_co
 
 ## e-Clínicas (Efficient) — integração de clínicas
 
-17 eventos de webhook, cada um mapeável a automação OU flow na tela Integrações > e-Clínica
+19 eventos de webhook, cada um mapeável a automação OU flow na tela Integrações > e-Clínica
 (o mapeamento e os lembretes passaram a ser editáveis por MCP em 31/08/2026, com
 `lionchat_eclinica_integrations_update` — ele **SUBSTITUI** o objeto inteiro, então leia com
 `_show` e devolva completo, senão apaga o resto):
@@ -502,7 +534,10 @@ daquele tipo no calendário; vazio = cor do agente. A tarefa devolve `booking_co
 `cliente_inclusao_pagamento`, `controle_laboratorio_novo`, `controle_laboratorio_alterado`,
 `agendamento_aguardando`, `odontograma_aprovado`, `procedimento_finalizado`,
 `cliente_alteracao_pagamento`, `odontograma_finalizado`, `inclusao_procedimento`
-(capturados ao vivo, não documentados pelo e-Clínica).
+(capturados ao vivo, não documentados pelo e-Clínica) +
+`agendamento_confirmado_link` e `agendamento_cancelado_link` (18/09/2026 — o PACIENTE confirmando/
+cancelando pelo link do portal, ecli.co; confirmado processa como `agendamento_alterado`, mantendo o
+lembrete; cancelado processa EXATAMENTE como `agendamento_desmarcado`, cancelando o lembrete).
 
 O recurso `eclinica_integration` da conta passou a ser ligado e desligado pelo PRÓPRIO cadastro da
 integração (10/09/2026, `auto_managed`): sumiu do Super Admin e não há passo manual — os blocos de

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

@@ -36,6 +36,14 @@ E/OU é encadeado condição a condição (sem parênteses).
 Atributo personalizado: informe `custom_attribute_type` na condição — `'conversation_attribute'`
 (atributo da conversa) ou `'contact_attribute'`. Sem ele o escopo pode sair errado.
 
+**`contact_attribute` lê a FICHA DO CONTATO da conversa (funciona de verdade desde 24/09/2026).** Antes o
+servidor ignorava o valor e lia o atributo da própria conversa — por isso lead de formulário da Meta
+(formulário, anúncio, campanha e 1ª/última origem ficam SÓ no contato) não era achado. Agora a conversa entra
+quando o contato dela casa. Chave precisa ter cadastro de atributo DE CONTATO na conta (senão 422). Exemplo:
+`{attribute_key:'meta_lead_form_name', custom_attribute_type:'contact_attribute', filter_operator:'contains',
+values:['vendas']}`. Negativos (`not_equal_to`, `does_not_contain`, `is_not_present`) incluem a conversa cujo
+contato não tem o dado. Texto compara sem maiúscula/acento.
+
 - `chat_type` em `conversations_filter` funciona desde 19/08/2026 (antes respondia 500). `group` =
   conversa de grupo de WhatsApp; `individual` cobre também canal, transmissão e status. Com
   `not_equal_to`, conversa sem contato vinculado NÃO some do resultado.
@@ -78,7 +86,8 @@ Mesmo shape de condição. 15/página.
 | attribute_key | Operadores |
 |---|---|
 | `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 |
+| `name`, `email`, `identifier`, `city`, `company_name` (Empresa), `job_title` (Cargo), `profession` | equal_to, not_equal_to, contains, does_not_contain |
+| `company` | **campo ANTIGO — nada grava nele, nunca casa. Use `company_name`** (2026-09-25). Continua aceito só para não quebrar regras antigas |
 | `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 |
@@ -162,6 +171,13 @@ Params: `funnel_id` (obrigatório), `from`, `to`, `user_ids[]` (agentes), `team_
 | `moved` | só quando entrou na etapa atual (mesma expressão do `stage_date_*` da seção 3) | "o que se mexeu no período" |
 | `closed` | só ganhos/perdidos no período | **a pergunta de receita** — é a régua certa pra "quanto vendemos em julho" |
 
+**Ganho/perda pela DATA DO FECHAMENTO (23/09/2026).** Com a régua `any` o relatório traz também cards que
+nasceram no período mas fecharam DEPOIS dele. Por isso, para "quanto ganhamos/perdemos em julho", leia
+`wonInPeriod`/`wonValueInPeriod` e `lostInPeriod`/`lostValueInPeriod` (este último é campo NOVO) — **nunca**
+`statusDistribution`, que é a foto do status de HOJE (serve só para "negócios abertos agora"). Desde 23/09 os
+motivos de ganho/perda, os perdidos recentes, a receita por semana e o ranking de vendedores também contam só
+o que FECHOU no período — antes somavam por status de hoje e divergiam do quadro de Ganhos na mesma tela.
+
 O relatório de UMA etapa — tool `lionchat_funnels_stage_report` (`GET /funnels/:id/stage_report`, o
 painel que abre dentro do quadro) — tem as MESMAS 4 opções de régua, mesmo parâmetro `date_basis` e as
 MESMAS expressões da seção 3, mas o **padrão dele é `moved`**, não `any`. Não é inconsistência: ele

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

@@ -140,6 +140,7 @@ Webhooks embutidos NÃO aparecem na listagem de integrações standalone; exclui
 **Gatilhos de AGENDAMENTO — Booking NATIVO do LionChat (2026-08-20):** `booking_created` (alguém marcou pelo link público, pela IA ou pelo painel), `booking_cancelled` (paciente cancelou pelo link, IA cancelou ou a equipe cancelou na Agenda), `booking_rescheduled` (a data/hora mudou — link do paciente, IA, editar/adiar na Agenda), `booking_completed` (equipe concluiu na Agenda; exige a Agenda unificada ligada na conta). **Não é e-Clínica.** Config (tudo opcional, vazio = todos): `booking_event_type_ids` (array de ids de tipo de agendamento, **STRING**), `agent_ids` (array de ids de usuário — o RESPONSÁVEL da tarefa), `create_conversation` (boolean, padrão `false`: só dispara para quem já tem conversa numa caixa do flow; `true` = cria a conversa na 1ª caixa do flow). Exemplo: `{ "key": "booking_created", "config": { "booking_event_type_ids": ["44"], "agent_ids": [], "create_conversation": true } }`. São INERTES a evento de conversa (quem dispara é o `Booking::FlowTriggerDispatcher`, por CONTA — caixa do flow só define onde a conversa é criada/reusada). Variáveis no flow: `{{booking.date}}` (DD/MM/AAAA), `{{booking.time}}`, `{{booking.weekday}}`, `{{booking.datetime}}` (ISO), `{{booking.type}}`, `{{booking.type_format}}` (presencial/videochamada), `{{booking.duration}}`, `{{booking.agent}}`, `{{booking.status}}` (confirmado/cancelado/remarcado/concluído), `{{booking.description}}`, `{{booking.cancel_url}}`, `{{booking.reschedule_url}}`, `{{booking.color}}`, `{{booking.id}}`; só no remarcado: `{{booking.previous_date}}`, `{{booking.previous_time}}`, `{{booking.previous_datetime}}`; `{{booking.meeting_url}}` NÃO vem no criado (nasce vazio). Data/hora vêm da TAREFA da Agenda (sempre atuais). Regras: o evento mais novo SUBSTITUI a rodada ativa do mesmo flow na mesma conversa (2ª consulta do mesmo paciente, ou cancelado chegando com o criado ainda esperando resposta); excluir a tarefa, reabrir cancelada ou desfazer conclusão NÃO disparam; adiar (snooze) conta como remarcado; tipo com confirmação/lembrete próprios ligados + `booking_created` = o paciente pode receber duas mensagens (a tela avisa). Colisão entre flows é por CONTA: mesmo kind + tipos se cruzando + agentes se cruzando (vazio = todos). Há também `{{booking.event}}` (`created`|`cancelled`|`rescheduled`|`completed` — bom pra condição; não aparece no seletor da tela, mas resolve); `{{trigger.type}}` = a chave do gatilho (ex.: `booking_created`), `{{trigger.kind}}` = `created`|`cancelled`|`rescheduled`|`completed` e `{{trigger.booking_id}}`. SÓ flow de conversa **individual** (a tela nem oferece em flow de grupo); **nunca dispara flow `ai_tool`**. Em caixa WhatsApp OFICIAL, conversa criada nova (ou parada há mais de 24h) está FORA da janela — texto livre no 1º bloco cai em `window_closed`/erro; comece por template.
 
 **TRAVA DE GATILHO DUPLICADO (2026-06-16) — leia ANTES de ativar/criar flow ativo:** o sistema BLOQUEIA ter dois flows ATIVOS com o MESMO gatilho na MESMA inbox e mesmo `conversation_mode` (evita o evento disparar dois flows). Colisão = mesmo tipo de gatilho + config cruzando (mesmas keywords/funil/labels/url/etc) + inbox compartilhada + mesmo modo. EXCEÇÕES que podem coexistir: `webhook_received`, `manual_trigger` e `campaign_trigger` (este último porque não dispara por evento — é só uma autorização para a campanha).
+- **`date_trigger` separa por HORÁRIO (24/09/2026):** dois flows no mesmo campo de data, mesma direção e mesmos dias NÃO colidem se os dois tiverem horário FIXO diferente (ex.: "1 dia depois às 08:00" e "às 14:00"). Horário vindo de atributo/fórmula continua colidindo (só existe na hora do disparo); `send_time` vazio conta como 09:00 e "8:00" = "08:00". A entrega é de 10 em 10 minutos — horários a menos de 10 min podem sair juntos.
 - Ao **ativar** (`flows_toggle` inativo→ativo) ou **criar já ativo**: qualquer conflito é barrado.
 - Ao **editar** um flow já ativo: só conflito NOVO é barrado (duplicados que já existiam são preservados).
 - A API responde **422** com `{ "error_code": "flow_trigger_conflict", "conflicts": [{ flow_id, flow_name, trigger_type, inbox_id, inbox_name }] }`.
@@ -605,6 +606,8 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 
 **Coerção por TIPO (2026-07-29):** em `attr_source: 'contact'|'conversation'`, o `attr_value` de atributo personalizado é coagido pelo tipo da definição antes de gravar: número/moeda/porcentagem viram numérico ("1.234,56" → 1234.56; inteiro fica inteiro), checkbox aceita sim/não/true/false e grava BOOLEANO, lista casa caixa-insensível e grava a opção canônica, data aceita DD/MM/AAAA ou ISO, hora aceita "14:30"/"14h30". Valor irreconhecível grava como veio e o passo mostra nota âmbar no histórico. Card NÃO coage (atributo de card não tem definição tipada no backend).
 
+**Empresa e Cargo (2026-09-25):** `contact.company_name` e `contact.job_title` valem em CONDIÇÃO (`attr_source: 'contact'`, `attr_key` igual ao path), em filtro de regras e como variável (`{{contact.company_name}}`, `{{contact.job_title}}`). São SÓ LEITURA: a ação "Alterar atributo do contato" NÃO grava esses dois (o texto Empresa anda junto com a empresa vinculada — para ligar a empresa use `lionchat_contacts_update` com `company_id`).
+
 **Campos NATIVOS do contato (2026-07-29):** com `attr_source: 'contact'`, `attr_key` também aceita os paths canônicos `contact.name`, `contact.email`, `contact.cpf`, `contact.cnpj`, `contact.rg`, `contact.passport`, `contact.date_of_birth`, `contact.gender`, `contact.marital_status`, `contact.profession` e `contact.address.{cep,street,number,complement,neighborhood,city,state,country}` — gravam na ficha nativa do contato (não em custom_attributes). Regras: telefone/identifier/etiquetas NÃO são aceitos (mapa fechado — chave fora dele vira atributo personalizado comum); documentos, nascimento, gênero e **e-mail** só preenchem campo VAZIO; nome/profissão/estado civil/endereço sobrescrevem; valor em branco nunca grava; gênero aceita `m|f|o|na` e estado civil `solteiro|casado|uniao_estavel|divorciado|separado|viuvo`; data de nascimento em `dd/mm/aaaa` ou `aaaa-mm-dd`. Recusas aparecem no histórico de execução (passo 'skipped'/'error' com mensagem).
 
 **Campos NATIVOS do contato em CONDIÇÃO (2026-08-13):** o bloco de Condições e o filtro do gatilho de data passaram a LER os mesmos paths nativos (`contact.name`, `contact.cpf`, `contact.marital_status`, `contact.address.city`, ...) na fonte `contact` — antes só liam atributo personalizado e o campo da ficha voltava vazio, jogando tudo na saída padrão em silêncio. Use com `is_empty`/`is_not_empty` para montar "o CPF está preenchido?". Aceita a forma curta (`contact.cpf`) e a longa (`contact.cadastral.cpf`). **`contact.label` NÃO é aceito** em condição (consulta cara em caminho reativo). **Gênero e estado civil são listas fechadas**: compare com o valor canônico (`m|f|o|na`, `solteiro|casado|uniao_estavel|divorciado|separado|viuvo`) — comparar com "Masculino" nunca casa.
@@ -705,7 +708,9 @@ Exemplo: `{"aiMode":"sentiment","aiAssistantId":"12","aiModel":"gpt-4.1-mini","a
 curinga** — não existe "a família gpt-5 inteira":
 `gpt-4o-mini`, `gpt-4o`, `gpt-4.1-nano`, `gpt-4.1-mini`, `gpt-4.1`, `gpt-5-mini`, `gpt-5`,
 `gpt-5.2`, `gpt-5.4-nano`, `gpt-5.4-mini`, `gpt-5.4`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-terra`,
-`gpt-5.6-sol`, `o1`, `o3`, `o3-mini`, `o4-mini`.
+`gpt-5.6-sol`, `gpt-6-luna`, `gpt-6-sol`, `o1`, `o3`, `o3-mini`, `o4-mini`.
+A família **`gpt-6` (luna/sol) entrou em 23/09/2026** pelo mesmo trilho do `gpt-5.6` (porta `/v1/responses`,
+sem temperatura, fora do Formulário de Lead).
 A família **`gpt-5.6` (luna/terra/sol) voltou em 09/2026** (tinha sido removida em 2026-07-29 porque
 recusa function tools no canal antigo): o servidor fala com esses três pela porta `/v1/responses`.
 Eles ignoram a temperatura do bloco (só o padrão) e **NÃO valem no bloco de IA do Formulário de Lead**

package/dist/docs/resources/glossary.md

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