marketing: migra superfície SEO para OpenSEO (motor único)

As skills de SEO assentavam em quatro dependências, nenhuma operacional: SEO Tools API (localhost:3000, pasta inexistente em disco), Ahrefs MCP (nunca esteve em config), gsc e lighthouse (em disabledServers). Os seis passos da /seo-audit e o workflow inteiro da /seo-report apontavam para tooling morto — não eram executáveis. - seo-audit v3.0: ordem por custo (grátis → lote pago → unitário pago), gate de mercado (PT = 2620/pt) e gate de maxPages - seo-report v3.0: cobertura de crawl obrigatória no entregável - ferramentas-api.md: inventário das 24 ferramentas OpenSEO + tabela de migração endpoint a endpoint - implementacao-tecnica.md: striking distance, desperdício e filtro de ruído do GSC em código - seo-specialist v3.0: primary_mcps [openseo], bloco de MCPs desligados, FID → INP nos Core Web Vitals maxPages tem default 50: descomplicar.pt auditado com o default deu 25 URLs e 92 issues sem críticos; com maxPages 600 deu 1337 issues e 9 críticos. Documentado como gate — a fase Search Console dimensiona o crawl. Limitações declaradas nas skills: get_audit_issues devolve contagens sem URLs pela bridge MCP (structuredContent.issues não é entregue) e o whoami não expõe saldo de créditos em self-hosted.
2026-07-30 22:39:40 +01:00
parent f90ba6ec76
commit 2d05873642
9 changed files with 545 additions and 497 deletions
@@ -5,22 +5,21 @@ description: >
  Use for SEO strategy, keyword research, technical SEO audits, on-page optimization, Core Web Vitals, rankings monitoring, link building, SERP analysis,
  or when user mentions "SEO", "keywords", "rankings", "tráfego orgânico", "SERP", "technical SEO", "link building", "Google", "optimização", "indexação".
 author: Descomplicar® Crescimento Digital
-version: 2.0.0
+version: 3.0.0
 category: business
 model: sonnet
 tools: Read, Glob, Grep, ToolSearch

 # Dependencies
-# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube
-# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar.
+# OpenSEO é o motor único de SEO. O stack antigo (gsc, lighthouse, Ahrefs,
+# SEO Tools API) está desligado ou não existe — não o invocar.
 primary_mcps:
-  - gsc
-  - google-analytics
-  - desk-crm-v3
+  - openseo
 recommended_mcps:
-  - lighthouse
+  - chrome-devtools
+  - google-workspace
  - context7
-allowed-mcps: ssh-unified, google-workspace, gsc, lighthouse, google-analytics, tavily
+allowed-mcps: openseo, chrome-devtools, google-workspace, context7
 skills:
  - _core
  - seo-audit
@@ -31,18 +30,18 @@ desk_task: 1516

 # SEO Specialist Descomplicar

-Especialista em optimizacao para motores de busca, focado em crescimento de trafego organico atraves de SEO tecnico, optimizacao de conteudo e estrategias de link building.
+Especialista em optimização para motores de busca, focado em crescimento de tráfego orgânico através de SEO técnico, optimização de conteúdo e estratégias de link building.

 ## Responsabilidades
- Conduzir pesquisa de keywords e analise competitiva
- Optimizar elementos on-page (titulos, meta descriptions, headers)
- Melhorar SEO tecnico (velocidade, crawlability, indexacao, Core Web Vitals)
- Desenvolver estrategias de link building e autoridade de dominio
- Monitorizar rankings e reportar metricas de trafego organico
+- Conduzir pesquisa de keywords e análise competitiva
+- Optimizar elementos on-page (títulos, meta descriptions, headers)
+- Melhorar SEO técnico (velocidade, crawlability, indexação, Core Web Vitals)
+- Desenvolver estratégias de link building e autoridade de domínio
+- Monitorizar rankings e reportar métricas de tráfego orgânico

 ## Knowledge Sources (Consultar SEMPRE)

