feat(marketing): adiciona plugin marketing (agents, skills, knowledge e metadados do projeto)

2026-10-28 16:09:09 +00:00
parent e43fec3bd9
commit 13c39d8000
96 changed files with 9733 additions and 0 deletions
@@ -0,0 +1,159 @@
+---
+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.
+layer: wiki
+---
+
+# Skill: /seo-report
+
+Gera relatorio SEO completo com dados de multiplas fontes e exporta automaticamente 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.
+
+---
+
+## Trigger
+
+`/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
+
+| 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 |
+
+**Tempo Total:** ~1m40s (sem concorrencia) | ~3m (com 2 concorrentes)
+
+---
+
+## 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/
+```
+
+---
+
+## Notas Tecnicas
+
+### Requisitos
+- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh`
+- Google Workspace MCP configurado
+- GSC authentication (OAuth primeira vez)
+
+### 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
+
+---
+
+## References (conteudo detalhado)
+
+| 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 |
+
+---
+
+## 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
+
+---
+
+**Versao:** 2.1.0 | **Autor:** Descomplicar
+
+---
+
+## Healing Log
+
+Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
+
+```jsonl
+{"date":"","issue":"","fix":"","source":"user|auto"}
+```
+
+*Adicionar nova linha após cada erro corrigido.*
@@ -0,0 +1,144 @@
+# Implementacao Tecnica - SEO Report
+
+## Workflow Tecnico
+
+```mermaid
+graph LR
+    A[Input: URL] --> B{Site em GSC?}
+    B -->|Sim| C[Recolher dados GSC]
+    B -->|Nao| D[Skip GSC, aviso]
+
+    C --> E[Lighthouse Desktop]
+    D --> E
+
+    E --> F[Lighthouse Mobile]
+    F --> G[Core Web Vitals]
+    G --> H[SEO Tools API]
+    H --> I{Ahrefs habilitado?}
+
+    I -->|Sim| J[Recolher DR/UR]
+    I -->|Nao| K[Skip Ahrefs]
+
+    J --> L[Processar dados]
+    K --> L
+
+    L --> M[Gerar relatorio Markdown]
+    M --> N[Criar Google Doc]
+    N --> O[Partilhar com email]
+
+    O --> P[Retornar link]
+```
+
+## Implementacao
+
+```javascript
+async function generateSEOReport(url, options = {}) {
+  const {
+    email = 'emanuelalmeidaa@gmail.com',
+    competitors = [],
+    includeAhrefs = true
+  } = options;
+
+  // 1. Validar URL
+  if (!isValidURL(url)) {
+    throw new Error('URL invalido');
+  }
+
+  // 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
+  ]);
+
+  // 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 */)
+  };
+
+  // 4. Gerar documento Markdown
+  const markdown = generateReportMarkdown(reportData);
+
+  // 5. Criar Google Doc
+  const docResult = await mcp__google-workspace__create_doc({
+    title: `Relatorio SEO - ${extractDomain(url)} - ${reportData.date}`,
+    body_content: markdown,
+    user_google_email: email
+  });
+
+  // 6. Retornar link
+  return {
+    success: true,
+    doc_url: docResult.url,
+    summary: reportData.recommendations.slice(0, 5)
+  };
+}
+```
+
+## 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
+
+### Requisitos
+- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh`
+- Google Workspace MCP configurado
+- GSC authentication (OAuth primeira vez)
+
+### Performance
+- Execucao paralela de tools (1m40s total)
+- Cache Lighthouse results (5 min TTL)
+- Rate limiting Ahrefs API (100 req/day free)
+
+### Erros Comuns
+- **Site nao em GSC:** Relatorio gerado sem dados GSC
+- **Lighthouse timeout:** Retry automatico (3x)
+- **Ahrefs rate limit:** Skip backlinks, aviso no relatorio
@@ -0,0 +1,220 @@
+# Template Relatorio SEO
+
+```markdown
+# Relatorio SEO - [DOMINIO]
+Data: YYYY-MM-DD | Versao 2.0 (2026 Standards)
+
+---
+
+## Sumario Executivo
+
+**Principais Descobertas (Top 5):**
+1. [Critico] Core Web Vitals - INP > 500ms (target < 200ms)
+2. [Importante] E-E-A-T - Sem autor identificado em 80% dos artigos
+3. [Melhoria] CTR GSC - Posicao 4-10 com CTR < 3%
+4. [Oportunidade] 15 keywords posicao 11-20 (easy wins)
+5. [Accao Imediata] 47 imagens sem alt text (SEO + A11y)
+
+**Accao Imediata Recomendada:**
+> Optimizar INP removendo 350KB JS nao usado (-40% bundle size)
+> ROI esperado: Posicao media +2 ranks, CTR +0.8pp
+
+---
+
+## 1. Pontuacoes Globais
+
+### Desktop vs Mobile
+
+| Metrica | Desktop | Mobile | Gap | Target 2026 |
+|---------|---------|--------|-----|-------------|
+| **Performance** | 85/100 | 62/100 | -23 | > 90 |
+| **SEO** | 92/100 | 88/100 | -4 | > 95 |
+| **Accessibility** | 78/100 | 78/100 | 0 | > 90 |
+| **Best Practices** | 95/100 | 92/100 | -3 | > 95 |
+
+**Analise Gap Mobile:** Dispositivos moveis representam 75% do trafego. Gap de -23 pontos e critico.
+
+---
+
+## 2. Core Web Vitals
+
+### Comparacao Mobile vs Desktop
+
+| Metrica | Mobile | Desktop | Threshold 2026 | Status |
+|---------|--------|---------|----------------|--------|
+| **LCP** | 2.8s | 1.9s | < 2.5s | -- |
+| **INP** | 520ms | 180ms | < 200ms | -- |
+| **CLS** | 0.08 | 0.05 | < 0.1 | -- |
+
+### Oportunidades LCP
+
+| Oportunidade | Savings | Prioridade |
+|--------------|---------|------------|
+| Preload imagem hero | 1.2s | Critico |
+| Lazy load below-fold (15 imagens) | 800ms | Alto |
+| Optimizar TTFB (servidor response) | 400ms | Alto |
+| Comprimir imagens WebP (85% quality) | 600ms | Medio |
+
+### Oportunidades INP
+
+| Oportunidade | Savings | Prioridade |
+|--------------|---------|------------|
+| Remover JS nao usado (350KB) | 280ms | Critico |
+| Code splitting (carregar on-demand) | 180ms | Alto |
+| Defer third-party scripts | 120ms | Alto |
+| Optimizar event listeners | 80ms | Medio |
+
+---
+
+## 3. GSC Analytics (Ultimos 90 dias)
+
+### Performance Overview
+
+| Metrica | Valor | vs 90 dias anteriores | Tendencia |
+|---------|-------|------------------------|-----------|
+| **Cliques** | 12,450 | +18% (+1,890) | Subida |
+| **Impressoes** | 245,800 | +22% (+44,300) | Subida |
+| **CTR Medio** | 5.1% | -0.3pp | Descida |
+| **Posicao Media** | 12.8 | +2.1 (pior) | Descida |
+
+### Top 10 Queries
+
+| Query | Cliques | Impr. | CTR | Pos. | Oportunidade |
+|-------|---------|-------|-----|------|--------------|
+| [keyword 1] | 850 | 15,200 | 5.6% | 8.2 | Optimizar para top 5 |
+| [keyword 2] | 720 | 9,800 | 7.3% | 4.5 | Manter |
+| [keyword 3] | 680 | 22,400 | 3.0% | 14.8 | Melhorar CTR + posicao |
+| ... | ... | ... | ... | ... | ... |
+
+---
+
+## 4. Analise On-Page
+
+### Meta Tags Audit
+
+| Pagina | Title | Description | Issues |
+|--------|-------|-------------|--------|
+| Homepage | OK 58 chars | Longo 175 chars | Description > 160 chars |
+| /servicos | OK 52 chars | OK 155 chars | - |
+| /blog/[slug] | Curto 28 chars | Duplicado (5 paginas) | Title curto, description duplicada |
+
+### Imagens SEO
+
+| Metrica | Valor | Target | Status |
+|---------|-------|--------|--------|
+| **Total Imagens** | 127 | - | - |
+| **Com Alt Text** | 80 (63%) | 100% | Critico |
+| **Alt Text Descritivo** | 52 (41%) | 100% | Critico |
+| **Formato WebP** | 15 (12%) | > 80% | Critico |
+| **Lazy Loading** | 45 (35%) | 100% (below-fold) | Medio |
+
+### Internal Linking
+
+| Metrica | Valor | Benchmark |
+|---------|-------|-----------|
+| **Links Internos Medios/Pagina** | 8.5 | > 10 bom |
+| **Orphan Pages** | 3 | 0 ideal |
+| **Broken Internal Links** | 7 | 0 |
+| **Anchor Text Optimizado** | 42% | > 70% |
+
+---
+
+## 5. Backlinks e Autoridade
+
+### Perfil de Dominio
+
+| Metrica | Valor | Benchmark | Status |
+|---------|-------|-----------|--------|
+| **Domain Rating (DR)** | 32 | > 40 bom | -- |
+| **URL Rating (UR) Medio** | 18 | > 25 bom | -- |
+| **Backlinks Totais** | 1,247 | - | - |
+| **Referring Domains** | 87 | > 100 bom | -- |
+| **DoFollow** | 68% | > 60% | OK |
+
+### Top 10 Backlinks (por DR)
+
+| Dominio | DR | Anchor Text | DoFollow | Tipo |
+|---------|-----|-------------|----------|------|
+| [site DR alto] | 58 | [anchor] | Sim | Editorial |
+| ... | ... | ... | ... | ... |
+
+---
+
+## 6. Benchmarks vs Concorrencia
+
+| Metrica | [Site] | Concorrente A | Concorrente B | Gap |
+|---------|--------|---------------|---------------|-----|
+| DR | 32 | 45 | 38 | -13 |
+| Traffic Estimado | 12.5K/mes | 28K/mes | 18K/mes | -15.5K |
+| Ranking Keywords | 450 | 820 | 610 | -370 |
+| Backlinks | 1,247 | 3,200 | 2,100 | -1,953 |
+
+---
+
+## 7. Plano de Accao (Priorizado)
+
+### Critico (Semana 1-2)
+
+| Accao | Impacto Estimado | Esforco | ROI |
+|-------|------------------|---------|-----|
+| **Optimizar INP Mobile** | Posicao media +2, CTR +0.8pp | 8h | Alto |
+| **Adicionar alt text imagens** | Acessibilidade +15 pontos, SEO +5% | 3h | Alto |
+| **Corrigir links internos quebrados** | UX, crawl efficiency +10% | 1h | Medio |
+| **Reescrever meta descriptions** (CTR baixo) | CTR +1.2pp estimado | 2h | Alto |
+
+### Importante (Semana 3-4)
+
+| Accao | Impacto Estimado | Esforco | ROI |
+|-------|------------------|---------|-----|
+| **Optimizar keywords posicao 11-20** | +1,200 cliques/mes | 12h | Medio |
+| **Implementar E-E-A-T** | Trust signals, rankings +5% | 6h | Medio |
+| **Internal linking orphan pages** | Indexabilidade, link equity | 2h | Medio |
+| **Converter imagens WebP** | LCP -600ms | 4h | Medio |
+
+### Melhoria (Mes 2-3)
+
+| Accao | Impacto Estimado | Esforco | ROI |
+|-------|------------------|---------|-----|
+| **Criar conteudo keywords gap** (3 artigos) | +2K visitas/mes | 20h | Medio |
+| **Campanha backlinks DR > 40** (6 guest posts) | DR +5, autoridade | 30h | Baixo |
+| **Optimizar structured data** | Rich snippets, CTR +0.5pp | 6h | Baixo |
+
+---
+
+## 8. Roadmap Trimestral
+
+### Mes 1: Fundacao Tecnica
+- Semana 1-2: Criticos (INP, alt text, links quebrados, meta descriptions)
+- Semana 3-4: Importantes (keywords 11-20, E-E-A-T, orphan pages)
+
+### Mes 2: Conteudo e Autoridade
+- Criar artigos keywords gap
+- Guest posts DR > 40
+- Optimizar artigos existentes (posicao 11-30)
+
+### Mes 3: Consolidacao e Escala
+- Monitorizar rankings e ajustar on-page
+- Guest posts adicionais
+- Expandir internal linking (cluster content)
+- Actualizar conteudo underperforming
+
+---
+
+## Anexos
+
+### A. Metodologia
+- Lighthouse: 3 runs, mediana reportada
+- GSC: Ultimos 90 dias completos
+- Thresholds: Google 2026 Standards
+
+### B. Glossario
+- **DR**: Domain Rating (Ahrefs)
+- **INP**: Interaction to Next Paint (substitui FID em 2026)
+- **E-E-A-T**: Experience, Expertise, Authoritativeness, Trust
+- **CTR**: Click-Through Rate
+
+---
+
+**Proxima Auditoria Recomendada:** [Data + 3 meses]
+**Contacto Suporte:** recursos@descomplicar.pt
+```