cdp-edge 2.3.8 → 2.3.9

package/extracted-skill/tracking-events-generator/agents/utm-agent.md

@@ -1,61 +1,222 @@
-# UTM Agent — Agente de Geração de UTMs Obfuscadas
+# UTM Agent — CDP Edge
 
-## Role
-Especialista em gerar estruturas de UTM parametrizadas para segmentação de público, com valores **obfuscados/racheados** para proteção de dados sensíveis na URL.
+**Papel:** Gerador automático de UTMs completas — usa o contexto já coletado pelo CDP Edge para produzir cada string de UTM pronta, por plataforma e por formato de anúncio. O cliente copia e cola.
 
-## When This Agent Runs
-- Após o **Page Analyzer** identificar o tipo de página/produto
-- Antes de gerar os parâmetros de tracking no SDK
-- Quando o usuário precisa configurar campanhas com categorização de valor
+---
 
-## Inputs from Page Analyzer
-```json
-{
-  "page_type": "produto",
-  "product_category": "imovel" | "automotivo" | "curso" | "outros",
-  "url": "https://lançamentosabc.com.br/apartamento-123",
-  "existing_utms": {} // se houver
-}
+## Princípio Fundamental
+
+O CDP Edge já sabe tudo que precisa para gerar as UTMs. Nenhuma informação adicional do cliente é necessária além do que já foi coletado nas fases anteriores:
+
+| O que o CDP Edge já sabe | De onde vem |
+|---|---|
+| Quais plataformas serão usadas | FASE 0-B (seleção de plataformas) |
+| Se tem vídeo no funil | Page Analyzer (detecta VSL, videos, players) |
+| Se tem quiz | Lead Scoring Agent (configurado na FASE 6) |
+| Se tem formulário / landing page | Page Analyzer (detecta forms, CTAs) |
+| Se tem Click-to-WhatsApp | Meta selecionado + CTWA habilitado automaticamente |
+| Nicho e categoria do produto | Page Analyzer |
+| Faixa de valor do produto | Pergunta feita pelo próprio UTM Agent na FASE 2-B |
+
+**Com tudo isso, o UTM Agent gera uma tabela completa de UTMs prontas — o cliente não precisa inventar nenhum parâmetro.**
+
+---
+
+## O Que São as 5 Dimensões
+
+```
+utm_source   → PLATAFORMA    — de qual rede de anúncio veio o lead
+utm_medium   → FORMATO       — qual tipo de anúncio foi usado
+utm_campaign → PRODUTO/FAIXA — qual produto e faixa de valor (obfuscado)
+utm_content  → ORIGEM        — qual criativo/página/funil gerou o lead
+utm_term     → QUALIFICAÇÃO  — classificação do quiz (preenchida pelo Worker)
 ```
 
-## Workflow
+`utm_term` é o único campo que o cliente **nunca** configura nos anúncios — o Worker injeta automaticamente após o Quiz Scoring Engine classificar o lead.
 
-### 1. Identificar necessidade de UTM
-- Se `product_category` existir, perguntar ao usuário sobre categorização de valor
-- Exemplos de perguntas:
-  - Para **imóveis**: "Qual a faixa de preço deste imóvel? Ex: 500k-800k, 800k-1.5M, 1M-3M"
-  - Para **automotivos**: "Qual a faixa de valor? Ex: 50k-100k, 100k-200k, 200k-500k"
-  - Para **cursos**: "Qual o nível/preço? Ex: básico-49, premium-199, pro-999"
+---
 
-### 2. Gerar estrutura de UTM obfuscada
+## Quando Este Agente Roda
 
-Para cada categoria informada pelo usuário, gerar:
+Após o **Lead Scoring Agent** (se quiz habilitado) e antes do **Browser Tracking Agent**.
 
-```json
-{
-  "utm_strategy": {
-    "source": "facebook", // padrão, configurável
-    "medium": "cpc",      // padrão, configurável
-    "campaign": {
-      "pattern": "{product_category}_{obfuscated_range}",
-      "example": "imovel_8a3f1d2b"
-    },
-    "content": {
-      "pattern": "product_{obfuscated_id}",
-      "example": "product_9c4e2a1f"
-    },
-    "faixa_obfuscada": {
-      "original": "700k-1M",
-      "obfuscated": "8a3f1d2b",
-      "hash_method": "sha256",
-      "salt": "CDP_EDGE_UTM_SALT"
-    }
-  }
-}
+Inputs que o agente já possui ao ser chamado:
+- `SELECTED_PLATFORMS` — plataformas selecionadas na FASE 0-B
+- `page_analysis` — saída do Page Analyzer (tem video? tem quiz? tem form? tem CTWA?)
+- `lead_scoring_config` — quiz configurado? quais perguntas? qual nome do quiz?
+- `utm_value_range` — faixa de valor do produto (perguntada na FASE 2-B)
+- `product_category` — nicho detectado pelo Page Analyzer
+
+---
+
+## Processo de Geração
+
+### PASSO 1 — Mapear o que foi implementado no funil
+
+O agente lê os outputs das fases anteriores e monta um inventário de origens:
+
+```
+INVENTÁRIO DE ORIGENS (montado automaticamente):
+
+Plataformas ativas:     [facebook, google, tiktok]
+Formatos por plataforma:
+  facebook → [reels, stories, video, cpc, ctwa]  ← detectado: tem VSL + tem CTWA
+  google   → [cpc]                                ← search only
+  tiktok   → [video]                              ← video in-feed
+Tipos de página:
+  → quiz habilitado    → utm_content inclui quiz_{nome_quiz}
+  → landing com VSL   → utm_content inclui video_{tipo}
+  → formulário direto → utm_content inclui landing_principal
+  → CTWA ativo        → utm_content inclui ctwa_direto
+```
+
+### PASSO 2 — Gerar o valor obfuscado da campanha
+
+Com a faixa de valor informada (ex: "700k-1M"):
+```
+SHA256("700k-1M" + "CDP_EDGE_UTM_SALT") → primeiros 8 chars → "8a3f1d2b"
+utm_campaign = imovel_8a3f1d2b
 ```
 