-### NotebookLM (Primario - usar PRIMEIRO)
+### NotebookLM (Primário — usar PRIMEIRO)

 ```
 mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf5655" query:"keywords rankings optimizacao SERP"
@@ -51,13 +50,13 @@ mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf565
 ## System Prompt

 ### Papel
-Especialista SEO responsavel por aumentar trafego organico atraves de optimizacao tecnica, keyword research e estrategias de link building alinhadas com algoritmos 2026.
+Especialista SEO responsável por aumentar tráfego orgânico através de optimização técnica, keyword research e estratégias de link building alinhadas com algoritmos 2026.

-### Regras Obrigatorias
-1. SEMPRE priorizar Core Web Vitals (LCP, FID, CLS)
+### Regras Obrigatórias
+1. SEMPRE priorizar Core Web Vitals (LCP < 2,5s, INP < 200ms, CLS < 0,1 — o INP substituiu o FID)
 2. NUNCA usar black-hat SEO (keyword stuffing, PBNs, cloaking)
-3. Keyword research baseado em search intent, nao volume
-4. E-E-A-T obrigatorio (Experience, Expertise, Authority, Trust)
+3. Keyword research baseado em search intent, não volume
+4. E-E-A-T obrigatório (Experience, Expertise, Authority, Trust)
 5. Mobile-first indexing (testar sempre em mobile)
 6. Structured data (Schema.org) para rich snippets

@@ -69,73 +68,74 @@ Especialista SEO responsavel por aumentar trafego organico atraves de optimizaca
 ## Workflows

 ### Workflow 1: Keyword Research
-1. Seed keywords: Brainstorm com cliente, analise concorrentes
-2. Expansion: Google Keyword Planner, Ahrefs, SEMrush
-3. Intent mapping: Informacional, navegacional, transaccional
-4. Difficulty: Avaliar competicao (DA de top 10)
-5. Priorization: Quick wins (low difficulty, medium volume)
-6. Mapping: Atribuir keywords a paginas/conteudos
+1. **Search Console primeiro** (grátis): `get_search_console_performance` — o que já posiciona
+2. Striking distance: filtrar pos 4-20 com impressões ≥ 25 (o GSC não filtra por posição)
+3. Hidratar: `get_keyword_metrics` — até 700 keywords/chamada, volume + KD + intenção
+4. Expandir (só se necessário): `research_keywords`, 1-5 seeds
+5. Priorizar: quick wins (KD baixo, volume médio, intenção comercial)
+6. Mapear keywords a páginas; guardar com `save_keywords`

 ### Workflow 2: Technical SEO Audit
-1. Crawl: Screaming Frog, Google Search Console
-2. Core Web Vitals: PageSpeed Insights, Lighthouse
-3. Indexation: Sitemap, robots.txt, canonicals, redirects
-4. Structure: URL structure, internal linking, breadcrumbs
-5. Mobile: Responsive design, tap targets, viewport
-6. Schema: Structured data validation (Google Rich Results Test)
+1. GSC por página: conta quantas páginas têm procura real
+2. `run_site_audit` com **maxPages ≥ páginas do GSC + 25%** (o default 50 cega a auditoria)
+3. `get_audit_status` em poll até "completed"; depois `get_audit_issues` por severidade
+4. Priorizar issues pelas páginas com impressões — nunca por contagem bruta
+5. Core Web Vitals das páginas que importam: `chrome-devtools → performance_start_trace`
+6. Indexação: `inspect_urls` (até 10 URLs)

 ### Workflow 3: On-Page Optimization
 1. Title tag: Keyword + brand, <60 chars
 2. Meta description: CTR-focused, <160 chars
 3. Headers: H1 (1x), H2/H3 hierarchy com keywords
 4. Content: E-E-A-T, >1000 words para pillar content
-5. Images: Alt text descritivo, compressao, lazy loading
-6. Internal links: Link para conteudo relacionado
+5. Images: Alt text descritivo, compressão, lazy loading
+6. Internal links: Link para conteúdo relacionado

 ## MCPs Relevantes
- ssh-unified: Optimizacoes tecnicas em servidores WP
- google-workspace: GSC data, relatorios em Sheets
+- **openseo**: motor único — crawl, Search Console, keywords, SERP, backlinks
+- **chrome-devtools**: Core Web Vitals e Lighthouse por página
+- **google-workspace**: exportar relatórios para Docs/Sheets

-## Metricas Chave
+## Métricas Chave
 - **Organic Traffic**: Visitantes de search engines
- **Rankings**: Posicoes keywords alvo (top 3 = sucesso)
+- **Rankings**: Posições das keywords alvo (top 3 = sucesso)
 - **CTR**: Click-through rate em SERPs
- **Core Web Vitals**: LCP <2.5s, FID <100ms, CLS <0.1
- **Backlinks**: Numero e qualidade (DA dos sites)
+- **Core Web Vitals**: LCP < 2,5s, INP < 200ms, CLS < 0,1
+- **Backlinks**: Número e qualidade (DA dos sites)

-## Colaboracao
+## Colaboração
 - Reports to: Digital Marketing Manager
 - Colabora com: Content Manager, Copywriter, Web Designer, WordPress Developer

 ## Your Available MCPs

 ### Primary MCPs (Your Domain)
-✓ **ssh-unified** (infra)
-  - SSH, SFTP, servidor management
-  - Usage: `mcp__ssh-unified__*`
+✓ **openseo** (motor SEO)
+  - Crawl e issues, Search Console, keywords, SERP, backlinks, rank tracking
+  - Ferramentas grátis primeiro; pagas só depois de esgotar as grátis
+  - Mercado PT obrigatório: `locationCode: 2620`, `languageCode: "pt"`

-✓ **google-workspace** (integration)
-  - Email, calendário, docs, drive
-  - Usage: `mcp__google-workspace__*`
+✓ **chrome-devtools** (performance)
+  - `lighthouse_audit`, `performance_start_trace` — CWV reais por página

 ### Recommended for seo
- **gsc** - Google Search Console
- **lighthouse** - Performance audits
- **google-analytics** - Google Analytics 4
- **tavily** - AI-powered search API - web search optimizado para LLMs
+- **google-workspace** — Exportar relatórios (Docs, Sheets)
+- **context7** — Documentação de bibliotecas e frameworks

-### All Available (32 total)
-desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, imap, outline-api, youtube-research, youtube-uploader, mcp-time, mem0, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, elevenlabs, magic, vimeo, design-systems, replicate
+### Desligados — NÃO invocar
+`gsc`, `lighthouse`, `google-analytics` estão em disabledServers. `Ahrefs` e a
+`SEO Tools API` (localhost:3000) não existem. Se precisares de um deles, pedir
+activação via `/mcp` — nunca contornar com bash/curl.

 **Discovery:** Use ToolSearch to find specific tools.
 **Example:** `ToolSearch("ssh upload")` finds SSH upload tools.
 ## Your Available Skills

 ### Primary Skills (Your Domain)
-✓ **/seo-audit** - Auditoria SEO completa usando todas as ferramentas instaladas - Lighthouse, SEO 
+✓ **/seo-audit** - Auditoria SEO completa com dados reais via OpenSEO (crawl, GSC, SERP, backlinks)
  - Invoke: `/seo-audit`

-✓ **/seo-report** - Relatório SEO completo com dados de múltiplas fontes (Lighthouse, GSC, SEO Tools
+✓ **/seo-report** - Relatório SEO para cliente com OpenSEO, exportado para Google Docs
  - Invoke: `/seo-report`

 ### Recommended for seo
@@ -1,202 +1,208 @@
 ---
 name: seo-audit
-description: Auditoria SEO completa com recomendacoes de optimizacao. Analisa SEO tecnico, conteudo, backlinks e desempenho.
+description: Auditoria SEO completa com dados reais via OpenSEO (crawl, Search Console, SERP, backlinks, keywords). Analisa SEO técnico, conteúdo, autoridade e desempenho, e prioriza por retorno. Usar quando "auditoria SEO", "audit", "analisar site", "Core Web Vitals", "Search Console", "striking distance", "porque não tenho tráfego".
 ---

-# SEO Audit - Auditoria Completa
+# SEO Audit — Auditoria Completa (OpenSEO)

-Skill para realizar auditorias SEO completas usando o stack de ferramentas instalado. Best practices 2026.
+Auditoria SEO com dados reais. **Motor único: OpenSEO** (`seo.descomplicar.pt`), que substituiu o stack antigo (SEO Tools API + Ahrefs + GSC MCP + Lighthouse MCP) — ver `references/ferramentas-api.md` para a tabela de migração.

 ---

-## Contexto NotebookLM
+## Regra zero — a ordem é económica, não estética

-ANTES de executar, consultar notebook para contexto especializado:
+O OpenSEO tem ferramentas **grátis** e ferramentas **que gastam créditos**. Executar pela ordem errada gasta dinheiro a produzir conclusões que as ferramentas grátis já davam.

-| Notebook | ID | Consultar quando |
-|----------|-----|-----------------|
-| Marketing Digital PT | `4c595973` | Sempre |
+| Fase | Ferramentas | Custo | Porquê nesta ordem |
+|---|---|---|---|
+| 1 | `get_search_console_performance`, `inspect_urls` | **grátis** | Dados de primeira mão. Diz o que já posiciona e quais páginas importam |
+| 2 | `run_site_audit`, `get_audit_issues`, `get_audit_pages` | **grátis** | Estado técnico. O dimensionamento do crawl depende da fase 1 |
+| 3 | `get_keyword_metrics` | pago (lote) | Hidrata até 700 keywords conhecidas de uma vez — a melhor relação valor/crédito |
+| 4 | `get_ranked_keywords`, `get_domain_overview`, `get_backlinks_overview` | pago | Contexto competitivo |
+| 5 | `get_serp_results`, `find_serp_competitors` | pago (~30-60/keyword) | Só nas keywords que sobreviveram à filtragem |

-```
-mcp__notebooklm__notebook_query({
-  notebook_id: "4c595973-ba10-420a-a3bf-e4389e424ad3",
-  query: "<adaptar ao contexto — ex: auditoria SEO tecnico, Core Web Vitals, backlinks, E-E-A-T>"
-})
-```
-
-**Procedimento relacionado:** `PROC-DMARC-Email-Entregabilidade.md` -- consultar quando a auditoria envolve email deliverability.
+**Nunca começar pela fase 3 ou acima.** As fases 1-2 resolvem a maioria das auditorias sem gastar um crédito.

 ---

-## Quando Usar
+## Pré-voo obrigatório (3 verificações, 30 segundos)

- Auditar um site completo (tecnico + conteudo + performance)
- Verificar Core Web Vitals e ranking factors
- Analisar backlinks e autoridade de dominio
- Obter dados reais do Google Search Console
- Identificar oportunidades de optimizacao
- Comparar com concorrencia
+```
+1. openseo → whoami            → confirma ligação, org, modo
+2. openseo → list_projects     → obtém projectId E o mercado do projecto
+3. confirmar mercado           → PT = locationCode 2620, languageCode "pt"
+```
+
+**GATE — mercado.** Se o projecto estiver em `2840/en` (EUA/inglês, que é o default) e o cliente for português, **todas** as chamadas pagas devolvem dados do mercado errado. Ou se corrige o mercado do projecto, ou se passa `locationCode`/`languageCode` explicitamente em **cada** chamada. Um esquecimento = créditos gastos em lixo.
+
+> `locationCode: 2620` = Portugal — confirmado empiricamente (SERP devolve domínios `.pt`). Não inventar códigos: se houver dúvida, correr uma query de teste e validar pelos resultados.

 ---

-## Google Updates 2026
+## Fase 1 — Search Console primeiro (grátis, é o mapa)

-### Core Algorithm Updates
+```
+openseo → get_search_console_performance
+  dimensions: ["query"]   dateRange: "last_3_months"   rowLimit: 1000
+openseo → get_search_console_performance
+  dimensions: ["page"]    dateRange: "last_3_months"   rowLimit: 1000
+```

-| Update | Data | Impacto |
-|--------|------|---------|
-| **Helpful Content Q1** | Jan 2026 | Penaliza conteudo AI de baixa qualidade |
-| **Core Web Vitals 3.0** | Mar 2026 | INP substitui FID, thresholds mais rigorosos |
-| **E-E-A-T Focus** | Q1-Q2 | Experiencia pratica obrigatoria |
-| **Mobile-First Index** | Universal | 100% dos sites |
+Paginar com `startRow` enquanto o cabeçalho disser `more available`.

-### Novos Ranking Factors 2026
+### As três armadilhas do GSC

-1. **INP (Interaction to Next Paint)** -- Bom: < 200ms | Medio: 200-500ms | Mau: > 500ms
-2. **E-E-A-T** -- Autor identificado com bio, credenciais verificaveis, experiencia real
-3. **Page Experience Signals** -- HTTPS obrigatorio, intrusive interstitials penalizados
+**1. Vista por query ≠ vista por página.** O GSC anonimiza queries raras, por isso os totais por query são sempre **muito menores** que os totais por página. A vista por **página** é a real; usar essa para números globais.
+
+**2. O GSC não filtra por posição.** `striking distance` tem de ser filtrado do lado do cliente, depois de puxar as linhas.
+
+**3. Há lixo nas queries.** Colagens de relatórios do Google Ads, operadores `site:`, strings com mojibake. Filtrar antes de contar, ou as métricas mentem.
+
+```python
+def is_noise(k):
+    return ('ativado' in k and 'correspond' in k) or k.startswith('-site:') \
+           or k.startswith('=') or len(k) > 90 or '0,00' in k
+```
+
+### O que extrair
+
+| Métrica | Cálculo | Leitura |
+|---|---|---|
+| CTR global | cliques ÷ impressões (vista por página) | < 1% = problema de captação, não de ranking |
+| Distribuição por posição | buckets 1-3 / 4-10 / 11-20 / 21-50 / 51+ | Impressões concentradas em 21+ = visibilidade inútil |
+| Branded vs não-branded | queries com o nome da marca vs resto | Se só a marca converte, o SEO não está a trabalhar |
+| **Striking distance** | pos 4-20 **e** impressões ≥ 25 | **É aqui que está o retorno** |
+| Desperdício | pos > 40 **e** impressões ≥ 300 | Páginas com procura real enterradas |
+
+### O sinal mais accionável de todos
+
+**Posição 4-10 com CTR perto de 0%.** Não é problema de ranking — o site está na primeira página. É o **título e a meta description** a não convencerem. Cruzar esta lista com os issues `missing-meta-description` e `title-too-long` da fase 2: a intersecção é a lista de trabalho, por ordem.

 ---

-## Workflow de Auditoria Completa
-
-### Passo 1: Analise Tecnica Basica (3 min)
+## Fase 2 — Auditoria técnica (grátis)

 ```
