docs(newwhats): Secretária IA — arquitetura, RAG sem pgvector, modo teste

Documenta o plugin secretaria: agente + cérebro de nós, resposta com fallback
de providers, RAG por embeddings+cosseno na aplicação (sem pgvector, com o
porquê), tabela sec_knowledge_chunks, indexação lazy e fallback, kill switch
em dev e cuidado com migrations Knex.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

projetos/newwhats.clube67.com/secretaria-ia.md

@@ -0,0 +1,54 @@
+# newwhats.clube67.com — Secretária IA (plugin `secretaria`)
+
+> Específico deste projeto. Atendente virtual de IA do newwhats, no plugin
+> `backend/plugins/secretaria/` (gerenciado por **Knex**, tabelas `sec_*`).
+
+## Arquitetura
+
+- **Agente** (`sec_agents`): define provider/modelo/temperatura/`context_window`.
+- **Cérebro** = nós (`sec_brain_nodes`), tipos: `persona`, `knowledge`,
+  `rules`, `calendar`, `escalation`. O `brain.ts` (`buildSystemPrompt`) monta o
+  system prompt concatenando os nós ativos + data/hora + protocolo + resumo.
+- **Resposta**: `callAI` com **fallback de providers** (config do plugin:
+  `openai_key`, `gemini_key`, `anthropic_key` — em Admin → Plugins → Secretária IA).
+- **Conversas/mensagens**: `sec_conversations` / `sec_messages` (com telemetria
+  `usage_tokens`/`provider_used`/`model_used`).
+- **UI**: `/secretaria` (abas Conversas, Cérebro, Agenda, Agentes, Números) +
+  ícone de **Ajuda** com modelos prontos por nó (botão "Usar este modelo").
+
+## RAG na Base de Conhecimento (SEM pgvector)
+
+**Por que sem pgvector:** a extensão **não está disponível** no Postgres da
+VPS3 nem na imagem do `pgdev`, e o role `newwhats` **não é superuser**
+(`CREATE EXTENSION` negado). Solução adotada (decisão 28/jun/2026):
+
+- `embeddings.ts`: **chunking** + **embed** (OpenAI `text-embedding-3-small`
+  ou Gemini `text-embedding-004`, conforme a chave) + **cosseno** — tudo em Node.
+- Tabela **`sec_knowledge_chunks`**: vetor serializado em **JSON/text** (sem
+  extensão) + índices em `agent_id`/`node_id`.
+- `brain.ts`: no nó `knowledge`, injeta só os **top-4 trechos** relevantes à
+  pergunta. **Indexação lazy** (reindexa quando o conteúdo muda — hash MD5).
+- **Fallback**: sem chave de embedding ou em qualquer erro → injeta o conteúdo
+  **inteiro** (comportamento anterior). Nunca regride.
+
+> Para bases pequenas (clínica/empresa) é rápido e suficiente. Quando a VPS3
+> tiver `pgvector`, dá para migrar a busca ao banco sem mudar a interface.
+
+## Modo teste / segurança
+
+- `DISABLE_OUTBOUND=true` (kill switch global, ver `ambiente-dev.md`) bloqueia
+  **todo** envio — inclusive respostas automáticas da secretária — em dev.
+- ⚠️ Ao conectar uma sessão WhatsApp **real** em dev, a secretária responde
+  sozinha (bots/IA). Mantenha o kill switch ligado nos testes.
+
+## Migrations (Knex) — cuidado
+
+O `migrate.ts` cria tabelas `if (!hasTable)` e adiciona colunas novas com
+blocos `hasColumn`/`alterTable` (idempotentes). **Ao adicionar coluna usada em
+runtime, adicione também o bloco de migração** — senão bancos antigos quebram
+(ex.: faltava `sec_messages.usage_tokens/provider_used/model_used` → erro 42703,
+corrigido).
+
+## Futuro (ver doc de evolução)
+
+Memória de longo prazo / humanização — em avaliação. Atualizar aqui quando definido.