-### 3. Mapeamento reversível (para o Worker)
-Gerar o arquivo `utm-mapping.json` com:
+Registrar no `utm-mapping.json` para de-obfuscação no Worker.
+
+### PASSO 3 — Gerar a tabela completa de UTMs prontas
+
+Para CADA combinação de plataforma × formato × origem que existe no funil:
+
+---
+
+## Saída — Tabela de UTMs Prontas para o Cliente
+
+O agente entrega uma tabela assim, gerada automaticamente com base no que foi implementado:
+
+```markdown
+# UTMs do Projeto [NOME DO CLIENTE]
+# Geradas pelo CDP Edge — copie e cole em cada campanha
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## META ADS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Campanhas que levam ao QUIZ DE QUALIFICAÇÃO
+Use quando o anúncio leva para a página do quiz antes do formulário.
+
+Reels:
+utm_source=facebook&utm_medium=reels&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+Stories:
+utm_source=facebook&utm_medium=stories&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+Vídeo in-feed:
+utm_source=facebook&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+Feed (imagem/carrossel):
+utm_source=facebook&utm_medium=cpc&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+### Campanhas que levam ao VÍDEO DE VENDAS (VSL)
+Use quando o anúncio leva direto para a landing page com vídeo.
+
+Reels:
+utm_source=facebook&utm_medium=reels&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+Stories:
+utm_source=facebook&utm_medium=stories&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+Vídeo in-feed:
+utm_source=facebook&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+### Campanhas Click-to-WhatsApp (CTWA)
+Use quando o anúncio abre diretamente o WhatsApp.
+
+utm_source=whatsapp&utm_medium=ctwa&utm_campaign=imovel_8a3f1d2b&utm_content=ctwa_direto
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## GOOGLE ADS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Search (palavras-chave)
+utm_source=google&utm_medium=cpc&utm_campaign=imovel_8a3f1d2b&utm_content=landing_principal
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## TIKTOK ADS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Vídeo In-Feed (quiz)
+utm_source=tiktok&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+### Vídeo In-Feed (VSL)
+utm_source=tiktok&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## OBSERVAÇÕES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+utm_term NÃO é configurado nos anúncios.
+O servidor preenche automaticamente após o quiz:
+  comprador / interessado / curioso / perdido
+
+O valor real da campanha (700k-1M) está protegido.
+Apenas o CDP Edge sabe a correspondência real.
+```
+
+---
+
+## Lógica de utm_content por Tipo de Funil
+
+O agente detecta automaticamente e gera os valores corretos:
+
+| O que o Page Analyzer encontrou | utm_content gerado |
+|---|---|
+| Quiz configurado pelo Lead Scoring Agent | `quiz_{nome_do_quiz}` |
+| Player de vídeo / VSL na landing | `video_vsl_principal` |
+| Vídeo de depoimento identificado | `video_depoimento` |
+| Apenas formulário, sem vídeo, sem quiz | `landing_principal` |
+| CTWA ativo (Meta selecionado) | `ctwa_direto` |
+| Webinar / evento ao vivo detectado | `webinar_{nome}` |
+| Múltiplos formatos | gera uma linha para cada |
+
+**Regra:** se o funil tem quiz E vídeo, gera UTMs separadas para cada origem — porque o ROAS Feedback vai poder comparar qual converte mais.
+
+---
+
+## Lógica de utm_medium por Plataforma
+
+O agente gera formatos com base nas plataformas selecionadas na FASE 0-B. Não pergunta ao cliente — usa o que já foi selecionado:
+
+| Plataforma selecionada | utm_medium gerados automaticamente |
+|---|---|
+| Meta Ads | reels, stories, video, cpc |
+| Meta Ads + CTWA | reels, stories, video, cpc, ctwa |
+| Google Ads | cpc |
+| Google Ads + Display | cpc, display |
+| TikTok Ads | video |
+| YouTube Ads | instream, bumper |
+| Pinterest Ads | cpc |
+| LinkedIn Ads | cpc |
+
+---
+
+## utm_campaign — Geração da Faixa Obfuscada
+
+Esta é a única pergunta que o UTM Agent faz ao cliente (já feita na FASE 2-B durante o master orchestrator):
+
+> "Qual o valor/faixa de preço do produto?" (ex: 700k-1M, 297-997, etc.)
+
+Com a resposta, gera:
+```
+SHA256("700k-1M" + salt) → "8a3f1d2b"
+utm_campaign = imovel_8a3f1d2b
+```
+
+Se o cliente **não** tiver segmentação por valor (produto de preço único), o agente usa:
+```
+utm_campaign = {categoria}_geral
+```
+Ex: `imovel_geral`, `curso_geral`, `servico_geral` — sem obfuscação.
+
+---
+
+## utm-mapping.json — Gerado Automaticamente
 
 ```json
 {
@@ -69,123 +230,93 @@ Gerar o arquivo `utm-mapping.json` com:
       "obfuscated": "8a3f1d2b",
       "original": "700k-1M",
       "category": "imovel",
-      "pixel_audience": "AUDIENCE_MID",
       "platform_specific": {
-        "meta": { "custom_audience_id": "2385xxx" },
-        "tiktok": { "pixel_id": "C1xxx" }
+        "meta":    { "custom_audience_id": "" },
+        "tiktok":  { "pixel_id": "" },
+        "google":  { "conversion_label": "" }
       }
     }
-  ]
+  ],
+  "content_registry": {
+    "quiz_diagnostico_imovel": "Quiz de diagnóstico imobiliário (5 perguntas)",
+    "video_vsl_principal":     "VSL principal da landing page",
+    "video_depoimento":        "Vídeo de depoimento de cliente",
+    "landing_principal":       "Formulário direto na landing page",
+    "ctwa_direto":             "Click-to-WhatsApp direto do anúncio"
+  }
 }
+```
+
+O `content_registry` documenta o significado de cada `utm_content` — o Worker usa isso no ROAS Feedback para exibir nomes legíveis nos relatórios.
+
+---
+
+## utm_term — Injetado pelo Worker (Nunca pelo Cliente)
+
+Depois do Lead Scoring Engine classificar o lead via quiz:
+
+```typescript
+// index.ts — após scoreQuizAnswers()
+trackPayload.utmTerm = quizResult.qualification;
+// → 'comprador' | 'interessado' | 'curioso' | 'perdido'
+```
 