-1. SEO Tools API -> /seo-audit -> Meta tags, headings, estrutura HTML
-2. SEO Tools API -> /page-speed-analyzer -> Velocidade, sugestoes
-3. Lighthouse -> run_audit -> Performance, SEO, Accessibility scores
+openseo → run_site_audit
+  url: "<url>"   maxPages: <N>   runLighthouse: true
+openseo → get_audit_status      (poll até "completed")
+openseo → get_audit_issues      (severity: critical → warning → info)
 ```

-**Checklist Critico:**
- [ ] Meta title (50-60 chars)
- [ ] Meta description (150-160 chars)
- [ ] H1 unico com keyword
- [ ] Canonical URL definido
- [ ] Robots.txt acessivel
- [ ] Sitemap.xml presente
- [ ] HTTPS activo
- [ ] Mobile-friendly
+### GATE — `maxPages` (o erro que cega a auditoria)

-### Passo 2: Core Web Vitals (2 min)
+**`maxPages` tem default 50.** Um site de 600 páginas auditado com o default devolve um relatório limpo e falso: descreve 8% do site e omite exactamente o hub de conteúdo que gera o tráfego.
+
+**Regra:** `maxPages` ≥ número de páginas com impressões no GSC (fase 1), com folga de ~25%. Por isso é que a fase 1 vem primeiro — é ela que dimensiona o crawl.
+
+> Caso real (descomplicar.pt, 07-2026): auditoria com default 50 → 25 URLs únicos, 92 issues, **zero críticos**, nenhuma das 119 páginas `/guia-*`. Relançada com `maxPages: 600` → **1337 issues, 9 críticos**. O relatório "limpo" descrevia 4% do site.
+
+### Prioridade dos issues
+
+| Severidade | Tipos | Acção |
+|---|---|---|
+| **critical** | `broken-internal-link`, `blocked-page`, `server-error`, `broken-page` | Corrigir já — sangram autoridade e crawl budget |
+| **warning** | `missing-h1`, `missing-meta-description`, `duplicate-content`, `multiple-h1`, `duplicate-title` | Priorizar pelas páginas com impressões (fase 1) |
+| **info** | `title-too-long`, `noindex-page`, `slow-response`, `heading-order-skip` | Lote; só vale a pena onde há procura |
+
+**Nunca tratar a lista de issues por ordem de contagem.** 300 metas em falta em páginas sem impressões valem menos que 6 em páginas na posição 8. A fase 1 é que ordena a fase 2.
+
+### Limitação conhecida — issues sem URL
+
+`get_audit_issues` e `get_audit_pages` devolvem **apenas contagens agregadas** através da bridge MCP. As linhas por URL vivem em `structuredContent.issues`, que a bridge não entrega; `get_audit_pages` trunca a listagem em ~25 linhas independentemente do `limit`.
+
+**Contorno:** o campo `details.mcpMeta.url` da resposta traz o link do relatório na UI. Entregar esse link ao humano para os URLs concretos:
+```
+https://seo.descomplicar.pt/p/<projectId>/audit?auditId=<auditId>
+```
+Declarar esta limitação no relatório — não fingir que se verificaram URLs que não se viram.
+
+### Core Web Vitals por página
+
+`run_site_audit` com `runLighthouse: true` corre Lighthouse numa amostra (até 20 páginas). Para uma página específica, usar `chrome-devtools`:

 ```
-1. Lighthouse -> get_core_web_vitals -> LCP, INP, CLS (mobile + desktop)
-2. Lighthouse -> compare_mobile_desktop -> Identificar gaps
-3. Lighthouse -> get_lcp_opportunities -> Sugestoes optimizacao
+chrome-devtools → lighthouse_audit          (SEO, acessibilidade, best practices)
+chrome-devtools → performance_start_trace   (LCP, INP, CLS reais)
 ```

-**Thresholds 2026:**
+**Thresholds 2026:** LCP < 2,5s · **INP** < 200ms · CLS < 0,1
+(INP substituiu o FID — se algum documento ainda disser FID, está desactualizado.)

-| Metrica | Bom | Necessita Melhoria | Mau |
-|---------|-----|-------------------|-----|
-| **LCP** | < 2.5s | 2.5-4s | > 4s |
-| **INP** | < 200ms | 200-500ms | > 500ms |
-| **CLS** | < 0.1 | 0.1-0.25 | > 0.25 |
+---

-### Passo 3: Analise de Conteudo (3 min)
+## Fase 3 — Hidratar keywords (pago, lote)

 ```
-1. SEO Tools API -> /content-optimization -> On-page SEO, keyword density
-2. SEO Tools API -> /internal-linking -> Estrutura links internos
-3. SEO Ahrefs -> keyword_generator -> Keywords relacionadas, volume, KD
+openseo → get_keyword_metrics
+  keywords: [<as keywords em striking distance da fase 1>]
+  locationCode: 2620   languageCode: "pt"
 ```

-**Checklist E-E-A-T:**
- [ ] Autor identificado com bio
- [ ] Credenciais verificaveis
- [ ] Data publicacao/actualizacao
- [ ] Fontes citadas (links externos autoritativos)
- [ ] Experiencia real demonstrada
+Até **700 keywords numa só chamada** — volume, dificuldade (KD), intenção, CPC, tendência. É a forma barata de priorizar. Só depois disto se decide onde vale a pena competir.

-### Passo 4: Backlinks e Autoridade (2 min)
+Guardar o que sobreviver: `openseo → save_keywords` (grátis, idempotente).
+
+---
+
+## Fase 4 — Contexto competitivo (pago)

 ```
-1. SEO Tools API -> /backlink-checker -> Backlinks basicos, DR/UR
-2. SEO Ahrefs -> get_backlinks_list -> Lista detalhada (DR, anchor text)
-3. SEO Ahrefs -> get_traffic -> Trafego estimado mensal
-```
-
-**Metricas Autoridade:**
- **DR (Domain Rating)**: 0-100 (forca backlink profile)
- **UR (URL Rating)**: 0-100 (forca pagina especifica)
- **Backlinks**: Quantidade + qualidade (DR > 30)
- **Referring Domains**: Numero de dominios unicos
-
-### Passo 5: Dados Reais GSC (3 min)
-
-```
-1. GSC -> get_search_analytics -> Queries, impressoes, CTR real (ultimos 90 dias)
-2. GSC -> check_indexing_issues -> Problemas de indexacao
-3. GSC -> get_sitemaps -> Status sitemaps submetidos
-```
-
-**Metricas GSC a Analisar:**
- **Impressoes vs Cliques**: CTR medio > 2%
- **Posicao media**: Top 3 para keywords principais
- **Cobertura**: % paginas indexadas vs submetidas
- **Mobile Usability**: Erros especificos mobile
-
-### Passo 6: Concorrencia (opcional, 2 min)
-
-```
-SEO Tools API -> /competitor-analysis -> Comparar com 2-3 concorrentes
- Keywords gap
- Backlinks gap
- Content gap
+openseo → get_domain_overview        (tráfego orgânico estimado, nº keywords, backlinks)
+openseo → get_ranked_keywords        (onde o domínio posiciona, por mercado)
+openseo → get_backlinks_overview     (~50 créditos por domínio)
+openseo → get_backlinks_profile      (linhas detalhadas: anchors, dofollow, spam)
 ```

 ---

-## Propriedades GSC Disponiveis
+## Fase 5 — SERP (pago, por último)

 ```
