# AEO by EPIC — Answer Engine Optimization

> Documento master do framework AEO da EPIC Digital.
> Tese, metodologia, Commerce Layer e evidencias em um unico lugar.
>
> Versao 2.1 | Maio 2026 | EPIC Digital | Autor: Fabio Munhoz
> Primeiro case: ClearSale/Experian, Fevereiro 2026
> **v2.1 (Mai 2026):** novo Layer 6 (Agentic Experience) — active handoff humano→LLM

---

## Indice

1. [Tese: Por que AEO existe](#parte-1--tese-por-que-aeo-existe)
2. [Framework: As 7 Camadas (v2.1)](#parte-2--framework-as-7-camadas-v21)
3. [Commerce Layer: o diferencial EPIC](#parte-3--commerce-layer-o-diferencial-epic)
4. [Metodologia EPIC](#parte-4--metodologia-epic)
5. [Evidencias (7 cases)](#parte-5--evidencias-7-cases)
6. [Como usar este repositorio](#parte-6--como-usar-este-repositorio)
7. [Mapa do repositorio](#parte-7--mapa-do-repositorio)
8. [Autoria e versao](#parte-8--autoria-e-versao)
9. [English version](#english-version)

---

## Parte 1 — Tese: Por que AEO existe

### O shift de comportamento

Executivos B2B e compradores corporativos nao comecam mais no Google. Comecam no ChatGPT, Perplexity, Gemini ou Copilot. As perguntas deixaram de ser palavras-chave e viraram frases completas, em contexto:

- "Quem sao os melhores fornecedores de [servico X] no Brasil?"
- "Compare [empresa A] com [empresa B]"
- "Quanto custa [solucao Y] para uma empresa de 500 funcionarios?"
- "Quem resolve [problema X] e atende clientes no setor [Y]?"

O resultado e uma nova camada de triagem entre o comprador e o fornecedor: **a resposta do answer engine**. Quem nao aparece na resposta, simplesmente nao existe.

### O problema: invisibilidade em answer engines

Nossos audits mostram que a maioria dos sites B2B nao esta preparada para esse novo comportamento. Dados reais do **HubSpot AEO Grader** em clientes recentes:

| Cliente | ChatGPT | Perplexity | Gemini | Overall |
|---------|---------|------------|--------|---------|
| DOT Digital Group | 50/100 | 76/100 | 50/100 | "no caminho" |
| Pulse Experiential Travel | 33/100 | 60/100 | 51/100 | 0.7/10 geral |
| EPIC Digital (self-audit) | — | — | — | 40.5/100 (combinado) |

Perplexity pontua mais alto porque faz pesquisa em tempo real. ChatGPT e Gemini dependem de training data — e training data **ignora sites que nao sao citaveis por maquinas**.

### A oportunidade: category leap via AEO

Quando a maioria esta invisivel, **aparecer na resposta e vantagem desproporcional**. E uma janela estreita de advantage competitiva — similar ao momento em que SEO era diferencial (2005-2010) antes de virar commodity. Em 2026, AEO esta nesta janela.

Para clientes EPIC, AEO nao e "melhoria de site" — e um **category leap**: o primeiro a ser visto pelos answer engines de um setor captura desproporcionalmente o intent de compra.

### AEO e uma disciplina, nao uma ferramenta

**AEO (Answer Engine Optimization)** e a disciplina de otimizar um site para ser **descobrivel, citavel e transacionavel** por maquinas — crawlers de AI, sistemas de retrieval, agentes autonomos.

Nao se confunde com:
- **SEO** — otimiza para buscadores tradicionais (Google, Bing). Cobre parte das camadas 0-2 do AEO.
- **GEO** — otimiza conteudo existente para ser citado por AI generativa. Cobre parte da camada 3 do AEO.

AEO vai alem: cria uma **camada dedicada para agentes** (Layer 4, a Commerce Layer), com endpoints estruturados e acoes executaveis. E o unico framework, hoje, que pensa a presenca digital a partir da maquina consumidora.

---

## Parte 2 — Framework: As 7 Camadas (v2.1)

O AEO Framework v2.1 tem **7 camadas** (6 de discoverability passiva + 1 de active handoff), cada uma servindo um tipo diferente de maquina consumidora ou momento de uso.

```
Layer 0  DISCOVERY          robots.txt + llms.txt + /.well-known/
Layer 1  STRUCTURED DATA    JSON-LD schemas + potentialAction
Layer 2  SEMANTIC HTML      Heading hierarchy + landmarks + microdata
Layer 3  NARRATIVE BLOCKS   TL;DR + FAQ + conteudo citavel
Layer 4  COMMERCE LAYER     Agent Card + API endpoints + transacao M2M
Layer 5  MEASUREMENT        Agent analytics + token benchmarks
Layer 6  AGENTIC EXPERIENCE Open-in-LLM + Copy Page + .md companion (NEW v2.1)
```

### Quem consome o que

| Maquina | Camadas | Exemplo |
|---------|---------|---------|
| Search Crawler | 0, 1, 2 | Googlebot, Bingbot |
| AI Crawler | 0, 1, 2, 3 | GPTBot, ClaudeBot, PerplexityBot |
| RAG / Retrieval | 2, 3 | Embeddings, vector search |
| AI Agent | 0, 4 | ChatGPT Actions, MCP tools, A2A agents |
| Analytics interna | 5 | Dashboards de agentes, token benchmarks |
| Human → LLM handoff | 6 | Open in ChatGPT/Claude/Perplexity buttons |

### Layer 0 — Discovery

**Proposito:** Permitir que maquinas descubram o site, entendam o que ele oferece, e encontrem os caminhos otimizados para consumo.

**Componentes:**
- `robots.txt` AEO-optimized (permite AI crawlers explicitamente)
- `llms.txt` (resumo markdown do site — 844k+ sites ja implementam)
- `/.well-known/` (IETF RFC 8615 — ponto de entrada para discovery)

**Canonico:** llmstxt.org, spec de Jeremy Howard (2024). Adotado por Anthropic, Cloudflare, Stripe.

Spec completa: [AEO-FRAMEWORK-v2.md § Layer 0](AEO-FRAMEWORK-v2.md)

### Layer 1 — Structured Data

**Proposito:** Declarar, em linguagem maquina, o que cada pagina representa — organizacao, produto, servico, pessoa, preco, acao.

**Componentes:**
- JSON-LD em todas as paginas (Schema.org)
- `potentialAction` + `EntryPoint` — a **ponte** para Layer 4 (Commerce)
- Sem `aggregateRating` sem dados reais (penalizacao Google)

**Regra critica:** `potentialAction` e o que conecta dados estruturados a acoes executaveis. Sem ele, Layer 4 nao se pluga em Layer 1.

Spec completa: [AEO-FRAMEWORK-v2.md § Layer 1](AEO-FRAMEWORK-v2.md)

### Layer 2 — Semantic HTML

**Proposito:** HTML bem-formado serve como **estrutura de retrieval**. RAG systems, embeddings e leitores de tela dependem de hierarquia semantica correta.

**Componentes:**
- H1 unico por pagina (nunca mencionando concorrente)
- Hierarquia H2/H3 logica
- Landmarks (`<main>`, `<nav>`, `<article>`, `<aside>`)
- Microdata complementar a JSON-LD

Spec completa: [AEO-FRAMEWORK-v2.md § Layer 2](AEO-FRAMEWORK-v2.md)

### Layer 3 — Narrative Blocks

**Proposito:** Conteudo citavel por AI generativa. Blocos autocontidos que o modelo pode **recortar e colar** na resposta.

**Componentes:**
- **TL;DR** no topo de cada pagina (2-3 linhas, autocontido)
- **FAQ** com perguntas reais do publico (nao adjetivos — frases que compradores digitariam)
- Conteudo pareado a perguntas (pergunta → resposta factual curta)
- Citacoes de fontes originais

**Regra:** narrative blocks devem funcionar **fora de contexto** — o modelo vai recortar um paragrafo sem ver o resto.

Spec completa: [AEO-FRAMEWORK-v2.md § Layer 3](AEO-FRAMEWORK-v2.md)

### Layer 4 — Commerce Layer

**Proposito:** Infraestrutura **machine-to-machine** que permite agentes de AI **transacionar** com o site — nao apenas ler.

**Componentes:**
- **Agent Card** (A2A-compatible) em `/.well-known/agent-card.json`
- **AEO Sitemap** (`sitemap-aeo.json`) com metadados para agentes
- **JSON endpoints** (`/api/aeo/{page}.json`) — dados estruturados sem HTML
- **Endpoints transacionais** (POST `/api/quote-request`, `/api/demo`, etc.)
- `<link rel="alternate">` no HTML apontando para a versao JSON

Esta e **a camada que diferencia EPIC**. Ver Parte 3 abaixo para deep dive.

### Layer 5 — Measurement

**Proposito:** Provar ROI. Agentes de AI deixam pegadas diferentes de humanos — e essas pegadas precisam ser medidas.

**Componentes:**
- Logs segmentados por User-Agent (GPTBot, ClaudeBot, PerplexityBot)
- Token cost benchmarks por endpoint
- Share of voice em answer engines ao longo do tempo
- Dashboards de citacao (AEO Grader recorrente)

Spec completa: [AEO-FRAMEWORK-v2.md § Layer 5](AEO-FRAMEWORK-v2.md)

### Layer 6 — Agentic Experience (NEW v2.1)

**Proposito:** Permitir que um humano transfira a pagina para um LLM ativo em **UM clique** — fechando o loop entre a discoverability passiva (L0-L5) e o consumo ativo por assistentes de IA.

Diferente das outras camadas, L6 atua na **UX do site** (botoes, dropdowns, link tags) e nao apenas na infraestrutura de dados. L0-L5 trazem o trafego organico (crawlers indexam → answer engines citam → humanos clicam). L6 amplifica engagement depois que o humano ja esta na pagina: curtiu o conteudo → quer aprofundar via LLM → leva a pagina para uma nova sessao de chat.

Sem L6, a pagina termina no momento que o usuario fecha o tab. Com L6, a pagina **vira input** para a proxima conversa do usuario com um LLM — extendendo o alcance da marca alem do session-end.

**Componentes (10 checks, peso 10% no overall v2.1):**
- `.md` companion publicado (padrao shadcn: `<url>.md`)
- Widget "Copy Page" no header de cada pagina relevante
- Open-in-ChatGPT (`chatgpt.com/?q=`), Open-in-Claude (`claude.ai/new?q=`), Open-in-Perplexity (`perplexity.ai/?q=`)
- `<link rel="alternate" type="text/markdown">` declarado
- Prompt template contextual (default: `Please read this page and help me summarize: {markdown_url}`)
- Mobile-accessible (nao escondido via media queries)
- Self-contained widget (≤ 2KB, zero deps externos)

**Inspiracao:** shadcn/ui, Vercel docs, Anthropic docs (todos publicam doc pages com Open-in-LLM dropdown).

**Implementacao de referencia:** `aeo generate agentic <url>` (CLI v2.1+) emite o snippet HTML self-contained. `aeo audit` e `aeo site` agora escrevem `.md` ao lado de `.html` automaticamente.

> **BREAKING (v2.1):** LAYER_WEIGHTS rebalanceados para acomodar L6 a 10% sem ultrapassar 100% — scores absolutos v2.0 NAO sao comparaveis com v2.1. Ver CHANGELOG.md.

Spec completa: [AEO-FRAMEWORK-v2.md § Layer 6](AEO-FRAMEWORK-v2.md)

---

## Parte 3 — Commerce Layer: o diferencial EPIC

### Por que elevar Commerce Layer como tese

Na pratica comercial da EPIC, Commerce Layer **deixou de ser "Layer 4 do AEO"** e virou um produto com nome proprio — o **modulo EPIC TECH** em propostas B2B globais (SoEnergy, Apgar, ClearSale).

A razao e conceitual: Layers 0-3 tornam o site **legivel** por maquinas. Layer 4 torna o site **acionavel**. A diferenca e da mesma magnitude do salto de brochure para e-commerce no inicio dos anos 2000 — so que o comprador agora e uma maquina.

### Contexto de mercado

- **Google A2A Protocol** (Agent-to-Agent, Abril 2025) — 150+ organizacoes fundadoras, protocolo aberto para agentes se descobrirem e cooperarem
- **MCP (Model Context Protocol)** da Anthropic (Novembro 2024) — padrao para LLMs acessarem ferramentas externas
- **RFC 7231 Content Negotiation** (2014) — mecanismo HTTP que permite a mesma URL servir HTML para humanos e JSON para agentes
- **llms.txt spec** (Jeremy Howard, 2024) — convencao adotada por 844k+ sites

Commerce Layer e a implementacao pragmatica desses padroes em sites B2B — **antes** dos concorrentes acordarem.

### O manifesto

> "Quando um executivo C-level perguntar ao ChatGPT quem resolve [problema do cliente], a resposta nao deve apenas citar voce — deve permitir que o agente **solicite uma cotacao**, **compare precos** e **agende uma demo**, tudo sem intervencao humana."

### Anatomia

1. **Agent Card** (`/.well-known/agent-card.json`) — Manifesto JSON declarando capacidades. Campos A2A padrao (`name`, `description`, `capabilities`, `skills[]`) + extensoes AEO (`x_aeo`: sitemap, llms_txt, key_metrics, competitive_context, token_cost_estimate).

2. **AEO Sitemap** (`sitemap-aeo.json`) — Indice machine-readable com URL, tipo de pagina, entidade schema, `aeo_endpoint` (JSON), `key_facts`, `actions_available`, `aeo_tldr`.

3. **JSON Endpoints** (`/api/aeo/{page}.json`) — Cada pagina HTML tem uma versao JSON correspondente. Token cost < 500 vs ~3000 do HTML (85% de economia). Inclui `actions` linkando endpoints transacionais.

4. **Endpoints transacionais** — POST para acoes reais:

| Endpoint | Acao | Campos obrigatorios |
|----------|------|---------------------|
| `/api/quote-request` | Solicitar cotacao | company_name, contact_email |
| `/api/estimate` | Estimar preco | monthly_transactions, average_order_value |
| `/api/recommend` | Recomendar solucao | industry, challenge |
| `/api/demo` | Agendar demo | company_name, contact_email |

5. **`<link rel="alternate">`** no HTML apontando para a versao JSON — permite crawlers de HTML descobrirem o canal estruturado.

### Business case para C-level

| | Hoje | Com Commerce Layer |
|-|------|--------------------|
| ChatGPT pergunta sobre voce | Pode ou nao citar | Cita com dados estruturados |
| Agente busca fornecedor | Nao encontra | Encontra via Agent Card |
| Agente quer cotacao | Impossivel | POST /api/quote-request |
| Agente compara precos | Scraping fragil | JSON endpoint dedicado |
| Token cost para a AI citar | ~3000 tokens de HTML | ~500 tokens de JSON |

### Compatibilidade por stack

| Stack | Commerce Layer |
|-------|----------------|
| Express / Node.js | **100%** — rotas nativas, headers custom, Content Negotiation RFC 7231 |
| HubSpot Content Hub | **~80%** — serverless functions (platformVersion 2025.2), URL mappings (tier-aware) |
| Static / Vercel / Netlify | **~40%** — sem endpoints dinamicos, sem Content Negotiation |

**Content Negotiation** (mesma URL servindo HTML ou JSON baseado em Accept header) so roda em infra propria. Implementado em Quave ONE (case Jupiter).

### Deep dive

- Tese completa: [docs/commerce-layer-thesis.md](docs/commerce-layer-thesis.md)
- Implementacao: [docs/commerce-layer-explained.md](docs/commerce-layer-explained.md)
- Content Negotiation: [docs/content-negotiation.md](docs/content-negotiation.md)
- Em HubSpot: [docs/hubspot-implementation.md](docs/hubspot-implementation.md)
- Em Express: [docs/express-implementation.md](docs/express-implementation.md)

---

## Parte 4 — Metodologia EPIC

A EPIC entrega AEO em 4 estagios, nesta ordem:

```
AUDIT DEVASTADOR  →  PROPOSTA  →  IMPLEMENTACAO  →  MEASUREMENT
```

### Estagio 1 — Audit devastador (mas factual)

Usamos duas ferramentas complementares:

**1. HubSpot AEO Grader** — roda o site contra 3 LLMs (ChatGPT, Perplexity, Gemini) e retorna:
- Reconhecimento de marca (/20)
- Posicao de mercado (/10)
- Qualidade da presenca (/20)
- Sentimento (/40)
- Share of voice (/10)
- **Total /100 por LLM**

**2. 50 prompts manuais** — testados em 3 LLMs com frases reais do publico-alvo:
- Prompts de reconhecimento ("O que e [empresa]?")
- Prompts de comparacao ("Compare X com Y")
- Prompts de decisao de compra ("Vale a pena contratar X?")
- Prompts de problema ("Como resolver [problema]?")

**3. Scoring manual por camada** (0-2 por camada, total /10):

| Camada | Criterio |
|--------|----------|
| L0 Discovery | robots.txt permite AI? llms.txt existe? .well-known? |
| L1 Structured Data | JSON-LD correto? potentialAction? |
| L2 Semantic HTML | H1 unico? Hierarquia? Tags semanticas? |
| L3 Narrative | TL;DR? FAQ? Conteudo citavel? |
| L4 Commerce Layer | Agent Card? Endpoints? Actions? |
| L5 Measurement | Logs? Analytics de agentes? |
| L6 Agentic Experience | `.md` companion? Open-in-LLM widget? Copy Page? Mobile-accessible? |

### Tom do audit: devastador mas factual

**Regra (aprendida no Pulse):** o corpo do audit e puramente factual — scores, screenshots, citacoes das respostas dos LLMs. **Nenhuma recomendacao no relatorio**. Recomendacoes ficam na proposta comercial separada.

Isso gera urgencia sem parecer venda. O cliente ve os numeros e chega sozinho a conclusao de que precisa agir.

Metodologia completa: [docs/aeo-grader-methodology.md](docs/aeo-grader-methodology.md)

### Estagio 2 — Proposta

A proposta derivada do audit inclui:
- **Gap analysis** por camada (onde o cliente esta vs onde precisa estar)
- **Priorizacao** de camadas (0-3 quick wins, 4 diferencial, 5 long game)
- **Escopo de paginas** com spec AEO por pagina
- **Modulo Commerce Layer como item destacado** (badge "EPIC TECH") para clientes B2B globais — aprendizado SoEnergy

### Estagio 3 — Implementacao

**Framework universal, adapters por stack.**

O `@epic-digital/aeo` CLI (npm package) roda auditorias, gera templates (llms.txt, agent-card.json, sitemap-aeo.json, robots.txt AEO) e produz reports HTML.

**5 comandos:**
- `aeo audit <url>` — auditoria 7-camadas (v2.1+), score 0-100. Escreve `.md` + `.html` companions.
- `aeo site <url>` — auditoria multi-page de dominio inteiro (v2.0+). Escreve `.md` + `.html` companions.
- `aeo report <url>` — HTML report EPIC Reporting style
- `aeo generate <url>` — gera templates pre-preenchidos (llms.txt, agent-card.json, sitemap-aeo.json, robots-aeo.txt)
- `aeo generate agentic <url>` — gera widget HTML self-contained (Copy Page + Open-in-LLM + .md companion) (v2.1+)
- `aeo compare <url1> <url2>` — comparativo lado a lado

**3 providers:**
- HttpProvider (default, rapido, undici)
- PlaywrightProvider (--deep, para SPAs com JS)
- FirecrawlProvider (--provider firecrawl, deep crawl)

**2 adapters (mais plugin registry):**
- HubSpot (tier-aware: Starter/Pro/Enterprise)
- Express / Node.js

**76 checks totais v2.1** (11+12+11+11+11+10+10 por camada — L6 acrescenta 10 checks).

Playbooks:
- [playbooks/hubspot-aeo-playbook.md](playbooks/hubspot-aeo-playbook.md) (848 linhas)
- [playbooks/express-aeo-playbook.md](playbooks/express-aeo-playbook.md) (921 linhas)

### Estagio 4 — Measurement

Pos-implementacao, o cliente recebe:
- Logs segmentados por User-Agent de AI (Layer 5)
- AEO Grader recorrente (trimestral ou mensal)
- Dashboard de citacoes em answer engines
- Token benchmarks por endpoint

**Objetivo:** provar deltas. "Antes do Commerce Layer, ChatGPT nao te citava. Agora cita em X% das queries do setor."

---

## Parte 5 — Evidencias (7 cases)

7 implementacoes AEO reais entre Fev e Mar 2026, ~150+ paginas criadas, 2 stacks validadas.

### 1. ClearSale / Experian — `Maior implementacao`

57 paginas em HubSpot CMS. O **AEO Framework v2 nasceu neste projeto**. Package 1 (7 pags) + Package 2 (5 pags) + 10 case studies individuais completos. Conceito "Trust for Machines" — primeira campanha direcionada a agentes de AI. CMS Fase 1 com 24 modules + 7 templates + 7 pages draft em GitHub `epic-digital-mkt/clearsale-cms`. [cases/clearsale-experian.md](cases/clearsale-experian.md)

### 2. DOT Digital Group — `Primeiro Commerce Layer funcional`

32 paginas em Express/Node.js, prototipo AEO-first completo. Primeiro Commerce Layer funcional da EPIC — produto escolhido: **Roleplay IA** (AI-native, 8 actions no Agent Card). AEO Grader: ChatGPT 50 / Perplexity 76 / Gemini 50. Mega menu CSS espelhando arquitetura do sitemap. [cases/dot-digital-group.md](cases/dot-digital-group.md)

### 3. Apgar — `Clone DOT para EU`

32 paginas Express/Node.js, clone do prototipo DOT adaptado para EdTech europeu. Prova que o framework e **replicavel entre clientes** com minimo esforco — trocar conteudo, manter estrutura. Mesma stack de Agent Card + sitemap-aeo + llms.txt. [cases/apgar.md](cases/apgar.md)

### 4. OpenCadd — `Specs antes do prototipo`

16 AEO spec docs, um por pagina planejada. Primeiro caso onde criamos specs AEO completas **antes** do prototipo visual — as specs servem como blueprint para implementacao futura. [cases/opencadd.md](cases/opencadd.md)

### 5. SoEnergy — `Commerce Layer em proposta B2B`

3 paginas (homepage V5 AEO 9/10 + concept hub + proposta). Homepage com fundo escuro, parallax, JSON-LD completo (Organization + 3x Service + FAQPage + BreadcrumbList). Proposta R$55k com **Commerce Layer AEO como modulo 3.4 com badge "EPIC TECH"** — primeiro caso onde Commerce Layer virou modulo comercial destacado para B2B global. [cases/soenergy.md](cases/soenergy.md)

### 6. Quave ONE / Jupiter — `Content Negotiation RFC 7231`

Homepage AEO-first (~1830 linhas), primeiro caso com **Content Negotiation completo**: mesma URL responde HTML ou JSON baseado em Accept header. Middleware Express inspeciona Accept + User-Agent, adiciona `Vary: Accept, User-Agent`. Score AEO/SEO subiu de 7.4 para 9.0 com 7 fixes. [cases/quave-one.md](cases/quave-one.md)

### 7. Pulse Experiential Travel — `Audit devastador`

Audit completo SEO/AEO/Agentic Commerce (SEO 2/10, AEO 0/10, Agentic 0/10, overall 0.7/10). HubSpot AEO Grader (ChatGPT 33 / Perplexity 60 / Gemini 51). 50 prompts testados manualmente. **Benchmark da metodologia "audit devastador"** — tom factual, sem recomendacoes no corpo, gera urgencia sem parecer venda. [cases/pulse.md](cases/pulse.md)

### Cross-project learnings

19 learnings consolidados em [learnings/AEO-LEARNINGS.md](learnings/AEO-LEARNINGS.md), organizados por tema (Framework, Structured Data, Semantic HTML, Commerce Layer, Implementacao, Audit & Grading).

---

## Parte 6 — Como usar este repositorio

### Matriz papel × documento

| Papel | Comece por | Depois |
|-------|-----------|--------|
| **Sales / Account** | [docs/what-is-aeo.md](docs/what-is-aeo.md) (pitch executivo) | Parte 3 deste doc + [docs/commerce-layer-thesis.md](docs/commerce-layer-thesis.md) para diferencial |
| **PM / Delivery** | Este doc (AEO-BY-EPIC.md) inteiro | [cases/](cases/) + playbook da stack + [learnings/AEO-LEARNINGS.md](learnings/AEO-LEARNINGS.md) |
| **Dev / Engineering** | [CLAUDE.md](CLAUDE.md) + [AEO-FRAMEWORK-v2.md](AEO-FRAMEWORK-v2.md) | Playbook da stack + [src/](src/) + [templates/](templates/) |
| **Cliente / Prospect** | [docs/what-is-aeo.md](docs/what-is-aeo.md) | [case-study.html](case-study.html) + [index.html](index.html) |
| **Auditor / QA** | [docs/aeo-grader-methodology.md](docs/aeo-grader-methodology.md) | [templates/aeo-audit-checklist.md](templates/aeo-audit-checklist.md) + CLI `aeo audit` |

### Fluxos tipicos

**Novo cliente B2B**
1. Rodar audit com `aeo audit <dominio>` + AEO Grader (3 LLMs) + 50 prompts manuais
2. Entregar relatorio devastador-mas-factual
3. Fechar escopo usando Parte 4 deste doc + Commerce Layer como modulo EPIC TECH (se B2B global)
4. Escolher stack: HubSpot → `docs/hubspot-implementation.md`, Express → `docs/express-implementation.md`
5. Implementar usando playbook da stack + templates + CLI para gerar stubs
6. Instalar Layer 5 Measurement

**Prospect / Proposta comercial**
1. Ler [docs/what-is-aeo.md](docs/what-is-aeo.md) para pitch
2. Ler Parte 3 deste doc para diferencial Commerce Layer
3. Consultar [cases/](cases/) para evidencia de setor proximo
4. Pitar com tabela "Hoje vs Com Commerce Layer"

**Audit de site existente**
1. Rodar `aeo audit <url> --deep`
2. Completar com [docs/aeo-grader-methodology.md](docs/aeo-grader-methodology.md) (50 prompts)
3. Usar [templates/aeo-audit-checklist.md](templates/aeo-audit-checklist.md) como gabarito
4. Gerar report HTML via `aeo report <url>`

**Contribuicao ao framework**
1. Ler [CONTRIBUTING.md](CONTRIBUTING.md)
2. Escolher tipo: novo check, novo adapter, novo playbook, novo case
3. Abrir PR no repo `epic-digital-mkt/aeo-framework`

---

## Parte 7 — Mapa do repositorio

```
/epic/aeo/
├── AEO-BY-EPIC.md              Este documento — master narrativo
├── AEO-FRAMEWORK-v2.md         Spec tecnica completa (7 camadas v2.1)
├── README.md                   Index navegacional curto
├── CLAUDE.md                   Project guide (stack, arquitetura)
├── CHANGELOG.md                Timeline de evolucao
├── CONTRIBUTING.md             Como contribuir (4 tipos)
├── SEO-GEO-AEO-RESEARCH.md     Research original (pre-framework)
├── START-HERE.md               Quick start para novos agents
├── index.html                  Landing bilingue (PT/EN)
├── case-study.html             Case study bilingue
│
├── docs/                       Documentacao conceitual (MD + HTML bilingue)
│   ├── what-is-aeo.md               Pitch executivo (clientes/prospects)
│   ├── aeo-vs-seo-vs-geo.md         Comparativo SEO vs GEO vs AEO
│   ├── commerce-layer-thesis.md     Tese Commerce Layer (diferencial)
│   ├── commerce-layer-explained.md  Implementacao Commerce Layer
│   ├── content-negotiation.md       RFC 7231 — quando e como
│   ├── hubspot-implementation.md    Guia pratico HubSpot
│   ├── express-implementation.md    Guia pratico Express/Node.js
│   └── aeo-grader-methodology.md    Metodologia audit (3 LLMs + 50 prompts)
│
├── playbooks/                  Playbooks operacionais
│   ├── hubspot-aeo-playbook.md      848 linhas
│   └── express-aeo-playbook.md      921 linhas
│
├── templates/                  Templates reutilizaveis
│   ├── llms.txt
│   ├── agent-card.json              A2A-compatible
│   ├── sitemap-aeo.json
│   ├── robots-aeo.txt
│   └── aeo-audit-checklist.md
│
├── cases/                      Portfolio de implementacoes reais
│   ├── README.md                    Indice de 7 cases
│   ├── clearsale-experian.md        57 pags, HubSpot, origem framework v2
│   ├── dot-digital-group.md         32 pags, Express, primeiro Commerce Layer
│   ├── apgar.md                     32 pags, clone DOT, EdTech EU
│   ├── opencadd.md                  16 specs (blueprint antes do prototipo)
│   ├── soenergy.md                  3 pags + proposta B2B (Commerce Layer modulo)
│   ├── quave-one.md                 Content Negotiation RFC 7231
│   └── pulse.md                     Audit devastador (benchmark metodologia)
│
├── learnings/
│   └── AEO-LEARNINGS.md         19 learnings cross-project consolidados
│
├── assets/
│   └── aeo-6-layers-diagram.md  Diagrama das 6 camadas
│
├── src/                        CLI implementation (TypeScript)
│   ├── core/                        ScoringEngine, types, constants
│   ├── auditors/                    7 auditors (um por camada — L6 add v2.1)
│   ├── providers/                   Http, Playwright, Firecrawl
│   ├── adapters/                    HubSpot, Express, plugin registry
│   ├── reporters/                   HTML reporter (EPIC Reporting style)
│   ├── generators/                  Templates pre-preenchidos
│   ├── kit/                         Component kit (7 reusable functions)
│   ├── cli/                         Commander subcommands
│   └── utils/
│
├── tests/                      Vitest — 434 tests, 30 files
├── calibration/                Expected scores por cliente
├── dist/                       Build output (tsup)
└── package.json                npm @epic-digital/aeo
```

---

## Parte 8 — Autoria e versao

**Framework:** AEO Framework v2.1 (7 camadas — 6 passive + 1 active handoff)
**Origem:** ClearSale/Experian, Fevereiro 2026
**Autor:** Fabio Munhoz / EPIC Digital
**Versao atual:** 2.1 (Mai 2026) — adicionou Layer 6 Agentic Experience
**Este documento:** v1.1, Maio 2026

**EPIC Digital** e consultoria de Arquitetura de Receita. AEO faz parte do portfolio de frameworks proprios da casa, junto a Revenue Intelligence e outros.

**Repositorio:** `epic-digital-mkt/aeo-framework` (privado)
**CLI npm:** `@epic-digital/aeo`
**Local:** `/epic/aeo/`

> "Quando um executivo perguntar ao ChatGPT quem resolve [problema X], o seu site precisa ser a resposta — e precisa deixar o agente agir."

---

## English version

### Part 1 — Thesis: Why AEO Exists

B2B executives no longer start at Google. They start at ChatGPT, Perplexity, Gemini or Copilot. Keywords became full-sentence questions in context:

- "Who are the best providers of [service X]?"
- "Compare [company A] with [company B]"
- "How much does [solution Y] cost for a 500-employee company?"

A new layer of triage sits between buyer and supplier: **the answer engine's response**. If you're not in the answer, you don't exist.

Our audits show most B2B sites are unprepared:

| Client | ChatGPT | Perplexity | Gemini |
|--------|---------|------------|--------|
| DOT Digital Group | 50/100 | 76/100 | 50/100 |
| Pulse Experiential Travel | 33/100 | 60/100 | 51/100 |

Perplexity scores higher because it searches in real time. ChatGPT and Gemini depend on training data — and training data ignores sites that aren't machine-citable.

When most players are invisible, **showing up in the answer is disproportionate advantage**. This is AEO's category-leap window — similar to SEO's advantage window in 2005-2010 before it commoditized.

### Part 2 — The 7 Layers (v2.1)

```
Layer 0  DISCOVERY          robots.txt + llms.txt + /.well-known/
Layer 1  STRUCTURED DATA    JSON-LD + potentialAction
Layer 2  SEMANTIC HTML      Headings + landmarks + microdata
Layer 3  NARRATIVE BLOCKS   TL;DR + FAQ + citable content
Layer 4  COMMERCE LAYER     Agent Card + API endpoints + M2M transactions
Layer 5  MEASUREMENT        Agent analytics + token benchmarks
Layer 6  AGENTIC EXPERIENCE Open-in-LLM + Copy Page + .md companion (NEW v2.1)
```

| Machine | Layers | Example |
|---------|--------|---------|
| Search crawler | 0, 1, 2 | Googlebot |
| AI crawler | 0, 1, 2, 3 | GPTBot, ClaudeBot |
| RAG / retrieval | 2, 3 | Embeddings, vector search |
| AI agent | 0, 4 | ChatGPT Actions, MCP tools, A2A |
| Internal analytics | 5 | Agent dashboards |
| Human → LLM handoff | 6 | Open in ChatGPT/Claude/Perplexity buttons |

**Layer 6 — Agentic Experience (NEW v2.1):** lets a human hand the page off to an active LLM in **one click** — closing the loop between passive discoverability (L0-L5) and active consumption by AI assistants. Unlike the other layers, L6 acts on the site's UX (buttons, dropdowns, link tags) rather than data infrastructure. Inspired by shadcn/ui, Vercel docs, and Anthropic docs. **BREAKING in v2.1:** LAYER_WEIGHTS rebalanced to fit L6 at 10% — v2.0 scores are NOT comparable.

### Part 3 — Commerce Layer as the Differentiator

Commerce Layer graduated from "Layer 4" to a standalone product — the **EPIC TECH module** in global B2B proposals (SoEnergy, Apgar, ClearSale).

Conceptually: Layers 0-3 make the site **readable** by machines. Layer 4 makes the site **actionable**. That's the same magnitude of shift as brochure-to-e-commerce in the early 2000s — except the buyer is now a machine.

Market context: **Google A2A Protocol** (April 2025, 150+ orgs), **MCP** (Anthropic, Nov 2024), **RFC 7231 Content Negotiation**, **llms.txt** spec.

Anatomy:
1. **Agent Card** (`/.well-known/agent-card.json`) — A2A-compatible manifest
2. **AEO Sitemap** (`sitemap-aeo.json`) — machine-readable index
3. **JSON Endpoints** (`/api/aeo/{page}.json`) — structured data, no HTML (~85% token savings)
4. **Transactional endpoints** — POST `/api/quote-request`, `/api/demo`, `/api/estimate`, `/api/recommend`
5. **`<link rel="alternate">`** in HTML pointing to the JSON version

| | Today | With Commerce Layer |
|-|-------|---------------------|
| ChatGPT asks about you | Maybe cites | Cites with structured data |
| Agent looks for supplier | Doesn't find | Finds via Agent Card |
| Agent wants quote | Impossible | POST /api/quote-request |
| Agent compares prices | Fragile scraping | Dedicated JSON endpoint |

Stack compatibility: Express 100% (native), HubSpot ~80% (tier-aware serverless), Static ~40% (no dynamic endpoints).

### Part 4 — EPIC Methodology

```
DEVASTATING AUDIT  →  PROPOSAL  →  IMPLEMENTATION  →  MEASUREMENT
```

**Devastating but factual** audit: HubSpot AEO Grader (3 LLMs scored /100) + 50 manual prompts + 6-layer scoring (0-2 each, total /10). Body is purely factual — **no recommendations in the report**. Recommendations go in the separate proposal. Generates urgency without feeling like a pitch.

**Implementation** via `@epic-digital/aeo` CLI: `audit`, `site`, `report`, `generate` (with `agentic` subcommand in v2.1+), `compare`. 3 providers (HTTP, Playwright, Firecrawl). 2 adapters (HubSpot tier-aware, Express) + plugin registry. 76 checks total in v2.1 (66 in v2.0 + 10 new L6 checks). `aeo audit` and `aeo site` now emit `.md` companions alongside `.html` reports for LLM-friendly handoff.

**Measurement**: logs segmented by AI User-Agent, quarterly AEO Grader, citation dashboards, token benchmarks. Goal: prove deltas.

### Part 5 — Evidence (7 cases)

7 real AEO implementations Feb-Mar 2026, ~150+ pages, 2 validated stacks. See [cases/](cases/) for each.

### Part 6+ — Repository Navigation

See Parte 6 and Parte 7 above (Portuguese). Repository structure is language-agnostic.

---

*EPIC Digital — Revenue Architecture consultancy. Framework by Fabio Munhoz. First case: ClearSale (clear.sale), February 2026.*

---

*Generated 2026-05-17. Rendered HTML version: https://epic.digital/aeo (password protected).*
*Repository: epic-digital-mkt/aeo-framework. CLI: `npm i -g @epic-digital/aeo` then `aeo audit <url>`.*