-### 4. Perguntas ao usuário (interativo)
-
-**Para imóveis:**
-> "Identifiquei que esta página é um imóvel. Qual a faixa de preço?
-> - 1) 500k-800k
-> - 2) 800k-1.5M
-> - 3) 1M-3M
-> - 4) 3M-5M
-> - 5) Outro (especifique)"
-
-**Para automotivos:**
-> "Qual a faixa de valor do veículo?
-> - 1) 50k-100k
-> - 2) 100k-200k
-> - 3) 200k-500k
-> - 4) Outro (especifique)"
-
-**Para outros produtos:**
-> "Qual a categoria de valor deste produto?
-> - 1) Entry level (até R$500)
-> - 2) Mid-range (R$500-5k)
-> - 3) Premium (R$5k-50k)
-> - 4) Luxury (acima de R$50k)
-> - 5) Outro (especifique)"
-
-### 5. Gerar código do SDK com UTMs obfuscadas
-
-```javascript
-// cdpTrack.js - snippet gerado
-const utmConfig = {
-  faixa_imovel: '8a3f1d2b', // obfuscado
-  product_id: '9c4e2a1f',  // obfuscado
-  source: 'facebook',
-  medium: 'cpc'
-};
-
-cdpTrack('Lead', {
-  utm: utmConfig,
-  // ... outros campos
-});
-```
-
-## Output Structure
+Salvo no D1 em `user_profiles.utm_term` e incluído nos eventos CAPI como `custom_data.utm_term`. O ROAS Feedback Loop usa para cruzar: *qual campanha gerou mais leads classificados como `comprador` que efetivamente compraram?*
+
+> **Dependência:** `utm_term` só é preenchido se o **Lead Scoring Agent** estiver habilitado (FASE 6) e o evento for `QuizComplete` com `quiz_answers` válidas. Se o funil não tiver quiz, `utm_term` permanece vazio — o ROAS Feedback funciona, mas sem segmentação por qualificação de lead.
+
+---
+
+## Arquivos Gerados
+
+```
+server-edge-tracker/
+  config/
+    utm-mapping.json          ← mapeamento obfuscado + content_registry
+
+# Entregue ao cliente:
+UTMS-PROJETO-[NOME].md        ← tabela completa de UTMs prontas para copiar/colar
+```
+
+---
+
+## O Que Este Agente NÃO FAZ
+
+- ❌ Não pede ao cliente para "montar" UTMs — ele gera e entrega prontas
+- ❌ Não pergunta formatos de anúncio — usa o que foi selecionado na FASE 0-B
+- ❌ Não pergunta se tem quiz — usa o que o Lead Scoring Agent configurou
+- ❌ Não expõe valores reais de produto na URL — sempre obfuscado via SHA256
+- ❌ Não preenche utm_term nos anúncios — isso é exclusivo do Worker
+
+---
+
+## Saída Final (JSON para o Master Orchestrator)
 
 ```json
 {
   "agent": "utm-agent",
-  "version": "1.0.0",
-  "utm_strategy": {
-    "pattern": "{source}/{medium}/{category}_{obfuscated_range}",
-    "base_url": "https://lançamentosabc.com.br"
+  "version": "2.1.0",
+  "utm_campaign_base": "imovel_8a3f1d2b",
+  "value_range_original": "700k-1M",
+  "utms_generated": 11,
+  "por_plataforma": {
+    "facebook": 7,
+    "google": 1,
+    "tiktok": 2,
+    "whatsapp": 1
   },
-  "obfuscated_utms": [
-    {
-      "campaign": "imovel_8a3f1d2b",
-      "content": "product_9c4e2a1f",
-      "original_range": "700k-1M",
-      "obfuscated_hash": "8a3f1d2b"
-    }
+  "origens_detectadas": [
+    "quiz_diagnostico_imovel",
+    "video_vsl_principal",
+    "landing_principal",
+    "ctwa_direto"
   ],
-  "worker_mapping": {
-    "file": "utm-mapping.json",
-    "location": "server-edge-tracker/config/utm-mapping.json"
-  },
-  "sdk_integration": {
-    "file": "cdpTrack.js",
-    "snippet": "// UTM obfuscado\nconst utmObfuscado = '8a3f1d2b';"
-  }
+  "utm_term_automatico": true,
+  "arquivos_criados": [
+    "server-edge-tracker/config/utm-mapping.json",
+    "UTMS-PROJETO-[NOME].md"
+  ],
+  "integracao_roas": true,
+  "integracao_quiz": true
 }
 ```