-sc-domain:descomplicar.pt
-https://emanuelalmeida.pt/
-https://carstuff.pt/
-https://solarfvengenharia.com/
-https://aquisevende.pt/
-https://alojadamaria.com/
-https://e-commerce.descomplicar.pt/
+openseo → get_serp_results       (1-10 keywords por chamada, ~30-60 créditos cada)
+openseo → find_serp_competitors  (quem compete num conjunto de keywords)
 ```

---
+Ler a SERP como **estrutura**, não como lista: se o top-10 estiver cheio de directórios e artigos "melhores X", a intenção é comparativa e uma homepage não entra — é preciso uma página de comparação. Se estiver cheio de homepages de concorrentes, é disputa de marca.

-## Notas Importantes
-
-### Requisitos
- **SEO Tools API** deve estar a correr: `~/mcp-servers/seo-tools-api/start.sh`
- **GSC** requer autenticacao OAuth na primeira utilizacao
- **GA** requer ADC credentials configuradas
-
-### Limitacoes
- Ahrefs API tem rate limiting (100 req/day free tier)
- GSC data maximo: 16 meses historico
- Lighthouse scores variam +/- 5 pontos entre execucoes
+Local/Maps: `get_local_serp_results`, `search_local_businesses`, `get_google_business_questions`.

 ---

-## References (conteudo detalhado)
+## Custos — o que sabemos e o que não sabemos

-| Ficheiro | Conteudo |
-|----------|----------|
-| `references/template-relatorio-auditoria.md` | Template completo do relatorio com todas as seccoes e tabelas |
-| `references/ferramentas-api.md` | Endpoints SEO Tools API, Lighthouse MCP, Ahrefs, GSC, GA |
+`whoami` **não expõe saldo de créditos** em modo self-hosted (verificado antes e depois de uma chamada paga: output idêntico). Os `~30-60 créditos/keyword` são a **estimativa do schema**, não uma medição.
+
+**Consequência prática:** não há medidor no OpenSEO. O contador real vive na conta DataForSEO. Para lotes grandes, confirmar saldo aí primeiro. Nunca reportar custo consumido como facto — reportar como estimativa.

 ---

-## Anti-Patterns
+## Anti-patterns

- Auditar sem dados reais (nunca simular metricas)
- Ignorar gap mobile vs desktop
- Nao verificar se site esta no GSC antes de recolher dados
- Recomendacoes sem priorizacao (critico/importante/melhoria)
- Esquecer E-E-A-T na analise de conteudo
+- **Correr `run_site_audit` com o `maxPages` por omissão.** Produz relatórios limpos e falsos.
+- **Começar por ferramentas pagas.** O GSC é grátis e responde a metade das perguntas.
+- Usar totais por query como totais do site (o GSC anonimiza — usar a vista por página).
+- Priorizar issues por contagem em vez de por impressões da página afectada.
+- Correr chamadas pagas sem confirmar o mercado do projecto.
+- Apresentar contagens de issues como se fossem URLs verificados.
+- Auditar sem dados reais ou simular métricas.
+- Recomendações sem prioridade (crítico/importante/melhoria) e sem esforço estimado.

 ---

-**Versao:** 2.1.0 | **Autor:** Descomplicar
+## References

+| Ficheiro | Conteúdo |
+|---|---|
+| `references/ferramentas-api.md` | Inventário OpenSEO completo + tabela de migração do stack antigo |
+| `references/template-relatorio-auditoria.md` | Template do relatório com todas as secções e tabelas |
+
+---
+
+**Versão:** 3.0.0 | **Autor:** Descomplicar® | **Motor:** OpenSEO

 ## Healing Log
 <!-- Registo automático de erros e correcções nesta skill -->
+```jsonl
+{"date":"2026-07-30","issue":"Skill dependia de SEO Tools API (localhost:3000), Ahrefs MCP, GSC MCP e Lighthouse MCP — todos inexistentes ou desligados. Nenhum dos 6 passos era executável.","fix":"Reescrita completa sobre OpenSEO, com ordem por custo, gates de mercado e maxPages.","source":"auto"}
+```
@@ -1,75 +1,113 @@
-# Ferramentas e APIs - SEO Audit
+# Ferramentas SEO — OpenSEO

-## 1. SEO Tools API (http://localhost:3000)
+Motor único do SEO Descomplicar®. Substituiu integralmente o stack anterior.
+UI: `https://seo.descomplicar.pt` · Projecto default: `1e5ad4d6-a285-4fd3-9633-339abef4b6af`

-```bash
-# Auditoria basica
-curl "http://localhost:3000/seo-audit?url=URL"
+---

-# Velocidade PageSpeed Insights style
-curl "http://localhost:3000/page-speed-analyzer?url=URL"
+## 1. Migração — o que morreu e o que o substitui

-# Backlinks + DR/UR
-curl "http://localhost:3000/backlink-checker?url=URL"
+O stack antigo desta skill (v2.1.0) apontava para quatro dependências. **Nenhuma está operacional** (verificado 30-07-2026):

-# Rankings para keywords
-curl "http://localhost:3000/rank-checker?url=URL&keywords=keyword1,keyword2"
+| Dependência antiga | Estado real | Substituto OpenSEO |
+|---|---|---|
+| **SEO Tools API** `localhost:3000` | `~/mcp-servers/seo-tools-api/` **não existe em disco** | ver tabela abaixo |
+| **Ahrefs MCP** | nunca esteve em nenhuma config MCP | `get_backlinks_*`, `get_domain_overview`, `get_keyword_metrics` |
+| **GSC MCP** | em `disabledServers` | `get_search_console_performance`, `inspect_urls` |
+| **Lighthouse MCP** | em `disabledServers` | `run_site_audit` (`runLighthouse`) ou `chrome-devtools` |

-# Optimizacao conteudo on-page
-curl "http://localhost:3000/content-optimization?url=URL"
+### Endpoint a endpoint

-# Internal linking structure
-curl "http://localhost:3000/internal-linking?url=URL"
+| Antigo | Novo | Nota |
+|---|---|---|
+| `/seo-audit` | `run_site_audit` + `get_audit_issues` | Atenção ao `maxPages` |
+| `/page-speed-analyzer` | `run_site_audit` com `runLighthouse: true` | Amostra até 20 páginas |
+| `/content-optimization` | `get_audit_issues` (`thin-content`, `title-*`, `meta-description-*`) | |
+| `/internal-linking` | `get_audit_issues` (`orphan-page`, `broken-internal-link`, `no-outgoing-links`) | |
+| `/backlink-checker` | `get_backlinks_overview` | |
+| `/rank-checker` | `get_rank_tracker` (grátis) ou `get_ranked_keywords` (pago) | |
+| `/competitor-analysis` | `find_serp_competitors` + `get_domain_overview` | |
+| `/sitemap-generator` | **sem equivalente** | Usar plugin WP ou gerar à mão |
+| Ahrefs `keyword_generator` | `research_keywords` (novas) / `get_keyword_metrics` (conhecidas) | |
+| Ahrefs `get_backlinks_list` | `get_backlinks_profile` | |
+| Ahrefs `get_traffic` | `get_domain_overview` | Estimado |
+| Lighthouse `run_audit` | `chrome-devtools → lighthouse_audit` | Por página |
+| Lighthouse `get_core_web_vitals` | `chrome-devtools → performance_start_trace` | LCP/INP/CLS reais |
+| GSC `get_search_analytics` | `get_search_console_performance` | |
+| GSC `check_indexing_issues` | `inspect_urls` | Até 10 URLs por chamada |
+| GSC `get_sitemaps` | **sem equivalente** | Ver na UI do Search Console |

-# Sitemap XML generator
-curl "http://localhost:3000/sitemap-generator?url=URL"
+---

-# Analise concorrencia
-curl "http://localhost:3000/competitor-analysis?url=URL&competitors=site1.com,site2.com"
-```
+## 2. Inventário OpenSEO (24 ferramentas)

-## 2. Lighthouse MCP
+### Grátis — não tocam no DataForSEO

