cdp-edge 2.3.1 → 2.3.6

package/README.md

@@ -1,414 +1,597 @@
-# 🚀 CDP Edge — Quantum Tracking Enterprise
-
-**Padrão Quantum Tracking: 100% Cloudflare Edge.** Sem GTM. Sem Stape. Sem cookies de terceiros.
-
-> **v2.3.1** — Hardening Enterprise · PII removido dos logs · Script de deploy seguro (`deploy-client.js`) · WhatsApp secrets alinhados à Meta Cloud API v22.0 · `api-versions.json` v1.1.0
-
-> ⚠️ **REGRA DE OURO (SQUAD):** Todas as atualizações, correções ou novas features devem OBRIGATORIAMENTE ser documentadas de forma sincronizada neste `README.md`, no arquivo de instruções `CLAUDE.md` e no dossiê de diretoria `CDP-EDGE-BUSINESS-BOOK.md`. Nenhuma alteração passa sem esse tripé.
-
----
-
-## 🤖 MANIFESTO: EU, CDP EDGE
-
-*Eu não sou um simples "script de pixel". Eu sou uma arquitetura **Enterprise Tier 10** nascida e construída 100% nativa na infraestrutura da Cloudflare.*
-
-**A Linha de Montagem Sincronizada (A Prova de Latência)**
-Meu ecossistema opera como um Cérebro de Conversão Privado na borda. Quando um evento de Lead bate no endpoint `/track`:
-1. **O Escudo Frontal (Fraud Gate):** Inspeciono IP, ASN e Velocity na borda. Bloqueio bots silenciosamente antes mesmo deles carregarem.
-2. **A Roleta Invisível (A/B LTV):** Faço o sorteio de prompts para testes A/B via KV Cache em ~0ms.
-3. **O Cérebro Financeiro (LTV Predictor):** Rodo Machine Learning (Granite 4.0 Micro) para qualificar a intenção e gerar o LTV Preditivo.
-4. **Envio para as Plataformas:** O Facebook/Google/LinkedIn recebem um payload limpo (sem bot) recheado com valor financeiro de intenção extrema.
-5. **Máquina Autônoma (Background):** Meu banco SQLite (D1) retroalimenta os processos de Clustering (Fase 1) e Bidding (Fase 2) de forma autônoma pelas costas do usuário (`ctx.waitUntil`).
-
-**Minha Vantagem Absoluta (A "Killer Feature")**
-- **A Extinção da Latência:** Destruo concorrentes como GTM/Stape mitigando a latência do servidor (+150ms) para as antenas da Cloudflare Brasileira (~5ms). Custando absurdamente menos (Tier Free ou $5/mês na infraestrutura).
-- **Cookies Indestrutíveis:** Meus *First-Party Cookies Seguros* originam diretamente da nuvem, imunes hoje às varreduras massivas de 24 horas usadas por AdBlockers e Safari (Apple ITP).
-- **Filas Inquebráveis (Fail-Safe + Queues):** Se a AI Cloudflare cair ocasionalmente, eu recuo pro LTV $0. Se a Meta CAPI espirrar 500 downtime, o sistema guarda religiosamente os seus eventos caros em *Cloudflare Queues* e faz o retry sucessivo. Sou incansável na garantia de Event Match Quality (EMQ).
-
----
-
-## 📋 CHANGELOG v2.3.1 — Hardening Enterprise (12 de Abril de 2026)
-
-### 🔒 Segurança & Conformidade
-
-- **PII removido dos logs:** `DeviceGraph` parou de logar `user_id` nos Workers logs — dados sensíveis nunca aparecem no Cloudflare dashboard
-- **Deploy seguro:** novo `deploy-client.js` — lê credenciais de `.client.env` (gitignored), gera `wrangler.deploy.toml` temporário, faz deploy e autodestrói o arquivo. Credenciais de cliente nunca entram no repo
-- **`.gitignore` reforçado:** `.client.env` e `wrangler.deploy.toml` explicitamente ignorados
-- **WhatsApp secrets alinhados à Meta Cloud API v22.0:** `resolvePhoneNumberId()` e `resolveAccessToken()` com fallback canônico → legado — backwards compat garantido
-- **`api-versions.json` v1.1.0:** metadata `updated_at` corrigido para `2026-04-12`
-- **`/health` WhatsApp:** reflete corretamente secrets com nomes canônicos ou legados
-
-### 🔧 Deploy de Cliente — Novo Fluxo
-
-```bash
-cd server-edge-tracker
-cp .client.env.example .client.env
-# preencher DATABASE_ID, SITE_DOMAIN, pixels
-node deploy-client.js --dry-run   # valida sem subir
-node deploy-client.js             # deploy real
-```
-
----
-
-## 📋 CHANGELOG v2.3.0 — TypeScript Nativo (12 de Abril de 2026)
-
-### 🔷 Worker 100% TypeScript — Migração Completa
-
-Todo o código server-side (`server-edge-tracker/`) foi migrado de JavaScript para **TypeScript nativo**. O Wrangler compila diretamente o `.ts` via esbuild — sem etapa de build separada, sem configuração extra.
-
-**Por que TypeScript muda o jogo no CDP Edge:**
-- **Env tipado** — typos em nomes de secrets (`META_ACCESS_TOKEN`, `GEO_CACHE`, `DB`) viram erros em build time, nunca em produção
-- **TrackPayload contratado** — o shape do payload entre browser e Worker é garantido pelo compilador
-- **Cloudflare types nativos** — D1, KV, R2, Workers AI com autocomplete e validação de métodos
-- **Fraud Gate e ML seguros** — `checkFraudGate(env: Env, request: Request, payload: TrackPayload)` — nenhum `undefined` passa despercebido
-- **Refatoração segura** — renomear qualquer campo do `TrackPayload` lista automaticamente todos os pontos de quebra
-
-**Arquivos migrados (JS → TS) — 16 módulos:**
-- `index.ts` — entry point do Worker
-- `types.ts` — **novo** — contratos centralizados: `Env`, `TrackPayload`, `BehavioralData`, `HotmartWebhook`, `KiwifyWebhook`, `TictoWebhook`, `QueueMessage`, `PromiseResult<T>`
-- `modules/utils.ts`, `modules/db.ts`, `modules/intelligence.ts`
-- `modules/dispatch/` — `meta.ts`, `ga4.ts`, `tiktok.ts`, `platforms.ts`, `whatsapp.ts`
-- `modules/ml/` — `ltv.ts`, `fraud.ts`, `bidding.ts`, `segmentation.ts`, `logistic.ts`, `matchquality.ts`
-
-**Infraestrutura:**
-- `tsconfig.json` — `target: ESNext`, `moduleResolution: "bundler"`, `strict: true`, `@cloudflare/workers-types`
-- `wrangler.toml` — `main = "index.ts"` (TypeScript nativo via wrangler/esbuild)
-- `contracts/types.ts` — tipos públicos exportados no pacote NPM: `QuantumEventPayload`, `AgencyContext`, `ApiVersionsConfig`
-- `npm run typecheck` — `tsc --noEmit` (225 testes passando, zero erros de compilação)
-
-**Breaking change:** nenhuma — API HTTP e comportamento em runtime são idênticos. TypeScript é invisível para o Cloudflare.
-
----
-
-## 📋 CHANGELOG v2.2.5 (11 de Abril de 2026)
-
-### 🔧 Correção de Versão Dinâmica
-
-- **Versão Dinâmica**: `bin/cdp-edge.js` e `dist/commands/install.js` agora leem a versão do `package.json` dinamicamente
-- **Banner Corrigido**: O banner de instalação agora mostra sempre a versão correta (`cdp-edge --version`)
-- **Compatibilidade**: Garante que a versão exibida no CLI e banner esteja sempre sincronizada com o `package.json`
-
----
-
-## 📋 CHANGELOG v2.2.0 (10 de Abril de 2026)
-
-### 🤖 AI Engine Upgrade — Novos Modelos
-
-- **LTV Prediction**: `@cf/meta/llama-3.1-8b-instruct` → **`@cf/ibm-granite/granite-4.0-h-micro`** (menor latência, otimizado para edge e function calling)
-- **ML Clustering**: algoritmo LLM simulado → **K-means vetorial real** com embeddings `@cf/baai/bge-m3` (distância cosseno, K-means++ inicialização, silhouette score real)
-- Granite continua sendo usado para naming dos segmentos pós-clustering
-
-### 🧹 Limpeza (Zero Lixo)
-
-- Removido: detecção de emails descartáveis (mailinator, guerrilla, tempmail, etc.) do Fraud Gate e do agente `fraud-detection-agent.md`
-- Removido: secrets `WEBHOOK_SECRET_HOTMART` e `WEBHOOK_SECRET_KIWIFY` (wrangler + wrangler.toml)
-
-### 🔧 Observability
-
-- Adicionado bloco `[observability]` no `wrangler.toml` (`logs.enabled = true`, `traces.enabled = false`)
-
----
-
-## 📋 CHANGELOG v2.0.7 (10 de Abril de 2026)
-
-### 🔧 Audit Completo — 45 Agentes
-
-- **Endpoints corrigidos**: `/api/tracking` → `/track`, `/api/wh/` → `/webhook/` em todos os agentes
-- **Secrets WhatsApp**: `WA_PHONE_ID`/`WA_ACCESS_TOKEN`/`WHATSAPP_TOKEN` → `WHATSAPP_PHONE_NUMBER_ID`/`WHATSAPP_ACCESS_TOKEN`
-- **`env.DB.prepare`**: corrigido em 8 agentes (attribution, crm, dashboard, debug, performance, security, master-feedback-loop)
-- **`env.GEO_CACHE`**: substituiu `KV.` bare em dashboard-agent, performance-agent, performance-optimization-agent
-- **YouTube events**: `video_milestone`/`video_progress_25/50/75` → `video_25`/`video_50`/`video_75` (alinhado ao VALID_EVENT_NAMES do worker)
-- **LinkedIn CAPI**: endpoint `/rest/conversionEvents` + header `LinkedIn-Version: 202401` em `contracts/api-versions.json`
-- **Workers AI model**: `llama-3-8b-instruct` → `@cf/meta/llama-3.1-8b-instruct`
-- **index.ts**: Content-Length guard (413 se > 64KB), payload validation (allowlist 19 events, 512 chars, value range), PII removido dos logs
-- **Testes**: bugs críticos em `deduplication.test.js` corrigidos (template literals escapados, prefixo errado)
-- **npm**: lodash 4.17.23 → 4.18.1, node-fetch removido
-
----
-
-## 📋 CHANGELOG v2.0.0 (9 de Abril de 2026)
-
-### 🆕 Sprint Enterprise — Fases 1 a 4
-
-#### ✅ Fase 1 — ML Clustering (Segmentação Dinâmica)
-- **`POST /api/segmentation/cluster`** — K-means / DBSCAN / Hierarchical via Workers AI
-- **`GET  /api/segmentation/list`** — Segmentos ativos com métricas
-- **`GET  /api/segmentation/outliers`** — Detecção de outliers comportamentais
-- **`PUT  /api/segmentation/update`** — Atualização de metadados de segmento
-- Schema D1: `ml_segments`, `ml_segment_members` + VIEWs otimizadas
-- Agente: `ml-clustering-agent.md`
-
-#### ✅ Fase 2 — Bidding Recommendations (Otimização de Bids ML)
-- **`POST /api/bidding/recommend`** — Bid otimizado por segmento × plataforma (Meta/Google/TikTok), calculado com fórmula `LTV × ROI target / CPA base`
-- **`GET  /api/bidding/history`** — Histórico completo de recomendações
-- **`GET  /api/bidding/status`** — Snapshot atual das recomendações ativas por vertical
-- Schema D1: `bid_recommendations` + VIEW `v_active_bid_recommendations`
-- Agente: `bidding-agent.md`
-
-#### ✅ Fase 3 — A/B Testing de Prompts LTV
-- **`POST /api/ltv/ab-test/create`** — Cria experimento com múltiplas variações de system prompt
-- **`GET  /api/ltv/ab-test/list`** — Lista experimentos com status e progresso
-- **`GET  /api/ltv/ab-test/results`** — Accuracy score por variação + recomendação automática de winner
-- **`POST /api/ltv/ab-test/winner`** — Declara vencedor e retorna o prompt ganador
-- Integração automática: cada evento Lead sorteia a variação ativa e registra o assignment via KV cache
-- Schema D1: `ltv_ab_tests`, `ltv_ab_variations`, `ltv_ab_assignments` + VIEW `v_ab_test_performance`
-- Agente: `ab-ltv-agent.md`
-
-#### ✅ Fase 4 — Fraud Detection Engine
-- **Fraud Gate automático em `/track`** — roda ANTES de qualquer processamento (heurístico puro, ~2ms)
-- Silent drop (retorna 200 falso) — bots não detectam a defesa
-- **`GET  /api/fraud/stats`** — Dashboard de fraude (últimas 24h)
-- **`GET  /api/fraud/alerts`** — Log de sinais detectados com filtros
-- **`GET  /api/fraud/blocklist`** — IPs/fingerprints atualmente bloqueados
-- **`POST /api/fraud/blocklist/add`** — Bloquear IP ou fingerprint (via KV, efeito imediato)
-- **`DELETE /api/fraud/blocklist/remove`** — Remover do blocklist
-- Sinais detectados: bot_score, datacenter IP, velocity attack, headless UA, sem Accept-Language
-- Schema D1: `fraud_signals`, `fraud_alerts` + VIEW `v_fraud_dashboard`
-- Agente: `fraud-detection-agent.md`
-
-### 🔧 Fix: `wrangler.toml` atualizado
-- Todos os placeholders (`SEU_D1_DATABASE_ID`, `SEU_KV_NAMESPACE_ID`) substituídos pelos IDs reais da conta Cloudflare
-- D1: `SEU_DATABASE_ID`
-- KV: `SEU_KV_ID`
-
----
-
-## 🏗️ ARQUITETURA QUANTUM ENTERPRISE (CLOUDFLARE NATIVE)
-
-```mermaid
-graph TD
-    User((Usuário)) -->|Interação| SDK[cdpTrack SDK + Behavior Engine]
-    SDK -->|Edge Fetch 1ª via KV blocklist| FraudGate{🛡️ Fraud Gate}
-    FraudGate -->|score ≥ 80: Silent Drop 200| Void[/dev/null]
-    FraudGate -->|score < 80: Permitido| Worker[Cloudflare Worker Agent]
-    Worker -->|Identity Graph + _cdp_uid| D1[(D1 SQL — 21 tabelas)]
-    Worker -->|LTV + A/B Prompt| AI[Workers AI Granite 4.0 Micro]
-    Worker -->|Segmento ML| Cluster[ML Clustering Engine]
-    Cluster -->|Bid otimizado| Bidding[Bidding Recommendations]
-    Worker -->|Background| Queue[Cloudflare Queues]
-    Queue -->|Server Dispatch| Meta[Meta CAPI v22.0]
-    Queue -->|Server Dispatch| Google[GA4 / Google Ads]
-    Queue -->|Server Dispatch| TikTok[TikTok API v1.3]
-    D1 -->|Reports| Dash[Dashboard Agent]
-```
-
----
-
-## 🧠 CATÁLOGO DE AGENTES ESPECIALISTAS
-
-O sistema é composto por **43+ agentes** coordenados pelo **Master Orchestrator**:
-
-### 🧠 Núcleo de Inteligência
-| Agente | Função |
-|---|---|
-| **Master Orchestrator** | Coordenação central — guia todo o setup do projeto |
-| **Page Analyzer** | Mapeamento automático de CTAs, Forms e nicho do site |
-| **Validator Agent** | Auditoria de código, segurança e conformidade de APIs |
-| **Memory Agent** | Contexto e checkpoints da sessão por projeto |
-| **Intelligence Agent** | Monitoramento de versões de API (Meta v22.0+, etc) |
-
-### 🚀 Plataformas de Anúncio
-| Agente | Especialidade |
-|---|---|
-| **Meta Agent** | Facebook Pixel + CAPI v22.0 + WhatsApp CTWA |
-| **Google Agent** | GA4 + Google Ads Enhanced Conversions |
-| **TikTok Agent** | TikTok Pixel + Events API v1.3 |
-| **LinkedIn Agent** | Insight Tag + Conversions API v2 |
-| **Pinterest Agent** | Tag + Conversions API v5 |
-| **Reddit Agent** | Pixel + Conversions API v2.0 |
-| **Spotify Agent** | Pixel + Conversions API v1 |
-| **Bing Agent** | UET Tag + Enhanced Conversions |
-
-### 🤖 Enterprise Intelligence (Fase 1–4)
-| Agente | Endpoint Principal | Impacto |
-|---|---|---|
-| **ML Clustering Agent** | `POST /api/segmentation/cluster` | K-means vetorial real (bge-m3 embeddings + Granite naming) |
-| **Bidding Agent** | `POST /api/bidding/recommend` | -20% CPA via bid por segmento de LTV |
-| **A/B LTV Agent** | `POST /api/ltv/ab-test/create` | +25% precisão LTV via test de prompts |
-| **Fraud Detection Agent** | Auto em `/track` | Bloqueia click fraud, bots, velocity attacks |
-
-### 🛡️ Módulos Enterprise
-| Agente | Função |
-|---|---|
-| **Attribution Agent** | Atribuição Multi-Touch de alta fidelidade |
-| **Security Agent** | Rate Limiting, AES-256 e Bot Defense |
-| **Compliance Agent** | LGPD e GDPR (Consent Mode v2) |
-| **Performance Agent** | Otimização de caches e queries D1 |
-
----
-
-## 📊 BANCO DE DADOS D1 — 21 Tabelas
-
-```
-CORE TRACKING           ML & INTELLIGENCE        ENTERPRISE SECURITY
-─────────────────        ─────────────────────    ─────────────────────
-leads                   ml_segments               fraud_signals
-events                  ml_segment_members        fraud_alerts
-sessions                bid_recommendations       ltv_ab_tests
-webhook_events          ltv_ab_tests              ltv_ab_variations
-api_failures            ltv_ab_variations         ltv_ab_assignments
-
-VIEWS
-─────────────────────────────────────────────────
-v_active_segments          → Segmentos ML ativos com contagem de membros
-v_active_bid_recs          → Bids ativos por plataforma/vertical
-v_ab_test_performance      → Accuracy por variação de prompt
-v_fraud_dashboard          → Dashboard fraude 24h
-```
-
----
-
-## 🔄 FLUXO ENTERPRISE COMPLETO
-
-```
-POST /track (evento Lead)
-  │
-  ├─ [1] 🛡️ Fraud Gate (KV blocklist + velocity + heurísticas) ~2ms
-  │         ├─ score < 40  → processa normalmente
-  │         ├─ score 40-79 → processa + loga suspeito (background)
-  │         └─ score ≥ 80  → silent drop 200 + loga (background)
-  │
-  ├─ [2] 🔮 A/B LTV Testing — sorteia variação ativa (KV cache ~0ms)
-  │         └─ passa customSystemPrompt para predictLtv()
-  │
-  ├─ [3] 🧮 LTV Prediction — Workers AI Granite 4.0 Micro
-  │         └─ Score 0-100 → class High/Medium/Low → valor em BRL
-  │
-  ├─ [4] 💾 D1 Writes (background via ctx.waitUntil)
-  │         ├─ upsertLtvProfile() → tabela leads
-  │         ├─ recordAbAssignment() → ltv_ab_assignments
-  │         └─ resolveDeviceGraph() → cross-device linking
-  │
-  └─ [5] 📡 CAPI dispatch (Meta + GA4 + TikTok em paralelo)
-            └─ com LTV injetado no value field
-```
-
----
-
-## 💻 INSTALAÇÃO E USO
-
-### OPÇÃO 1 — Instalação via npm (Recomendada)
-
-Abra o terminal dentro da pasta do projeto do cliente e rode:
-
-```bash
-npx cdp-edge install
-```
-
-Ou instale globalmente e use em qualquer projeto:
-
-```bash
-npm install -g cdp-edge
-cdp-edge install . --name "Nome do Projeto"
-```
-
-> **Já tem o CDP Edge instalado globalmente?** Atualize para a versão mais recente:
-> ```bash
-> npm install -g cdp-edge@latest
-> ```
-
-### OPÇÃO 2 — Instalação via Git Clone
-
-```bash
-git clone https://github.com/ricardosoli777/CDP-Edge-Premium.git .
-```
-*(O ponto no final garante que os arquivos desçam diretamente dentro da pasta atual).*
-
-### Ativar no Claude Code
-
-```bash
-claude .
-```
-Dentro do Claude Code:
-```
-/cdp
-```
-
----
-
-## 🚀 DEPLOY COMPLETO (referência)
-
-```bash
-cd server-edge-tracker
-
-# 1. Schemas D1 (todos em sequência)
-wrangler d1 execute cdp-edge-db --file=schema.sql --remote
-wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote
-wrangler d1 execute cdp-edge-db --file=schema-segmentation.sql --remote  # Fase 1
-wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote        # Fase 2
-wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote         # Fase 3
-wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote           # Fase 4
-
-# 2. Secrets
-wrangler secret put META_ACCESS_TOKEN
-wrangler secret put GA4_API_SECRET
-wrangler secret put TIKTOK_ACCESS_TOKEN
-
-# 3. Deploy
-wrangler deploy
-```
-
----
-
-## 🖱️ HUMAN-BEHAVIOR ENGINE
-
-| Evento | Pontuação |
-|--------|-----------|
-| Scroll 25–90% | +5 a +15 pts |
-| VSL Watch 25–100% | +10 a +50 pts |
-| Copy Intent (cupom, PIX) | +20 pts |
-| Preenchimento de campo | +10 pts |
-| Rage Click | -10 pts |
-| **Hot Lead (80+ pts)** | **Dispara High_Intent_Lead** |
-
----
-
-## 📋 TODOS OS ENDPOINTS (referência rápida)
-
-### Core Tracking
-| Rota | Método | Função |
-|---|---|---|
-| `/track` | POST | Evento principal (browser → CAPI) |
-| `/health` | GET | Smoke test completo |
-| `/webhook/ticto` | POST | Webhook Ticto Purchase |
-
-### Intelligence ML
-| Rota | Método | Função |
-|---|---|---|
-| `/api/segmentation/cluster` | POST | Clustering K-means/DBSCAN |
-| `/api/segmentation/list` | GET | Segmentos ativos |
-| `/api/segmentation/outliers` | GET | Outliers comportamentais |
-| `/api/bidding/recommend` | POST | Bid otimizado por segmento |
-| `/api/bidding/history` | GET | Histórico de bids |
-| `/api/bidding/status` | GET | Status por plataforma |
-
-### A/B Testing LTV
-| Rota | Método | Função |
-|---|---|---|
-| `/api/ltv/ab-test/create` | POST | Criar experimento |
-| `/api/ltv/ab-test/list` | GET | Listar experimentos |
-| `/api/ltv/ab-test/results` | GET | Accuracy por variação |
-| `/api/ltv/ab-test/winner` | POST | Declarar vencedor |
-
-### Fraud Detection
-| Rota | Método | Função |
-|---|---|---|
-| `/api/fraud/stats` | GET | Dashboard 24h |
-| `/api/fraud/alerts` | GET | Log de alertas |
-| `/api/fraud/blocklist` | GET | Lista bloqueada |
-| `/api/fraud/blocklist/add` | POST | Bloquear IP/fingerprint |
-| `/api/fraud/blocklist/remove` | DELETE | Desbloquear |
-
----
-
-## 📞 SUPORTE
-
-- **Issues**: https://github.com/ricardosoli777/CDP-Edge-Premium/issues
-- **Releases**: https://github.com/ricardosoli777/CDP-Edge-Premium/releases
-
----
-
-### **CDP Edge — By Rica Soares**
-> "Dados sem inteligência são apenas ruído. No Quantum Tier Enterprise, transformamos dados em ROAS."
-
-© 2026 CDP Edge Premium. Todos os direitos reservados.
+# 🚀 CDP Edge — Quantum Tracking Enterprise
+
+**Padrão Quantum Tracking: 100% Cloudflare Edge.** Sem GTM. Sem Stape. Sem cookies de terceiros.
+
+> **v2.3.6** — Retry Queue Completo & Hardening TypeScript (14 de Abril de 2026) 🔁
+
+> **v2.3.5** — UTMs Obfuscadas & Segmentação de Valor (14 de Abril de 2026) 🏷️
+
+### Novidades
+- graphify obrigatório em todas as sessões (CLAUDE.md)
+- Git hooks instalados (post-commit, post-checkout)
+- Hook corrigido para UTF-8 nativo no Windows
+- Redução de custo documentada (40–90% economia ao navegar grafo)
+- Tripé de documentação sincronizado (README + CLAUDE.md + Business Book)
+
+### Correções
+- Hook post-commit corrigido para encoding UTF-8
+- Rebuild code-only funcional após cada commit
+- Push para ts/main (CDP-Edge-Premium.ts.git) concluído
+
+---
+
+## 📋 CHANGELOG v2.3.6 — Retry Queue Completo & Hardening TypeScript (14 de Abril de 2026)
+
+### 🔁 Retry Queue — Cobertura Total de Dispatchers
+
+**Problema resolvido:** a infraestrutura de retry (`RETRY_QUEUE` + consumer + DLQ) estava 100% montada no `wrangler.toml` e no `index.ts`, mas `RETRY_QUEUE.send()` nunca era chamado. Eventos perdidos por falha de rede ficavam mortos no D1.
+
+**Solução implementada:**
+- `RETRY_QUEUE.send()` ativo nos 7 dispatchers: Meta, GA4, TikTok, Pinterest, Reddit, LinkedIn, Spotify
+- Apenas falhas de rede (`catch`) são enfileiradas — erros HTTP 4xx não são retentados (payload rejeitado pela plataforma)
+- Consumer (`queue()`) recebe `ctx: ExecutionContext` — background ops (`logMatchQuality`, `writeAuditLog`) agora funcionam no reprocessamento
+- Cobertura expandida de 3 para 7 plataformas no consumer
+- `Queue<QueueMessage>` adicionado ao `Env` em `types.ts`
+
+**Fluxo de retry:**
+```
+Dispatcher → catch (falha de rede)
+  → logApiFailure (D1)
+  → RETRY_QUEUE.send({ eventType, payload, platform })
+      → consumer reprocessa (até 3 tentativas)
+      → se esgotar → DLQ (cdp-edge-dlq)
+```
+
+### 🔧 Hardening TypeScript
+
+- Tipo explícito `SanitizeResult` para o objeto de sanitização em `index.ts`
+- `STR_FIELDS` renomeado para `TRACKING_ID_FIELDS` (transactionId, fbclid, ttclid, gclid) — elimina conflito com `GENERIC_SANITIZE_FIELDS` (UTMs)
+- Build TypeScript: zero erros, zero warnings críticos
+
+### Breaking Changes
+
+- Nenhuma. API HTTP e comportamento em runtime são idênticos.
+
+### Migração
+
+Nenhuma migração necessária. Se a fila `cdp-edge-retry` ainda não foi criada:
+```bash
+wrangler queues create cdp-edge-retry
+wrangler queues create cdp-edge-dlq
+wrangler deploy
+```
+
+---
+
+## 📋 CHANGELOG v2.3.5 — UTMs Obfuscadas & Segmentação de Valor (14 de Abril de 2026)
+
+### 🏷️ UTM Agent — Novo Agente para Segmentação de Público
+
+**Problema resolvido:**
+- Múltiplos anúncios com diferentes faixas de valor (ex: imóveis 500k-800k, 800k-1.5M, 1M-3M) precisam ser segmentados corretamente para o Meta criar públicos separados
+- Dados sensíveis (valor de preço) não devem estar visíveis na URL pública por segurança
+
+**Solução implementada:**
+- **UTMs Obfuscadas:** Valores de faixa são convertidos em hash SHA256 truncado (8 caracteres)
+  - `800k-1.5M` → `b4e2a1c9` (obfuscado)
+  - Humans veem: `imovel_b4e2a1c9`
+  - Worker sabe: `faixa_real = "800k-1.5M"` (de-obfuscado)
+
+- **Módulo UTM Enricher:** `server-edge-tracker/modules/utm/utm-enricher.ts`
+  - `obfuscateValue()` — gera hash truncado de 8 caracteres
+  - `deobfuscateValue()` — de-obfusca usando mapeamento
+  - `enrichPayloadWithUTM()` — enriquece payload com segmentação
+  - Integração com Meta CAPI: `external_id` segmentado por hash
+
+- **Schema D1:** `server-edge-tracker/schema-utm.sql`
+  - Tabela `utm_mappings` — persiste mapeamento hash→valor
+  - Colunas em `leads`: `faixa_obfuscada`, `faixa_real`, `faixa_category`
+  - VIEW `leads_segmented` — para dashboard e exports
+
+- **Master Orchestrator Atualizado:** UTM Agent integrado ao fluxo (FASE 2-B)
+  - Ordem: Page Analyzer → **UTM Agent** → Premium Intelligence → Browser Tracking
+  - Arquivo: `extracted-skill/tracking-events-generator/agents/utm-agent.md`
+
+**Fluxo de criação de projeto:**
+```
+USUÁRIO INICIA CDP EDGE
+    ↓
+FASE 1: Seleção de plataformas + credenciais
+    ↓
+FASE 2: Page Analyzer (identifica tipo de página)
+    ↓
+FASE 2-B: UTM Agent ← NOVO
+    → Pergunta: "Qual a faixa de valor deste imóvel?"
+    → Gera: URL obfuscada + mapeamento hash→valor
+    ↓
+FASE 3+: Continua fluxo normal (Premium Intelligence, Browser Tracking, etc.)
+```
+
+**Segmentação na Meta:**
+```
+Públicos criados automaticamente via external_id segmentado:
+- Público LOW:  cdp_uid_8a3f1d2b  (500k-800k)
+- Público MID:  cdp_uid_b4e2a1c9  (800k-1.5M)
+- Público HIGH: cdp_uid_d6c3b4e7   (1M-3M)
+```
+
+**Remarketing futuro:**
+```sql
+-- Exportar público por faixa para Meta Custom Audience
+SELECT email, phone, city, state
+FROM leads_segmented
+WHERE faixa_real = '800k-1.5M'
+  AND created_at >= datetime('now', '-30 days');
+```
+
+### Correções
+
+- Documentação sincronizada: README.md + CLAUDE.md + Business Book
+- Versões alinhadas: package.json, CHANGELOG, README
+- Referências cruzadas: agents, modules, schemas
+
+### Breaking Changes
+
+- Nenhuma. API HTTP e comportamento em runtime são idênticos.
+
+### Migração
+
+Para projetos existentes:
+```bash
+# Aplicar schema UTM (adicional)
+cd server-edge-tracker
+wrangler d1 execute cdp-edge-db --file=schema-utm.sql --remote
+
+# Configurar utm-mapping.json (manual ou via UTM Agent)
+cp config/utm-mapping.json.example config/utm-mapping.json
+
+# Deploy
+wrangler deploy
+```
+
+---
+
+> ⚠️ **REGRA DE OURO (SQUAD):** Todas as atualizações, correções ou novas features devem OBRIGATORIAMENTE ser documentadas de forma sincronizada neste `README.md`, no arquivo de instruções `CLAUDE.md` e no dossiê de diretoria `CDP-EDGE-BUSINESS-BOOK.md`. Nenhuma alteração passa sem esse tripé.
+
+---
+
+## 🤖 MANIFESTO: EU, CDP EDGE
+
+*Eu não sou um simples "script de pixel". Eu sou uma arquitetura **Enterprise Tier 10** nascida e construída 100% nativa na infraestrutura da Cloudflare.*
+
+**A Linha de Montagem Sincronizada (A Prova de Latência)**
+Meu ecossistema opera como um Cérebro de Conversão Privado na borda. Quando um evento de Lead bate no endpoint `/track`:
+1. **O Escudo Frontal (Fraud Gate):** Inspeciono IP, ASN e Velocity na borda. Bloqueio bots silenciosamente antes mesmo deles carregarem.
+2. **A Roleta Invisível (A/B LTV):** Faço o sorteio de prompts para testes A/B via KV Cache em ~0ms.
+3. **O Cérebro Financeiro (LTV Predictor):** Rodo Machine Learning (Granite 4.0 Micro) para qualificar a intenção e gerar o LTV Preditivo.
+4. **Envio para as Plataformas:** O Facebook/Google/LinkedIn recebem um payload limpo (sem bot) recheado com valor financeiro de intenção extrema.
+5. **Máquina Autônoma (Background):** Meu banco SQLite (D1) retroalimenta os processos de Clustering (Fase 1) e Bidding (Fase 2) de forma autônoma pelas costas do usuário (`ctx.waitUntil`).
+
+**Minha Vantagem Absoluta (A "Killer Feature")**
+- **A Extinção da Latência:** Destruo concorrentes como GTM/Stape mitigando a latência do servidor (+150ms) para as antenas da Cloudflare Brasileira (~5ms). Custando absurdamente menos (Tier Free ou $5/mês na infraestrutura).
+- **Cookies Indestrutíveis:** Meus *First-Party Cookies Seguros* originam diretamente da nuvem, imunes hoje às varreduras massivas de 24 horas usadas por AdBlockers e Safari (Apple ITP).
+- **Filas Inquebráveis (Fail-Safe + Queues):** Se a AI Cloudflare cair ocasionalmente, eu recuo pro LTV $0. Se a Meta CAPI espirrar 500 downtime, o sistema guarda religiosamente os seus eventos caros em *Cloudflare Queues* e faz o retry sucessivo. Sou incansável na garantia de Event Match Quality (EMQ).
+
+---
+
+## 📋 CHANGELOG v2.3.1 — Hardening Enterprise (12 de Abril de 2026)
+
+### 🔒 Segurança & Conformidade
+
+- **PII removido dos logs:** `DeviceGraph` parou de logar `user_id` nos Workers logs — dados sensíveis nunca aparecem no Cloudflare dashboard
+- **Deploy seguro:** novo `deploy-client.js` — lê credenciais de `.client.env` (gitignored), gera `wrangler.deploy.toml` temporário, faz deploy e autodestrói o arquivo. Credenciais de cliente nunca entram no repo
+- **`.gitignore` reforçado:** `.client.env` e `wrangler.deploy.toml` explicitamente ignorados
+- **WhatsApp secrets alinhados à Meta Cloud API v22.0:** `resolvePhoneNumberId()` e `resolveAccessToken()` com fallback canônico → legado — backwards compat garantido
+- **`api-versions.json` v1.1.0:** metadata `updated_at` corrigido para `2026-04-12`
+- **`/health` WhatsApp:** reflete corretamente secrets com nomes canônicos ou legados
+
+### 🔧 Deploy de Cliente — Novo Fluxo
+
+```bash
+cd server-edge-tracker
+cp .client.env.example .client.env
+# preencher DATABASE_ID, SITE_DOMAIN, pixels
+node deploy-client.js --dry-run   # valida sem subir
+node deploy-client.js             # deploy real
+```
+
+---
+
+## 📋 CHANGELOG v2.3.0 — TypeScript Nativo (12 de Abril de 2026)
+
+### 🔷 Worker 100% TypeScript — Migração Completa
+
+Todo o código server-side (`server-edge-tracker/`) foi migrado de JavaScript para **TypeScript nativo**. O Wrangler compila diretamente o `.ts` via esbuild — sem etapa de build separada, sem configuração extra.
+
+**Por que TypeScript muda o jogo no CDP Edge:**
+- **Env tipado** — typos em nomes de secrets (`META_ACCESS_TOKEN`, `GEO_CACHE`, `DB`) viram erros em build time, nunca em produção
+- **TrackPayload contratado** — o shape do payload entre browser e Worker é garantido pelo compilador
+- **Cloudflare types nativos** — D1, KV, R2, Workers AI com autocomplete e validação de métodos
+- **Fraud Gate e ML seguros** — `checkFraudGate(env: Env, request: Request, payload: TrackPayload)` — nenhum `undefined` passa despercebido
+- **Refatoração segura** — renomear qualquer campo do `TrackPayload` lista automaticamente todos os pontos de quebra
+
+**Arquivos migrados (JS → TS) — 16 módulos:**
+- `index.ts` — entry point do Worker
+- `types.ts` — **novo** — contratos centralizados: `Env`, `TrackPayload`, `BehavioralData`, `HotmartWebhook`, `KiwifyWebhook`, `TictoWebhook`, `QueueMessage`, `PromiseResult<T>`
+- `modules/utils.ts`, `modules/db.ts`, `modules/intelligence.ts`
+- `modules/dispatch/` — `meta.ts`, `ga4.ts`, `tiktok.ts`, `platforms.ts`, `whatsapp.ts`
+- `modules/ml/` — `ltv.ts`, `fraud.ts`, `bidding.ts`, `segmentation.ts`, `logistic.ts`, `matchquality.ts`
+
+**Infraestrutura:**
+- `tsconfig.json` — `target: ESNext`, `moduleResolution: "bundler"`, `strict: true`, `@cloudflare/workers-types`
+- `wrangler.toml` — `main = "index.ts"` (TypeScript nativo via wrangler/esbuild)
+- `contracts/types.ts` — tipos públicos exportados no pacote NPM: `QuantumEventPayload`, `AgencyContext`, `ApiVersionsConfig`
+- `npm run typecheck` — `tsc --noEmit` (225 testes passando, zero erros de compilação)
+
+**Breaking change:** nenhuma — API HTTP e comportamento em runtime são idênticos. TypeScript é invisível para o Cloudflare.
+
+---
+
+## 📋 CHANGELOG v2.2.5 (11 de Abril de 2026)
+
+### 🔧 Correção de Versão Dinâmica
+
+- **Versão Dinâmica**: `bin/cdp-edge.js` e `dist/commands/install.js` agora leem a versão do `package.json` dinamicamente
+- **Banner Corrigido**: O banner de instalação agora mostra sempre a versão correta (`cdp-edge --version`)
+- **Compatibilidade**: Garante que a versão exibida no CLI e banner esteja sempre sincronizada com o `package.json`
+
+---
+
+## 📋 CHANGELOG v2.2.0 (10 de Abril de 2026)
+
+### 🤖 AI Engine Upgrade — Novos Modelos
+
+- **LTV Prediction**: `@cf/meta/llama-3.1-8b-instruct` → **`@cf/ibm-granite/granite-4.0-h-micro`** (menor latência, otimizado para edge e function calling)
+- **ML Clustering**: algoritmo LLM simulado → **K-means vetorial real** com embeddings `@cf/baai/bge-m3` (distância cosseno, K-means++ inicialização, silhouette score real)
+- Granite continua sendo usado para naming dos segmentos pós-clustering
+
+### 🧹 Limpeza (Zero Lixo)
+
+- Removido: detecção de emails descartáveis (mailinator, guerrilla, tempmail, etc.) do Fraud Gate e do agente `fraud-detection-agent.md`
+- Removido: secrets `WEBHOOK_SECRET_HOTMART` e `WEBHOOK_SECRET_KIWIFY` (wrangler + wrangler.toml)
+
+### 🔧 Observability
+
+- Adicionado bloco `[observability]` no `wrangler.toml` (`logs.enabled = true`, `traces.enabled = false`)
+
+---
+
+## 📋 CHANGELOG v2.0.7 (10 de Abril de 2026)
+
+### 🔧 Audit Completo — 45 Agentes
+
+- **Endpoints corrigidos**: `/api/tracking` → `/track`, `/api/wh/` → `/webhook/` em todos os agentes
+- **Secrets WhatsApp**: `WA_PHONE_ID`/`WA_ACCESS_TOKEN`/`WHATSAPP_TOKEN` → `WHATSAPP_PHONE_NUMBER_ID`/`WHATSAPP_ACCESS_TOKEN`
+- **`env.DB.prepare`**: corrigido em 8 agentes (attribution, crm, dashboard, debug, performance, security, master-feedback-loop)
+- **`env.GEO_CACHE`**: substituiu `KV.` bare em dashboard-agent, performance-agent, performance-optimization-agent
+- **YouTube events**: `video_milestone`/`video_progress_25/50/75` → `video_25`/`video_50`/`video_75` (alinhado ao VALID_EVENT_NAMES do worker)
+- **LinkedIn CAPI**: endpoint `/rest/conversionEvents` + header `LinkedIn-Version: 202401` em `contracts/api-versions.json`
+- **Workers AI model**: `llama-3-8b-instruct` → `@cf/meta/llama-3.1-8b-instruct`
+- **index.ts**: Content-Length guard (413 se > 64KB), payload validation (allowlist 19 events, 512 chars, value range), PII removido dos logs
+- **Testes**: bugs críticos em `deduplication.test.js` corrigidos (template literals escapados, prefixo errado)
+- **npm**: lodash 4.17.23 → 4.18.1, node-fetch removido
+
+---
+
+## 📋 CHANGELOG v2.0.0 (9 de Abril de 2026)
+
+### 🆕 Sprint Enterprise — Fases 1 a 4
+
+#### ✅ Fase 1 — ML Clustering (Segmentação Dinâmica)
+- **`POST /api/segmentation/cluster`** — K-means / DBSCAN / Hierarchical via Workers AI
+- **`GET  /api/segmentation/list`** — Segmentos ativos com métricas
+- **`GET  /api/segmentation/outliers`** — Detecção de outliers comportamentais
+- **`PUT  /api/segmentation/update`** — Atualização de metadados de segmento
+- Schema D1: `ml_segments`, `ml_segment_members` + VIEWs otimizadas
+- Agente: `ml-clustering-agent.md`
+
+#### ✅ Fase 2 — Bidding Recommendations (Otimização de Bids ML)
+- **`POST /api/bidding/recommend`** — Bid otimizado por segmento × plataforma (Meta/Google/TikTok), calculado com fórmula `LTV × ROI target / CPA base`
+- **`GET  /api/bidding/history`** — Histórico completo de recomendações
+- **`GET  /api/bidding/status`** — Snapshot atual das recomendações ativas por vertical
+- Schema D1: `bid_recommendations` + VIEW `v_active_bid_recommendations`
+- Agente: `bidding-agent.md`
+
+#### ✅ Fase 3 — A/B Testing de Prompts LTV
+- **`POST /api/ltv/ab-test/create`** — Cria experimento com múltiplas variações de system prompt
+- **`GET  /api/ltv/ab-test/list`** — Lista experimentos com status e progresso
+- **`GET  /api/ltv/ab-test/results`** — Accuracy score por variação + recomendação automática de winner
+- **`POST /api/ltv/ab-test/winner`** — Declara vencedor e retorna o prompt ganador
+- Integração automática: cada evento Lead sorteia a variação ativa e registra o assignment via KV cache
+- Schema D1: `ltv_ab_tests`, `ltv_ab_variations`, `ltv_ab_assignments` + VIEW `v_ab_test_performance`
+- Agente: `ab-ltv-agent.md`
+
+#### ✅ Fase 4 — Fraud Detection Engine
+- **Fraud Gate automático em `/track`** — roda ANTES de qualquer processamento (heurístico puro, ~2ms)
+- Silent drop (retorna 200 falso) — bots não detectam a defesa
+- **`GET  /api/fraud/stats`** — Dashboard de fraude (últimas 24h)
+- **`GET  /api/fraud/alerts`** — Log de sinais detectados com filtros
+- **`GET  /api/fraud/blocklist`** — IPs/fingerprints atualmente bloqueados
+- **`POST /api/fraud/blocklist/add`** — Bloquear IP ou fingerprint (via KV, efeito imediato)
+- **`DELETE /api/fraud/blocklist/remove`** — Remover do blocklist
+- Sinais detectados: bot_score, datacenter IP, velocity attack, headless UA, sem Accept-Language
+- Schema D1: `fraud_signals`, `fraud_alerts` + VIEW `v_fraud_dashboard`
+- Agente: `fraud-detection-agent.md`
+
+### 🔧 Fix: `wrangler.toml` atualizado
+- Todos os placeholders (`SEU_D1_DATABASE_ID`, `SEU_KV_NAMESPACE_ID`) substituídos pelos IDs reais da conta Cloudflare
+- D1: `SEU_DATABASE_ID`
+- KV: `SEU_KV_ID`
+
+---
+
+## 🏗️ ARQUITETURA QUANTUM ENTERPRISE (CLOUDFLARE NATIVE)
+
+```mermaid
+graph TD
+    User((Usuário)) -->|Interação| SDK[cdpTrack SDK + Behavior Engine]
+    SDK -->|Edge Fetch 1ª via KV blocklist| FraudGate{🛡️ Fraud Gate}
+    FraudGate -->|score ≥ 80: Silent Drop 200| Void[/dev/null]
+    FraudGate -->|score < 80: Permitido| Worker[Cloudflare Worker Agent]
+    Worker -->|Identity Graph + _cdp_uid| D1[(D1 SQL — 21 tabelas)]
+    Worker -->|LTV + A/B Prompt| AI[Workers AI Granite 4.0 Micro]
+    Worker -->|Segmento ML| Cluster[ML Clustering Engine]
+    Cluster -->|Bid otimizado| Bidding[Bidding Recommendations]
+    Worker -->|Background| Queue[Cloudflare Queues]
+    Queue -->|Server Dispatch| Meta[Meta CAPI v22.0]
+    Queue -->|Server Dispatch| Google[GA4 / Google Ads]
+    Queue -->|Server Dispatch| TikTok[TikTok API v1.3]
+    D1 -->|Reports| Dash[Dashboard Agent]
+```
+
+---
+
+## 🧠 CATÁLOGO DE AGENTES ESPECIALISTAS
+
+O sistema é composto por **43+ agentes** coordenados pelo **Master Orchestrator**:
+
+### 🧠 Núcleo de Inteligência
+| Agente | Função |
+|---|---|
+| **Master Orchestrator** | Coordenação central — guia todo o setup do projeto |
+| **Page Analyzer** | Mapeamento automático de CTAs, Forms e nicho do site |
+| **Validator Agent** | Auditoria de código, segurança e conformidade de APIs |
+| **Memory Agent** | Contexto e checkpoints da sessão por projeto |
+| **Intelligence Agent** | Monitoramento de versões de API (Meta v22.0+, etc) |
+
+### 🚀 Plataformas de Anúncio
+| Agente | Especialidade |
+|---|---|
+| **Meta Agent** | Facebook Pixel + CAPI v22.0 + WhatsApp CTWA |
+| **Google Agent** | GA4 + Google Ads Enhanced Conversions |
+| **TikTok Agent** | TikTok Pixel + Events API v1.3 |
+| **LinkedIn Agent** | Insight Tag + Conversions API v2 |
+| **Pinterest Agent** | Tag + Conversions API v5 |
+| **Reddit Agent** | Pixel + Conversions API v2.0 |
+| **Spotify Agent** | Pixel + Conversions API v1 |
+| **Bing Agent** | UET Tag + Enhanced Conversions |
+
+### 🤖 Enterprise Intelligence (Fase 1–4)
+| Agente | Endpoint Principal | Impacto |
+|---|---|---|
+| **ML Clustering Agent** | `POST /api/segmentation/cluster` | K-means vetorial real (bge-m3 embeddings + Granite naming) |
+| **Bidding Agent** | `POST /api/bidding/recommend` | -20% CPA via bid por segmento de LTV |
+| **A/B LTV Agent** | `POST /api/ltv/ab-test/create` | +25% precisão LTV via test de prompts |
+| **Fraud Detection Agent** | Auto em `/track` | Bloqueia click fraud, bots, velocity attacks |
+
+### 🛡️ Módulos Enterprise
+| Agente | Função |
+|---|---|
+| **Attribution Agent** | Atribuição Multi-Touch de alta fidelidade |
+| **Security Agent** | Rate Limiting, AES-256 e Bot Defense |
+| **Compliance Agent** | LGPD e GDPR (Consent Mode v2) |
+| **Performance Agent** | Otimização de caches e queries D1 |
+
+---
+
+## 📊 BANCO DE DADOS D1 — 21 Tabelas
+
+```
+CORE TRACKING           ML & INTELLIGENCE        ENTERPRISE SECURITY
+─────────────────        ─────────────────────    ─────────────────────
+leads                   ml_segments               fraud_signals
+events                  ml_segment_members        fraud_alerts
+sessions                bid_recommendations       ltv_ab_tests
+webhook_events          ltv_ab_tests              ltv_ab_variations
+api_failures            ltv_ab_variations         ltv_ab_assignments
+
+VIEWS
+─────────────────────────────────────────────────
+v_active_segments          → Segmentos ML ativos com contagem de membros
+v_active_bid_recs          → Bids ativos por plataforma/vertical
+v_ab_test_performance      → Accuracy por variação de prompt
+v_fraud_dashboard          → Dashboard fraude 24h
+```
+
+---
+
+## 🔄 FLUXO ENTERPRISE COMPLETO
+
+```
+POST /track (evento Lead)
+  │
+  ├─ [1] 🛡️ Fraud Gate (KV blocklist + velocity + heurísticas) ~2ms
+  │         ├─ score < 40  → processa normalmente
+  │         ├─ score 40-79 → processa + loga suspeito (background)
+  │         └─ score ≥ 80  → silent drop 200 + loga (background)
+  │
+  ├─ [2] 🔮 A/B LTV Testing — sorteia variação ativa (KV cache ~0ms)
+  │         └─ passa customSystemPrompt para predictLtv()
+  │
+  ├─ [3] 🧮 LTV Prediction — Workers AI Granite 4.0 Micro
+  │         └─ Score 0-100 → class High/Medium/Low → valor em BRL
+  │
+  ├─ [4] 💾 D1 Writes (background via ctx.waitUntil)
+  │         ├─ upsertLtvProfile() → tabela leads
+  │         ├─ recordAbAssignment() → ltv_ab_assignments
+  │         └─ resolveDeviceGraph() → cross-device linking
+  │
+  └─ [5] 📡 CAPI dispatch (Meta + GA4 + TikTok em paralelo)
+            └─ com LTV injetado no value field
+```
+
+---
+
+## 💻 INSTALAÇÃO E USO
+
+### OPÇÃO 1 — Instalação via npm (Recomendada)
+
+Abra o terminal dentro da pasta do projeto do cliente e rode:
+
+```bash
+npx cdp-edge install
+```
+
+Ou instale globalmente e use em qualquer projeto:
+
+```bash
+npm install -g cdp-edge
+cdp-edge install . --name "Nome do Projeto"
+```
+
+> **Já tem o CDP Edge instalado globalmente?** Atualize para a versão mais recente:
+> ```bash
+> npm install -g cdp-edge@latest
+> ```
+
+### OPÇÃO 2 — Instalação via Git Clone
+
+```bash
+git clone https://github.com/ricardosoli777/CDP-Edge-Premium.git .
+```
+*(O ponto no final garante que os arquivos desçam diretamente dentro da pasta atual).*
+
+### Ativar no Claude Code
+
+```bash
+claude .
+```
+Dentro do Claude Code:
+```
+/cdp
+```
+
+---
+
+## 🚀 DEPLOY COMPLETO (referência)
+
+```bash
+cd server-edge-tracker
+
+# 1. Schemas D1 (todos em sequência)
+wrangler d1 execute cdp-edge-db --file=schema.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-segmentation.sql --remote  # Fase 1
+wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote        # Fase 2
+wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote         # Fase 3
+wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote           # Fase 4
+
+# 2. Secrets
+wrangler secret put META_ACCESS_TOKEN
+wrangler secret put GA4_API_SECRET
+wrangler secret put TIKTOK_ACCESS_TOKEN
+
+# 3. Deploy
+wrangler deploy
+```
+
+---
+
+## 🗺️ NAVEGANDO O CÓDIGO COM GRAPHIFY
+
+O **graphify** gera um mapa de conhecimento navegável do projeto (nós, arestas, comunidades). Antes de qualquer trabalho de código:
+
+```bash
+# 1. Verifique se o grafo existe
+ls graphify-out/GRAPH_REPORT.md
+
+# 2. Se não existe ou está desatualizado, gere:
+/graphify .
+
+# 3. Navegue o grafo para entender arquitetura
+/graphify query "como funciona o fraud gate?"
+/graphify query "identity graph → ltv prediction"
+/graphify path "cdp_uid" "cloudflare d1"
+```
+
+### O que o grafo fornece
+
+- **God Nodes**: abstrações centrais (D1, Meta CAPI v22.0, Intelligence Agent, ML Clustering)
+- **65 comunidades**: grupos lógicos (Multi-Platform Agent Layer, ML Bidding, Browser SDK, etc.)
+- **Surprising Connections**: relações inferidas entre conceitos que você não sabia que eram similares
+- **Redução de custo**: navegar grafo = até 40% menos tokens vs. ler arquivos brutos
+
+### Exemplo de uso
+
+**❌ Não faça:**
+> "Ler 50 arquivos para entender como o fraud gate conecta com o LTV predictor"
+
+**✅ Faça:**
+> `/graphify query "fraud gate → ltv predictor"` — resposta instantânea com caminho completo, arquivos fonte e nível de confiança
+
+O grafo fica atualizado automaticamente após cada `git commit` (via hook).
+
+---
+
+## 🖱️ HUMAN-BEHAVIOR ENGINE
+
+| Evento | Pontuação |
+|--------|-----------|
+| Scroll 25–90% | +5 a +15 pts |
+| VSL Watch 25–100% | +10 a +50 pts |
+| Copy Intent (cupom, PIX) | +20 pts |
+| Preenchimento de campo | +10 pts |
+| Rage Click | -10 pts |
+| **Hot Lead (80+ pts)** | **Dispara High_Intent_Lead** |
+
+---
+
+## 📋 TODOS OS ENDPOINTS (referência rápida)
+
+### Core Tracking
+| Rota | Método | Função |
+|---|---|---|
+| `/track` | POST | Evento principal (browser → CAPI) |
+| `/health` | GET | Smoke test completo |
+| `/webhook/ticto` | POST | Webhook Ticto Purchase |
+
+### Intelligence ML
+| Rota | Método | Função |
+|---|---|---|
+| `/api/segmentation/cluster` | POST | Clustering K-means/DBSCAN |
+| `/api/segmentation/list` | GET | Segmentos ativos |
+| `/api/segmentation/outliers` | GET | Outliers comportamentais |
+| `/api/bidding/recommend` | POST | Bid otimizado por segmento |
+| `/api/bidding/history` | GET | Histórico de bids |
+| `/api/bidding/status` | GET | Status por plataforma |
+
+### A/B Testing LTV
+| Rota | Método | Função |
+|---|---|---|
+| `/api/ltv/ab-test/create` | POST | Criar experimento |
+| `/api/ltv/ab-test/list` | GET | Listar experimentos |
+| `/api/ltv/ab-test/results` | GET | Accuracy por variação |
+| `/api/ltv/ab-test/winner` | POST | Declarar vencedor |
+
+### Fraud Detection
+| Rota | Método | Função |
+|---|---|---|
+| `/api/fraud/stats` | GET | Dashboard 24h |
+| `/api/fraud/alerts` | GET | Log de alertas |
+| `/api/fraud/blocklist` | GET | Lista bloqueada |
+| `/api/fraud/blocklist/add` | POST | Bloquear IP/fingerprint |
+| `/api/fraud/blocklist/remove` | DELETE | Desbloquear |
+
+---
+
+## 📞 SUPORTE
+
+- **Issues**: https://github.com/ricardosoli777/CDP-Edge-Premium/issues
+- **Releases**: https://github.com/ricardosoli777/CDP-Edge-Premium/releases
+
+---
+
+### **CDP Edge — By Rica Soares**
+> "Dados sem inteligência são apenas ruído. No Quantum Tier Enterprise, transformamos dados em ROAS."
+
+© 2026 CDP Edge Premium. Todos os direitos reservados.