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.

marketing/skills/seo-report/SKILL.md

@@ -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.*