-| Tool | Funcao | Output |
-|------|--------|--------|
-| `run_audit(url)` | Auditoria completa | Performance, SEO, A11y, Best Practices |
-| `get_performance_score(url)` | Score performance | 0-100 |
-| `get_core_web_vitals(url)` | LCP, INP, CLS | Mobile + Desktop |
-| `get_accessibility_score(url)` | Acessibilidade | 0-100 + issues |
-| `get_seo_analysis(url)` | Analise SEO tecnico | Meta, headings, indexabilidade |
-| `get_security_audit(url)` | Seguranca | HTTPS, mixed content, headers |
-| `compare_mobile_desktop(url)` | Comparacao | Diferencas performance |
-| `get_lcp_opportunities(url)` | Optimizacoes LCP | Preload, lazy load |
-| `find_unused_javascript(url)` | JS nao usado | Tamanhos, % savings |
+| Ferramenta | Função |
+|---|---|
+| `whoami` | Utilizador, org, modo, scopes. **Não mostra saldo em self-hosted** |
+| `list_projects` | Projectos + `projectId` + mercado default |
+| `create_project` | Novo projecto (nome, domínio, mercado) |
+| `run_site_audit` | Crawl same-origin, robots-aware. `maxPages` **default 50** |
+| `get_audit_status` | Progresso (fase, páginas, Lighthouse) |
+| `get_audit_issues` | Relatório priorizado. Filtros `severity`/`issueType` |
+| `get_audit_pages` | Páginas crawladas com dados SEO por página |
+| `get_search_console_performance` | Search Analytics: cliques, impressões, CTR, posição |
+| `inspect_urls` | URL Inspection do GSC (até 10 URLs): indexação, canónico |
+| `get_rank_tracker` | Configs de rank tracking + último snapshot |
+| `save_keywords` | Guardar keywords no projecto (idempotente) |
+| `list_saved_keywords` | Keywords guardadas + métricas em cache |

-## 3. SEO Ahrefs MCP (via API)
+### Pagas — consomem créditos

-| Tool | Funcao | Dados |
-|------|--------|-------|
-| `get_backlinks_list(domain)` | Lista backlinks | DR, UR, anchor text |
-| `keyword_generator(keyword, country)` | Ideias keywords | Volume, KD, CPC |
-| `get_traffic(domain)` | Trafego estimado | Visitas mensais, keywords |
-| `keyword_difficulty(keyword)` | Dificuldade keyword | 0-100 (KD score) |
+| Ferramenta | Custo aprox. | Função |
+|---|---|---|
+| `get_keyword_metrics` | lote | **Até 700 keywords/chamada**: volume, KD, intenção, CPC, tendência |
+| `research_keywords` | ~30-100/seed | 1-5 seeds → ideias novas + métricas |
+| `get_serp_results` | ~30-60/keyword | Google orgânico ao vivo, 1-10 keywords |
+| `find_serp_competitors` | pago | Domínios que competem num conjunto de keywords |
+| `get_ranked_keywords` | pago | Keywords onde um domínio posiciona, por mercado |
+| `get_domain_overview` | pago | Tráfego orgânico, nº keywords, backlinks, ref. domains |
+| `get_domain_keyword_suggestions` | pago | Lista detalhada de keywords de um domínio |
+| `get_backlinks_overview` | ~50/domínio, ~25/página | Resumo do perfil de backlinks |
+| `get_backlinks_profile` | pago | Linhas detalhadas: anchors, dofollow, spam, lost/broken |
+| `get_local_serp_results` | pago | Google Maps / Local Finder junto a coordenadas |
+| `search_local_businesses` | pago | Negócios locais perto de coordenadas |
+| `get_google_business_questions` | pago | Q&A de Google Business Profile |

-## 4. Google Search Console MCP
+---

-| Tool | Funcao | Dados Reais |
-|------|--------|-------------|
-| `list_properties` | Listar sites verificados | URLs properties |
-| `get_search_analytics(site, period)` | Queries, cliques, CTR | Ultimos 16 meses |
-| `inspect_url_enhanced(site, url)` | Inspeccionar URL | Indexacao, mobile usability |
-| `check_indexing_issues(site, urls)` | Problemas indexacao | Erros, avisos |
-| `get_sitemaps(site)` | Listar sitemaps | Status, URLs submetidos |
+## 3. Mercados

-## 5. Google Analytics MCP
+| Mercado | `locationCode` | `languageCode` |
+|---|---|---|
+| **Portugal** | `2620` | `pt` |
+| EUA (default do projecto) | `2840` | `en` |

-| Tool | Funcao | Metricas |
-|------|--------|----------|
-| `get_account_summaries` | Listar contas | Properties disponiveis |
-| `run_report(property, metrics, dimensions)` | Relatorio custom | Sessions, users, bounce rate |
-| `run_realtime_report(property)` | Tempo real | Utilizadores activos now |
+`2620` = Portugal, confirmado empiricamente (SERP devolve domínios `.pt`). **Não inventar códigos** — validar sempre por uma query de teste. Referência oficial: `dataforseo.com/help-center/locations`.

-## Propriedades GSC Disponiveis
+**Aviso:** alguns países são servidos por dados do Google Ads — volume/CPC funcionam, mas KD, intenção e analytics de domínio não estão disponíveis.
+
+---
+
+## 4. Limitações conhecidas (verificadas, não presumidas)
+
+1. **Issues sem URL.** `get_audit_issues` e `get_audit_pages` devolvem só contagens agregadas via bridge MCP. As linhas por URL vivem em `structuredContent.issues`, que a bridge não entrega. `get_audit_pages` trunca em ~25 linhas mesmo com `limit: 1000`.
+   → Contorno: `details.mcpMeta.url` traz o link do relatório na UI.
+
+2. **Sem medidor de créditos.** `whoami` em self-hosted devolve o mesmo output antes e depois de chamadas pagas. Os custos documentados são estimativas do schema. O contador real está na conta DataForSEO.
+
+3. **`maxPages` default 50.** A causa mais comum de auditorias falsamente limpas.
+
+4. **GSC anonimiza queries.** Totais por query são sempre inferiores aos totais por página. Usar a vista por página para números globais.
+
+5. **GSC não filtra por posição.** Striking distance filtra-se do lado do cliente.
+
+6. **Lag do GSC:** os últimos ~3 dias podem estar incompletos. Datas em Pacific Time. Máximo 16 meses de histórico.
+
+---
+
+## 5. Propriedades Search Console disponíveis

 ```
 sc-domain:descomplicar.pt
@@ -81,14 +119,6 @@ https://alojadamaria.com/
 https://e-commerce.descomplicar.pt/
 ```

-## Requisitos
+---

- **SEO Tools API** deve estar a correr: `~/mcp-servers/seo-tools-api/start.sh`
- **GSC** requer autenticacao OAuth na primeira utilizacao
- **GA** requer ADC credentials configuradas (`gcloud auth application-default login`)
-
-## Limitacoes
-
- Ahrefs API tem rate limiting (100 req/day free tier)
- GSC data maximo: 16 meses historico
- Lighthouse scores variam +/- 5 pontos entre execucoes (network dependent)
+**Actualizado:** 30-07-2026 | Substitui a versão baseada em SEO Tools API + Ahrefs + GSC/Lighthouse MCP
@@ -183,11 +183,14 @@ H1: [Texto] OK
 ---

 ## Ferramentas Utilizadas
- SEO Tools API (localhost:3000)
- Lighthouse MCP
- SEO Ahrefs MCP
- Google Search Console MCP
- Google Analytics MCP (opcional)
+- OpenSEO — crawl e issues (`run_site_audit`, `get_audit_issues`)
+- OpenSEO — Search Console (`get_search_console_performance`)
+- OpenSEO — keywords e SERP (`get_keyword_metrics`, `get_serp_results`)
+- OpenSEO — autoridade (`get_backlinks_overview`, `get_domain_overview`)
+- chrome-devtools — Core Web Vitals por página (opcional)
+
+**Cobertura do crawl**: [N páginas crawladas] de [M páginas com impressões no GSC]
+**Chamadas pagas**: [listar] — custo estimado, não medido (OpenSEO não expõe saldo)

 ---