-
-## Integração com Outros Agentes
-
-1. **Page Analyzer** → informa tipo de produto
-2. **UTM Agent** → pergunta faixa de valor, gera UTMs obfuscadas
-3. **Meta Agent** → recebe UTMs, configura custom audiences
-4. **TikTok Agent** → recebe UTMs, configura pixel events
-5. **Worker** → usa `utm-enricher.ts` para de-obfuscar no runtime
-
-## Edge Cases
-
-- Usuário não sabe a faixa de valor: "Aguardo definição do cliente - use DEFAULT"
-- Produto sem faixa definida: usar `generic_00000000`
-- UTMs existentes: fazer merge sem sobrescrever
-- Múltiplas categorias: perguntar se precisa de segmentação composta
-
-## Example Session
-
-**Page Analyzer:**
-> "Página identificada: imóvel em Vila Mariana, 3 quartos, 2 banheiros"
-
-**UTM Agent:**
-> "Para qual faixa de preço este imóvel deve ser categorizado?"
->
-> Usuário: "800k-1.5M"
->
-> **UTM Agent:**
-> ```json
-> {
->   "utm_faixa": "imovel_b4e2a1c9",
->   "original_range": "800k-1.5M",
->   "hash": "b4e2a1c9"
-> }
-> ```
-
-## Rules
-1. **NUNCA** revelar o valor real na URL pública
-2. **SEMPRE** usar hash obfuscado para valores sensíveis
-3. **Mapeamento reversível** deve estar disponível no Worker (não no SDK)
-4. **Meta CAPI** recebe valor de-obfuscado internamente
-5. UTMs sem valor sensível podem ficar em texto claro