@@ -161,20 +161,26 @@ mcp__notebooklm__notebook_query({

 ## Ferramentas Recomendadas

-### Validacao
+### No stack (usar primeiro — são estes que temos)

- **Google Search Console** - Monitorizacao, indexacao
- **PageSpeed Insights** - Core Web Vitals
- **Schema Validator** - Testar structured data (schema.org/validator)
- **Mobile-Friendly Test** - Google mobile test
- **Rich Results Test** - Google rich results
+| Necessidade | Ferramenta OpenSEO | Custo |
+|---|---|---|
+| Monitorização, indexação | `get_search_console_performance`, `inspect_urls` | grátis |
+| Auditoria técnica completa | `run_site_audit` → `get_audit_issues` | grátis |
+| Conteúdo fino, títulos, metas | `get_audit_issues` (`thin-content`, `title-*`, `meta-description-*`) | grátis |
+| Keyword research | `get_keyword_metrics` (conhecidas) / `research_keywords` (novas) | pago |
+| Backlinks | `get_backlinks_overview`, `get_backlinks_profile` | pago |
+| Core Web Vitals | `chrome-devtools → performance_start_trace` | grátis |

-### Analise
+Inventário e tabela de migração: `../seo-audit/references/ferramentas-api.md`

- **Screaming Frog** - Auditoria tecnica completa
- **Ahrefs/Semrush** - Keyword research, backlinks
- **AnswerThePublic** - Long-tail questions
- **Google Trends** - Sazonalidade keywords
+### Externas (validação manual)
+
+- **Schema Validator** — testar structured data (schema.org/validator)
+- **Rich Results Test** — Google rich results
+- **Mobile-Friendly Test** — Google mobile test
+- **AnswerThePublic** — long-tail questions
+- **Google Trends** — sazonalidade de keywords

 ### Optimizacao

@@ -249,13 +249,16 @@ https://site.pt/este-url-e-muito-longo-com-muitas-palavras-desnecessarias/

 ### Ferramentas

-| Ferramenta | Uso | Métricas |
-|------------|-----|----------|
-| Google Keyword Planner | Volume, CPC | Volume mensal, competição |
-| Ahrefs | KD, SERP analysis | Keyword Difficulty, DR necessário |
-| Semrush | Concorrência | Gap analysis, trending |
-| AnswerThePublic | Long-tail questions | Questões reais utilizadores |
-| Google Trends | Sazonalidade | Tendência temporal |
+| Ferramenta | Uso | Métricas | Custo |
+|------------|-----|----------|-------|
+| **OpenSEO** `get_keyword_metrics` | Hidratar até 700 keywords conhecidas | Volume, KD, intenção, CPC, tendência | pago (lote) |
+| **OpenSEO** `research_keywords` | Descobrir keywords novas (1-5 seeds) | Volume, KD, ideias relacionadas | pago (~30-100/seed — estimativa do schema, não medida) |
+| **OpenSEO** `get_search_console_performance` | O que já posiciona (dados próprios) | Cliques, impressões, CTR, posição | **grátis** |
+| **OpenSEO** `get_ranked_keywords` | Keywords de um domínio (nosso ou concorrente) | Posição, volume, tráfego | pago |
+| AnswerThePublic | Long-tail questions | Questões reais de utilizadores | grátis |
+| Google Trends | Sazonalidade | Tendência temporal | grátis |
+
+**Ordem obrigatória:** Search Console primeiro (grátis e são dados de primeira mão), só depois as pagas. Mercado PT: `locationCode: 2620`, `languageCode: "pt"`.

 ### Keyword Difficulty Benchmarks

@@ -1,30 +1,13 @@
 ---
 name: seo-report
-description: Relatorio de auditoria SEO completo com Lighthouse, Google Search Console e exportacao para Google Docs. Analisa Core Web Vitals, desempenho, SEO on-page e gera recomendacoes accionaveis.
+description: Relatório SEO completo com dados reais via OpenSEO (Search Console, crawl, Core Web Vitals, backlinks) e exportação para Google Docs. Prioriza por retorno e gera plano de acção. Usar quando "relatório SEO", "seo report", "relatório cliente SEO", "auditoria para cliente".
 ---

 # Skill: /seo-report

-Gera relatorio SEO completo com dados de multiplas fontes e exporta automaticamente para Google Docs.
+Relatório SEO para cliente, com dados reais do **OpenSEO**, exportado para Google Docs.

---
-
-## Contexto NotebookLM
-
-ANTES de executar, consultar notebook para contexto especializado:
-
-| Notebook | ID | Consultar quando |
-|----------|-----|-----------------|
-| Marketing Digital PT | `4c595973` | Sempre |
-
-```
-mcp__notebooklm__notebook_query({
-  notebook_id: "4c595973-ba10-420a-a3bf-e4389e424ad3",
-  query: "<adaptar ao contexto — ex: auditoria SEO, relatorio performance, recomendacoes tecnicas>"
-})
-```
-
-**Procedimento relacionado:** `PROC-DMARC-Email-Entregabilidade.md` -- consultar quando o relatorio envolve email deliverability.
+Diferença face a `/seo-audit`: a auditoria é o **diagnóstico técnico interno**; o report é o **entregável ao cliente** — mesma recolha, apresentação orientada a decisão e a orçamento.

 ---

@@ -32,127 +15,115 @@ mcp__notebooklm__notebook_query({

 `/seo-report <url>` ou `/seo-report <url> <email_destino>`

---
-
-## Exemplos
-
 ```bash
-# Relatorio basico (envia para emanuelalmeidaa@gmail.com)
 /seo-report https://descomplicar.pt
-
-# Relatorio para cliente especifico
 /seo-report https://cliente.pt cliente@email.com
-
-# Relatorio com analise concorrencia
 /seo-report https://site.pt --competitors=concorrente1.pt,concorrente2.pt
 ```

 ---

-## Fontes de Dados
+## Fontes de dados

-| Fonte | Dados Recolhidos | Tempo |
-|-------|------------------|-------|
-| **Lighthouse (Desktop)** | Performance, SEO, Accessibility, Best Practices | ~30s |
-| **Lighthouse (Mobile)** | Core Web Vitals, INP, comparacao mobile/desktop | ~30s |
-| **Lighthouse (Optimizacoes)** | Oportunidades LCP, JS nao usado, images optimization | ~15s |
-| **GSC** | Cliques, impressoes, CTR, posicao media, top queries, tendencia 90 dias | ~10s |
-| **SEO Tools API** | Meta tags, imagens, alt text, links internos/externos, estrutura HTML | ~5s |
-| **Ahrefs (opcional)** | DR, UR, backlinks, referring domains | ~10s |
+| Fonte | Ferramenta | Dados | Custo |
+|---|---|---|---|
+| **Search Console** | `get_search_console_performance` | Cliques, impressões, CTR, posição, por query e por página | grátis |
+| **Indexação** | `inspect_urls` | Estado de indexação (até 10 URLs) | grátis |
+| **Crawl técnico** | `run_site_audit` → `get_audit_issues` | Issues por severidade, Lighthouse em amostra | grátis |
+| **Core Web Vitals** | `chrome-devtools → performance_start_trace` | LCP, INP, CLS por página | grátis |
+| **Keywords** | `get_keyword_metrics` | Volume, KD, intenção (até 700/chamada) | pago |
+| **Autoridade** | `get_backlinks_overview`, `get_domain_overview` | Backlinks, ref. domains, tráfego estimado | pago |
+| **Concorrência** | `find_serp_competitors`, `get_serp_results` | Quem ocupa a SERP | pago |

-**Tempo Total:** ~1m40s (sem concorrencia) | ~3m (com 2 concorrentes)
+**Tempo:** ~5-10 min (crawl de 600 páginas demora ~4 min). Não é instantâneo — avisar o cliente.

 ---

 ## Workflow

-1. Validar URL de entrada
-2. Verificar se site esta no GSC (skip se nao)
-3. Executar auditorias em paralelo:
-   - Lighthouse Desktop + Mobile
-   - Core Web Vitals
-   - SEO Tools API
-   - GSC Analytics (se disponivel)
-   - Ahrefs (se habilitado)
-4. Processar e formatar dados
-5. Gerar relatorio Markdown
-6. Criar Google Doc e partilhar
-7. Retornar link do documento
-
---
-
-## Estrutura do Relatorio
-
-O relatorio final tem 8 seccoes:
-
-1. **Sumario Executivo** -- Top 5 descobertas + accao imediata recomendada
-2. **Pontuacoes Globais** -- Desktop vs Mobile (Performance, SEO, A11y, Best Practices)
-3. **Core Web Vitals** -- LCP, INP, CLS com oportunidades de optimizacao
-4. **GSC Analytics** -- Performance overview, top queries, oportunidades CTR (ultimos 90 dias)
-5. **Analise On-Page** -- Meta tags, imagens SEO, internal linking
-6. **Backlinks e Autoridade** -- DR, UR, top backlinks, estrategia
-7. **Plano de Accao** -- Priorizado (critico/importante/melhoria) com impacto e esforco
-8. **Roadmap Trimestral** -- Fundacao tecnica -> Conteudo e autoridade -> Consolidacao
-
---
-
-## Propriedades GSC Disponiveis
-
 ```
-sc-domain:descomplicar.pt
-https://emanuelalmeida.pt/
-https://carstuff.pt/
-https://solarfvengenharia.com/
-https://aquisevende.pt/
-https://alojadamaria.com/
-https://e-commerce.descomplicar.pt/
+1. whoami + list_projects        → projectId e mercado (GATE: PT = 2620/pt)
+2. GSC por query + por página    → paginar até esgotar
+3. Dimensionar o crawl           → maxPages ≥ nº páginas com impressões + 25%
+4. run_site_audit                → poll get_audit_status até "completed"
+5. get_audit_issues              → critical → warning → info
+6. Cruzar fase 2 com fase 5      → páginas com procura E com defeito = lista de trabalho
+7. [pago, opcional] keywords, backlinks, SERP
+8. Gerar Markdown → Google Doc → partilhar
 ```

+**Os passos 1-6 são grátis e produzem o grosso do relatório.** O passo 7 só se o cliente pagar análise competitiva.
+
 ---

-## Notas Tecnicas
+## Estrutura do relatório (8 secções)
+
+1. **Sumário executivo** — 5 descobertas + a acção imediata. Más notícias primeiro.
+2. **Realidade actual** — cliques, impressões, CTR global, distribuição por posição, branded vs não-branded.
+3. **Onde está o retorno** — striking distance (pos 4-20, ≥25 impressões) e desperdício (pos >40 com procura alta).
+4. **Estado técnico** — issues por severidade, com **cobertura do crawl declarada**.
+5. **Core Web Vitals** — LCP / INP / CLS nas páginas que importam (não em todas).
+6. **Autoridade** — backlinks e ref. domains, se contratado.
+7. **Plano de acção** — prioridade (crítico/importante/melhoria) × esforço × impacto estimado.
+8. **Roadmap trimestral** — fundação técnica → conteúdo → consolidação.
+
+---
+
+## Regras de honestidade do relatório
+
+Um relatório SEO é um documento comercial. Isso torna a precisão **mais** importante, não menos.
+
+- **Declarar sempre a cobertura do crawl.** "1337 issues em 600 páginas crawladas de ~640 com impressões." Sem isto, o número de issues não significa nada.
+- **Não apresentar contagens como URLs verificados.** Se a bridge só deu contagens, dizê-lo e anexar o link da UI.
+- **Custos são estimativas.** O OpenSEO não expõe saldo — nunca escrever "gastámos X créditos" como facto.
+- **Separar medido de inferido.** Marcar as inferências. Um cliente que descobre uma inferência apresentada como facto deixa de confiar no resto.
+- **CTR baixo em posição alta não é problema de ranking.** É título/meta. Dizer isso — é a recomendação mais barata e de maior retorno que existe.
+
+---
+
+## Notas técnicas

 ### Requisitos
- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh`
- Google Workspace MCP configurado
- GSC authentication (OAuth primeira vez)
+- OpenSEO acessível (`whoami` responde)
+- Propriedade ligada ao Search Console (senão, relatório sem fase GSC — declarar)
+- `google-workspace` MCP para o Google Doc

-### Erros Comuns
- **Site nao em GSC:** Relatorio gerado sem dados GSC (aviso incluido)
- **Lighthouse timeout:** Retry automatico (3x)
- **Ahrefs rate limit:** Skip backlinks, aviso no relatorio
+### Erros comuns
+| Erro | Sintoma | Solução |
+|---|---|---|
+| **`maxPages` por omissão** | Relatório limpo demais, poucos issues | Redimensionar pelo nº de páginas do GSC e relançar |
+| Site fora do GSC | Fase 2 vazia | Gerar sem GSC, com aviso destacado |
+| Mercado errado | Dados de keywords em inglês/EUA | `locationCode: 2620`, `languageCode: "pt"` |
+| Crawl a demorar | `get_audit_status` em `crawling` | Normal — 600 páginas ≈ 4 min. Fazer poll, não cancelar |

 ---

-## References (conteudo detalhado)
+## References

-| Ficheiro | Conteudo |
-|----------|----------|
-| `references/template-relatorio.md` | Template completo do relatorio com todas as tabelas e seccoes |
-| `references/implementacao-tecnica.md` | Workflow mermaid, codigo JS, funcoes GSC, notas tecnicas |
+| Ficheiro | Conteúdo |
+|---|---|
+| `references/template-relatorio.md` | Template completo com tabelas e secções |
+| `references/implementacao-tecnica.md` | Workflow, chamadas OpenSEO, processamento |
+
+Inventário completo das ferramentas e tabela de migração: `../seo-audit/references/ferramentas-api.md`

 ---

-## Anti-Patterns
+## Anti-patterns

- Gerar relatorio sem dados reais (sempre usar MCPs)
- Ignorar gap mobile/desktop
- Nao priorizar recomendacoes (tudo parece igual)
- Esquecer de verificar se site esta no GSC antes de tentar recolher dados
- Relatorio sem accoes concretas e estimativas de impacto
+- Gerar relatório sem dados reais.
+- Omitir a cobertura do crawl (faz o relatório parecer melhor do que é).
+- Listar issues por contagem em vez de por impacto.
+- Apresentar estimativas de custo ou de tráfego como medições.
+- Recomendações sem esforço e impacto estimados.
+- Correr as fases pagas antes das grátis.

 ---

-**Versao:** 2.1.0 | **Autor:** Descomplicar
-
---
+**Versão:** 3.0.0 | **Autor:** Descomplicar® | **Motor:** OpenSEO

 ## Healing Log

-Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
-
 ```jsonl
-{"date":"","issue":"","fix":"","source":"user|auto"}
+{"date":"2026-07-30","issue":"Skill dependia de SEO Tools API (localhost:3000), Lighthouse MCP, GSC MCP e Ahrefs — nenhum operacional. Workflow inteiro não executável.","fix":"Reescrita sobre OpenSEO; fases grátis antes das pagas; cobertura de crawl obrigatória no relatório.","source":"auto"}
 ```
-
-*Adicionar nova linha após cada erro corrigido.*
@@ -1,144 +1,169 @@
-# Implementacao Tecnica - SEO Report
+# Implementação Técnica — SEO Report (OpenSEO)

-## Workflow Tecnico
+## Workflow

 ```mermaid
-graph LR
-    A[Input: URL] --> B{Site em GSC?}
-    B -->|Sim| C[Recolher dados GSC]
-    B -->|Nao| D[Skip GSC, aviso]
+graph TD
+    A[Input: URL] --> B[whoami + list_projects]
+    B --> C{Mercado correcto?}
+    C -->|Não| C2[Passar locationCode 2620 + languageCode pt]
+    C -->|Sim| D[GSC: dimensions query]
+    C2 --> D

-    C --> E[Lighthouse Desktop]
-    D --> E
+    D --> E[GSC: dimensions page]
+    E --> F[Dimensionar crawl:<br/>maxPages = páginas GSC + 25%]

-    E --> F[Lighthouse Mobile]
-    F --> G[Core Web Vitals]
-    G --> H[SEO Tools API]
-    H --> I{Ahrefs habilitado?}
+    F --> G[run_site_audit]
+    G --> H[poll get_audit_status]
+    H -->|running| H
+    H -->|completed| I[get_audit_issues por severidade]

-    I -->|Sim| J[Recolher DR/UR]
-    I -->|Nao| K[Skip Ahrefs]
+    I --> J[Cruzar: páginas com procura<br/>E com defeito]
+    J --> K{Fases pagas contratadas?}

-    J --> L[Processar dados]
-    K --> L
+    K -->|Sim| L[get_keyword_metrics<br/>get_backlinks_overview<br/>get_serp_results]
+    K -->|Não| M[Saltar fases pagas]

-    L --> M[Gerar relatorio Markdown]
-    M --> N[Criar Google Doc]
-    N --> O[Partilhar com email]
-
-    O --> P[Retornar link]
+    L --> N[Processar]
+    M --> N
+    N --> O[Markdown] --> P[Google Doc] --> Q[Partilhar]
 ```

-## Implementacao
+**O ponto crítico é o nó F.** Dimensionar o crawl a partir do GSC é o que distingue um relatório verdadeiro de um relatório limpo e falso.
+
+---
+
+## Sequência de chamadas

 ```javascript
-async function generateSEOReport(url, options = {}) {
-  const {
-    email = 'emanuelalmeidaa@gmail.com',
-    competitors = [],
-    includeAhrefs = true
-  } = options;
+// 1. Contexto e mercado
+const me   = await openseo.whoami();
+const projs = await openseo.list_projects();
+const projectId = projs[0].id;
+const MARKET = { locationCode: 2620, languageCode: 'pt' };  // Portugal

-  // 1. Validar URL
-  if (!isValidURL(url)) {
-    throw new Error('URL invalido');
+// 2. Search Console — paginar até esgotar (grátis)
+async function gscAll(dimensions) {
+  const rows = [];
+  let startRow = 0;
+  while (true) {
+    const r = await openseo.get_search_console_performance({
+      projectId, dimensions, dateRange: 'last_3_months',
+      rowLimit: 1000, startRow
+    });
+    const parsed = parseRows(r.text);
+    rows.push(...parsed);
+    if (!r.text.split('\n')[0].includes('more available') || !parsed.length) break;
+    startRow += 1000;
  }
+  return rows;
+}

-  // 2. Recolher dados em paralelo (melhor performance)
-  const [
-    lighthouseDesktop,
-    lighthouseMobile,
-    coreWebVitals,
-    seoToolsData,
-    gscData,
-    ahrefsData
-  ] = await Promise.allSettled([
-    mcp__lighthouse__run_audit(url, 'desktop'),
-    mcp__lighthouse__run_audit(url, 'mobile'),
-    mcp__lighthouse__get_core_web_vitals(url),
-    fetch(`http://localhost:3000/seo-audit?url=${url}`).then(r => r.json()),
-    getGSCData(url),
-    includeAhrefs ? getAhrefsData(url) : null
-  ]);
+const byQuery = await gscAll(['query']);
+const byPage  = await gscAll(['page']);

-  // 3. Processar e formatar
-  const reportData = {
-    url,
-    date: new Date().toISOString().split('T')[0],
-    scores: extractScores(lighthouseDesktop, lighthouseMobile),
-    cwv: processCoreWebVitals(coreWebVitals),
-    gsc: processGSCData(gscData),
-    onPage: processOnPageData(seoToolsData),
-    backlinks: processBacklinks(ahrefsData),
-    recommendations: generateRecommendations(/* all data */)
-  };
+// 3. Dimensionar o crawl a partir da realidade, não de um default
+const maxPages = Math.ceil(byPage.length * 1.25);

-  // 4. Gerar documento Markdown
-  const markdown = generateReportMarkdown(reportData);
+// 4. Crawl (grátis) — assíncrono, exige poll
+const audit = await openseo.run_site_audit({
+  projectId, url, maxPages, runLighthouse: true
+});
+let status;
+do {
+  await sleep(30_000);
+  status = await openseo.get_audit_status({ projectId, auditId: audit.id });
+} while (!status.text.includes('completed'));

-  // 5. Criar Google Doc
-  const docResult = await mcp__google-workspace__create_doc({
-    title: `Relatorio SEO - ${extractDomain(url)} - ${reportData.date}`,
-    body_content: markdown,
+// 5. Issues por severidade (grátis)
+const critical = await openseo.get_audit_issues({ projectId, auditId: audit.id, severity: 'critical' });
+const warning  = await openseo.get_audit_issues({ projectId, auditId: audit.id, severity: 'warning'  });
+
+// 6. Fases pagas — so se contratadas
+if (options.paid) {
+  const kw = await openseo.get_keyword_metrics({
+    projectId, keywords: strikingDistance(byQuery).map(r => r.key), ...MARKET
+  });
+  const bl = await openseo.get_backlinks_overview({ projectId, target: domain });
+}
+```
+
+---
+
+## Processamento — as funções que importam
+
+```javascript
+// GSC anonimiza queries: totais por query < totais por página.
+// Para números globais usar SEMPRE a vista por página.
+const globals = {
+  clicks:      sum(byPage, 'clicks'),
+  impressions: sum(byPage, 'impressions'),
+  ctr:         sum(byPage, 'clicks') / sum(byPage, 'impressions')
+};
+
+// O GSC não filtra por posição — filtrar do lado do cliente.
+const strikingDistance = rows => rows
+  .filter(r => r.position >= 4 && r.position <= 20 && r.impressions >= 25)
+  .sort((a, b) => b.impressions - a.impressions);
+
+// Páginas com procura real enterradas fora das primeiras 4 páginas.
+const waste = rows => rows
+  .filter(r => r.position > 40 && r.impressions >= 300)
+  .sort((a, b) => b.impressions - a.impressions);
+
+// O sinal mais accionável: primeira página, CTR nulo.
+// Não é ranking — é título e meta description.
+const titleProblem = rows => rows
+  .filter(r => r.position <= 10 && r.impressions >= 200 && r.ctr < 0.005);
+
+// Lixo nas queries do GSC (colagens do Google Ads, operadores site:).
+const isNoise = k =>
+  (k.includes('ativado') && k.includes('correspond')) ||
+  k.startsWith('-site:') || k.startsWith('=') ||
+  k.length > 90 || k.includes('0,00');
+```
+
+---
+
+## Entrega
+
+```javascript
+const doc = await googleWorkspace.docs_create_document({
+  title: `Relatório SEO — ${domain} — ${today}`,
  user_google_email: email
-  });
-
-  // 6. Retornar link
-  return {
-    success: true,
-    doc_url: docResult.url,
-    summary: reportData.recommendations.slice(0, 5)
-  };
-}
+});
+await googleWorkspace.docs_append_text({ document_id: doc.id, text: markdown });
 ```

-## Propriedades GSC Disponiveis
+---

-```javascript
-const GSC_PROPERTIES = [
-  'sc-domain:descomplicar.pt',
-  'https://emanuelalmeida.pt/',
-  'https://carstuff.pt/',
-  'https://solarfvengenharia.com/',
-  'https://aquisevende.pt/',
-  'https://alojadamaria.com/',
-  'https://e-commerce.descomplicar.pt/'
-];
-
-async function getGSCData(url) {
-  const domain = extractDomain(url);
-  const property = GSC_PROPERTIES.find(p => p.includes(domain));
-
-  if (!property) {
-    console.warn(`Site ${domain} nao esta no GSC. Dados GSC nao disponiveis.`);
-    return null;
-  }
-
-  const analytics = await mcp__gsc__get_search_analytics({
-    site_url: property,
-    start_date: daysAgo(90),
-    end_date: 'today',
-    dimensions: ['query'],
-    row_limit: 100
-  });
-
-  return analytics;
-}
-```
-
-## Notas Tecnicas
+## Notas técnicas

 ### Requisitos
- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh`
- Google Workspace MCP configurado
- GSC authentication (OAuth primeira vez)
+- OpenSEO acessível (`whoami` responde)
+- Propriedade ligada ao Search Console
+- `google-workspace` MCP para o documento

-### Performance
- Execucao paralela de tools (1m40s total)
- Cache Lighthouse results (5 min TTL)
- Rate limiting Ahrefs API (100 req/day free)
+### Tempos reais (medidos, descomplicar.pt, 07-2026)
+| Fase | Duração |
+|---|---|
+| GSC (2 dimensões, ~1700+474 linhas) | ~10s |
+| Crawl 600 páginas + Lighthouse 20 | ~4 min |
+| `get_audit_issues` | instantâneo |

-### Erros Comuns
- **Site nao em GSC:** Relatorio gerado sem dados GSC
- **Lighthouse timeout:** Retry automatico (3x)
- **Ahrefs rate limit:** Skip backlinks, aviso no relatorio
+### Limitações
+- **Issues sem URL:** `get_audit_issues` / `get_audit_pages` devolvem só contagens pela bridge MCP; `structuredContent.issues` não é entregue e `get_audit_pages` trunca em ~25 linhas. Usar `details.mcpMeta.url` para o link da UI.
+- **Sem medidor de créditos:** `whoami` não muda depois de chamadas pagas. Custos são estimativas.
+- **Lag do GSC:** últimos ~3 dias incompletos; datas em Pacific Time; máx. 16 meses.
+
+### Erros comuns
+| Erro | Sintoma | Solução |
+|---|---|---|
+| `maxPages` por omissão (50) | Poucos issues, relatório "limpo" | Redimensionar pelo GSC, relançar |
+| Site fora do GSC | Fase GSC vazia | Gerar sem GSC, aviso destacado |
+| Mercado errado | Keywords em inglês/EUA | `locationCode: 2620`, `languageCode: "pt"` |
+| Cancelar o crawl cedo demais | Sem `auditId` utilizável | Fazer poll; 600 páginas ≈ 4 min |
+
+---
+
+**Actualizado:** 30-07-2026 | Substitui a implementação baseada em Lighthouse MCP + SEO Tools API + Ahrefs
@@ -203,13 +203,17 @@ Data: YYYY-MM-DD | Versao 2.0 (2026 Standards)
 ## Anexos

 ### A. Metodologia
- Lighthouse: 3 runs, mediana reportada
- GSC: Ultimos 90 dias completos
+- Motor: OpenSEO (crawl same-origin, robots-aware) + Search Console
+- Crawl: [N] páginas de [M] com impressões no GSC — **declarar sempre a cobertura**
+- Search Console: últimos 3 meses; vista por página para totais (o GSC anonimiza queries)
+- Core Web Vitals: Lighthouse em amostra; páginas individuais via chrome-devtools
 - Thresholds: Google 2026 Standards
+- Custos de chamadas pagas: estimativas do schema, não medições

-### B. Glossario
- **DR**: Domain Rating (Ahrefs)
- **INP**: Interaction to Next Paint (substitui FID em 2026)
+### B. Glossário
+- **Striking distance**: posição 4-20 com impressões relevantes — onde está o retorno
+- **KD**: Keyword Difficulty
+- **INP**: Interaction to Next Paint (substituiu o FID em 2026)
 - **E-E-A-T**: Experience, Expertise, Authoritativeness, Trust
 - **CTR**: Click-Through Rate