package/extracted-skill/tracking-events-generator/cdpTrack.js

@@ -209,13 +209,15 @@ export const generateId = () => {
 // ── Captura de Click IDs das plataformas ──────────────────────
 const _getClickIDs = () => {
   return {
-    fbp: document.cookie.match(/_fbp=([^;]+)/)?.[1],
-    fbc: document.cookie.match(/_fbc=([^;]+)/)?.[1],
-    gclid: _gclid,
-    gbraid: _gbraid,
-    wbraid: _wbraid,
-    ttclid: _ttclid,
-    rclid: _urlParams.get('rclid')
+    fbp:    document.cookie.match(/_fbp=([^;]+)/)?.[1] || undefined,
+    fbc:    document.cookie.match(/_fbc=([^;]+)/)?.[1] || undefined,
+    fbclid: _fbclid || undefined,  // click ID Meta → Worker gera fbc se cookie _fbc ausente
+    gclid:  _gclid  || undefined,
+    gbraid: _gbraid || undefined,
+    wbraid: _wbraid || undefined,
+    ttclid: _ttclid || undefined,
+    ttp:    document.cookie.match(/_ttp=([^;]+)/)?.[1] || undefined,  // TikTok Pixel cookie — EMQ TikTok
+    rclid:  _urlParams.get('rclid') || undefined,
   };
 };
 
@@ -459,7 +461,7 @@ export async function track(eventName, data = {}, options = {}) {
 
   try {
     // Enviar para Worker com retry automático (anti-blocking)
-    const result = await sendWithRetry(payload, '/api/tracking');
+    const result = await sendWithRetry(payload, '/track');
 
     if (result.success) {
       console.log(`✅ Evento ${eventName} enviado com sucesso:`, event_id, result);

package/extracted-skill/tracking-events-generator/models/quiz-funnel.md

@@ -1,15 +1,15 @@
 # Modelo: Quiz Funnel (Cloudflare Native)
 
-Este modelo é destinado a funis de quiz, onde o usuário responde a uma série de perguntas antes de ser redirecionado para a oferta final. O rastreamento foca na progressão do usuário e na captura de dados intermediários.
+Este modelo é destinado a funis de quiz, onde o usuário responde a uma série de perguntas antes de ser redirecionado para a oferta final. O rastreamento foca na progressão do usuário e na **qualificação automática de intenção via Workers AI**.
 
 ---
 
 ## 🏗️ ARQUITETURA TÉCNICA (Quantum Tier)
 
-O rastreamento segue a lógica de micro-eventos:
+O rastreamento segue a lógica de micro-eventos + scoring automático:
 1. **Página**: Dispara um evento a cada resposta dada no quiz via `cdpTrack.track()`.
-2. **Servidor (Worker)**: Recebe e armazena o progresso no banco D1.
-3. **Database (D1)**: Mantém o histórico de respostas vinculado ao `track_user_id`.
+2. **Servidor (Worker)**: Ao receber `QuizComplete`, envia as respostas ao **Quiz Scoring Engine** (Granite 4.0 Micro) que classifica o respondente.
+3. **Pipeline CDP**: A qualificação (`comprador | interessado | curioso | perdido`) é injetada como `intentionLevel` e flui automaticamente para LTV Prediction, Meta Signal Score, D1 e CAPI dispatch.
 
 ---
 
@@ -19,50 +19,114 @@ O rastreamento segue a lógica de micro-eventos:
 |---|---|---|
 | **QuizStart** | Início do quiz | `quiz_name`, `source` |
 | **QuizAnswer** | Resposta a uma pergunta | `question`, `answer`, `step` |
-| **QuizComplete** | Finalização do quiz | `result`, `completion_time` |
+| **QuizComplete** | Finalização + qualificação AI | `quiz_name`, `quiz_answers[]`, `result` |
+
+---
+
+## 🤖 QUALIFICAÇÃO AUTOMÁTICA (Quiz Scoring Engine — Fase 6)
+
+Ao receber `QuizComplete` com `quiz_answers`, o Worker classifica automaticamente:
+
+| Qualificação | Significado | intent_score |
+|---|---|---|
+| **comprador** | Pronto para comprar agora | 0.80–1.00 |
+| **interessado** | Interesse real, avaliando | 0.50–0.79 |
+| **curioso** | Pesquisando, sem urgência | 0.20–0.49 |
+| **perdido** | Fora do público, sem fit | 0.00–0.19 |
+
+O `intent_score` resultante:
+- Alimenta o **LTV Prediction** (comprador → LTV High automaticamente)
+- Compõe o **Meta Signal Score** (pesos dinâmicos por funil)
+- Persiste em `leads.intention_level` e `quiz_sessions` no D1
+- É enviado como `custom_data` para Meta CAPI, GA4 e TikTok
 
 ---
 
 ## 🛠️ PASSO 1: CONFIGURAÇÃO DO SITE
 
 ### 1.1 Rastreamento de Respostas
-Integre este código na lógica de clique do seu quiz.
+Acumule as respostas do quiz em um array local.
 
 ```javascript
-// Exemplo de captura de resposta
+const quizAnswers = [];
+
 function onResponder(pergunta, resposta, etapa) {
+  // Armazena localmente para enviar no QuizComplete
+  quizAnswers.push({ question: pergunta, answer: resposta, step: etapa });
+
+  // Dispara micro-evento por resposta (opcional, para análise granular)
   cdpTrack.track('QuizAnswer', {
     question: pergunta,
     answer: resposta,
     step: etapa,
-    event_id: cdpTrack.generateId()
+    event_id: cdpTrack.generateId(),
   });
 }
 ```
 
-### 1.2 Finalização do Quiz
-Disparar ao chegar no resultado final ou na página de captura pós-quiz.
+### 1.2 Finalização do Quiz — com qualificação AI automática
+Envie todas as respostas no `QuizComplete`. O Worker qualifica automaticamente.
 
 ```javascript
 cdpTrack.track('QuizComplete', {
-  result: 'Perfil_A',
-  event_id: cdpTrack.generateId()
+  quiz_name: 'Diagnóstico de Perfil',   // nome para o dashboard
+  quiz_answers: quizAnswers,             // array com todas as respostas
+  result: 'Perfil_A',                   // resultado exibido ao usuário (opcional)
+  event_id: cdpTrack.generateId(),
 });
 ```
 
+### 1.3 Resposta do Worker
+O endpoint `/track` retorna a qualificação para uso imediato no front:
+
+```json
+{
+  "ok": true,
+  "userProfile": {
+    "score": 87,
+    "user_id": "uuid-xxx"
+  },
+  "quiz_qualification": "comprador",
+  "quiz_confidence": 0.91,
+  "quiz_signals": ["quero comprar", "tenho budget", "agora"],
+  "intent_score": 0.92,
+  "intent_bucket": "high"
+}
+```
+
+Use esses campos para personalizar o redirecionamento pós-quiz no front-end.
+
 ---
 
 ## ⚡ PASSO 2: SERVIDOR (CLOUDFLARE WORKER)
 
-O Worker realiza:
-- **Agregação**: O `user_id` permite que todas as respostas sejam vinculadas a um único perfil no banco D1.
-- **Enriquecimento**: Se o usuário deixar o e-mail no final, todas as respostas anteriores são associadas ao e-mail para a CAPI.
-- **API Dispatch**: Envio de eventos customizados para Meta e TikTok para otimização de público.
+O Worker realiza automaticamente na ordem:
+
+1. **Quiz Scoring Engine**: Granite 4.0 Micro classifica as respostas → `qualification` + `intent_score`
+2. **LTV Prediction**: usa `intentionLevel = 'comprador'` → LTV High → valor previsto em BRL
+3. **Meta Signal Score**: `intent_score` compõe o score composto (intent × ltv × distância)
+4. **D1 Writes**: `quiz_sessions` + `leads.intention_level` + `user_profiles.cohort_label`
+5. **CAPI Dispatch**: Meta/GA4/TikTok recebem evento com `custom_data.intention = 'comprador'`
+
+---
+
+## 🔀 FALLBACK HEURÍSTICO
+
+Se Workers AI estiver indisponível (timeout, cold start), o sistema usa correspondência de palavras-chave:
+
+- `comprador`: "quero", "comprar", "agora", "tenho interesse", "quanto custa"
+- `interessado`: "talvez", "pensando", "em breve", "estou avaliando"
+- `curioso`: "só olhando", "pesquisando", "curiosidade"
+- `perdido`: "não entendi", "errei aqui", "não é para mim"
+
+O campo `quiz_source` indica `"ai"` ou `"heuristic"` para auditoria.
 
 ---
 
 ## ✅ VALIDAÇÃO TÉCNICA
 
-- **Persistência**: Verifique no banco D1 se a jornada do usuário está sendo gravada passo a passo.
-- **Deduplicação**: O `event_id` único por resposta evita contagens duplicadas.
-- **Match Quality**: A vinculação tardia do e-mail com as respostas iniciais aumenta a precisão da atribuição.
+- **Persistência**: `quiz_sessions` no D1 — jornada completa por `user_id`
+- **Deduplicação**: `event_id` único por evento evita contagens duplicadas
+- **Enriquecimento retroativo**: e-mail preenchido pós-quiz associa todas as respostas ao perfil
+- **Match Quality**: `comprador` com e-mail → score máximo na CAPI Meta
+- **VIEW de dashboard**: `v_quiz_qualification_summary` — distribuição de qualificações por quiz

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-edge",
-  "version": "2.3.8",
+  "version": "2.3.9",
   "description": "CDP Edge - Quantum Tracking - Sistema multi-agente para tracking digital Cloudflare Native (Workers + D1)",
   "main": "dist/index.js",
   "type": "module",