antigravity-seo-kit 2.0.0

package/docs/COMMANDS.md

@@ -0,0 +1,184 @@
+# Workflows Reference
+
+## Overview
+
+All SEO Kit workflows start with `/seo-` followed by a command name. These are defined in `.agent/workflows/`.
+
+## Workflow List
+
+### `/seo-audit`
+
+Full website SEO audit with specialist skills.
+
+**Example:**
+```
+/seo-audit https://example.com
+```
+
+**What it does:**
+1. Crawls up to 500 pages
+2. Detects business type
+3. Activates 7+ specialist skills
+4. Generates SEO Health Score (0-100)
+5. Creates prioritized action plan
+
+**Output:**
+- `FULL-AUDIT-REPORT.md`
+- `ACTION-PLAN.md`
+- `screenshots/` (if Playwright available)
+
+---
+
+### `/seo-page`
+
+Deep single-page analysis.
+
+**Example:**
+```
+/seo-page https://example.com/about
+```
+
+---
+
+### `/seo-technical`
+
+Technical SEO audit across 9 categories.
+
+**Example:**
+```
+/seo-technical https://example.com
+```
+
+**Categories:** Crawlability, Indexability, Security, URL Structure, Mobile, Core Web Vitals, Structured Data, JavaScript Rendering, IndexNow
+
+---
+
+### `/seo-content`
+
+E-E-A-T and content quality analysis.
+
+**Example:**
+```
+/seo-content https://example.com/blog/post
+```
+
+---
+
+### `/seo-schema`
+
+Schema markup detection, validation, and generation.
+
+**Example:**
+```
+/seo-schema https://example.com
+```
+
+---
+
+### `/seo-geo`
+
+AI Overviews / Generative Engine Optimization.
+
+**Example:**
+```
+/seo-geo https://example.com/blog/guide
+```
+
+---
+
+### `/seo-images`
+
+Image optimization analysis.
+
+**Example:**
+```
+/seo-images https://example.com
+```
+
+---
+
+### `/seo-sitemap`
+
+Analyze existing XML sitemap or generate new one.
+
+**Example:**
+```
+/seo-sitemap https://example.com/sitemap.xml
+```
+
+---
+
+### `/seo-plan`
+
+Strategic SEO planning.
+
+**Types:** `saas`, `local`, `ecommerce`, `publisher`, `agency`
+
+**Example:**
+```
+/seo-plan saas
+```
+
+---
+
+### `/seo-competitor-pages`
+
+Competitor comparison page generation.
+
+**Example:**
+```
+/seo-competitor-pages generate
+```
+
+---
+
+### `/seo-hreflang`
+
+Hreflang and international SEO audit.
+
+**Example:**
+```
+/seo-hreflang https://example.com
+```
+
+---
+
+### `/seo-programmatic`
+
+Programmatic SEO analysis and planning.
+
+**Example:**
+```
+/seo-programmatic https://example.com/tools/
+```
+
+---
+
+### `/seo-local`
+
+Local SEO analysis (GBP, citations, reviews, map pack).
+
+**Example:**
+```
+/seo-local https://example.com
+```
+
+---
+
+## Quick Reference
+
+| Workflow | Use Case |
+|----------|----------|
+| `/seo-audit` | Full website audit |
+| `/seo-page` | Single page analysis |
+| `/seo-technical` | Technical SEO check |
+| `/seo-content` | E-E-A-T analysis |
+| `/seo-schema` | Schema validation |
+| `/seo-sitemap` | Sitemap validation/generation |
+| `/seo-images` | Image optimization |
+| `/seo-geo` | AI search optimization |
+| `/seo-plan` | Strategic planning |
+| `/seo-programmatic` | Programmatic SEO |
+| `/seo-competitor-pages` | Competitor pages |
+| `/seo-local` | Local SEO |
+| `/seo-hreflang` | International SEO |

package/docs/INSTALLATION.md

@@ -0,0 +1,100 @@
+# Installation Guide
+
+## Prerequisites
+
+- **Python 3.11+** with pip
+- **Google Antigravity** or compatible AI coding agent
+
+Optional:
+- **Playwright** for screenshot capabilities
+
+## Quick Start (Recommended)
+
+1. **Clone or copy SEO Kit into your workspace:**
+
+```bash
+git clone https://github.com/AgriciDaniel/claude-seo.git seo-kit
+```
+
+2. **Open the workspace in Antigravity**
+
+The agent will auto-discover:
+- Skills in `.agent/skills/`
+- Workflows in `.agent/workflows/`
+- Agent instructions in `.agent/agent.md`
+
+3. **Install Python dependencies:**
+
+```bash
+pip install -r requirements.txt
+```
+
+4. **Install Playwright browsers** (optional):
+
+```bash
+pip install playwright
+playwright install chromium
+```
+
+## Project Structure
+
+| Component | Path |
+|-----------|------|
+| Agent config | `.agent/agent.md` |
+| Main skill | `.agent/skills/seo/SKILL.md` |
+| Sub-skills | `.agent/skills/seo-*/SKILL.md` |
+| Workflows | `.agent/workflows/seo-*.md` |
+| References | `.agent/skills/seo/references/` |
+| Scripts | `.agent/skills/seo/scripts/` |
+| Schema templates | `.agent/skills/seo/schema/` |
+
+## Verify Installation
+
+1. Open the workspace in Antigravity
+2. The agent should list available skills
+3. Try a workflow:
+```
+/seo-audit https://example.com
+```
+
+## Extensions (Optional)
+
+### DataForSEO Extension
+
+Adds live SEO data via DataForSEO MCP server.
+
+```bash
+# Follow setup in extensions/dataforseo/README.md
+```
+
+### Banana Image Gen Extension
+
+Adds AI image generation via Gemini MCP.
+
+```bash
+# Follow setup in extensions/banana/README.md
+```
+
+## Troubleshooting
+
+### Skills not discovered
+
+Ensure the `.agent/` directory is at the root of your workspace:
+
+```bash
+ls .agent/skills/seo/SKILL.md
+```
+
+### Python dependency errors
+
+Install dependencies manually:
+
+```bash
+pip install beautifulsoup4 requests lxml playwright Pillow urllib3 validators
+```
+
+### Playwright screenshot errors
+
+```bash
+playwright install chromium
+```

package/docs/MCP-INTEGRATION.md

@@ -0,0 +1,153 @@
+<!-- Updated: 2026-02-07 -->
+# MCP Integration
+
+## Overview
+
+SEO Kit can integrate with Model Context Protocol (MCP) servers to access external APIs and enhance analysis capabilities.
+
+## Available Integrations
+
+### PageSpeed Insights API
+
+Use Google's PageSpeed Insights API directly for real Core Web Vitals data.
+
+**Configuration:**
+
+1. Get an API key from [Google Cloud Console](https://console.cloud.google.com/)
+2. Enable the PageSpeed Insights API
+3. Use in your analysis:
+
+```bash
+curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=URL&key=YOUR_API_KEY"
+```
+
+### Google Search Console
+
+For organic search data, use the `mcp-server-gsc` MCP server by [ahonn](https://github.com/ahonn/mcp-server-gsc). Provides search performance data, URL inspection, and sitemap management.
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "google-search-console": {
+      "command": "npx",
+      "args": ["-y", "mcp-server-gsc"],
+      "env": {
+        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json"
+      }
+    }
+  }
+}
+```
+
+### PageSpeed Insights MCP Server
+
+Use `mcp-server-pagespeed` by [enemyrr](https://github.com/enemyrr/mcp-server-pagespeed) for Lighthouse audits, CWV metrics, and performance scoring via MCP.
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "pagespeed": {
+      "command": "npx",
+      "args": ["-y", "mcp-server-pagespeed"],
+      "env": {
+        "PAGESPEED_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Official SEO MCP Servers (2025-2026)
+
+The MCP ecosystem for SEO has matured significantly. These are production-ready integrations:
+
+| Tool | Package / Endpoint | Type | Notes |
+|------|-------------------|------|-------|
+| **Ahrefs** | `@ahrefs/mcp` | Official | Launched July 2025. Supports local and remote modes. Backlinks, keywords, site audit data. |
+| **Semrush** | `https://mcp.semrush.com/v1/mcp` | Official (remote) | Full API access via remote MCP endpoint. Domain analytics, keyword research, backlink data. |
+| **Google Search Console** | `mcp-server-gsc` | Community | By ahonn. Search performance, URL inspection, sitemaps. |
+| **PageSpeed Insights** | `mcp-server-pagespeed` | Community | By enemyrr. Lighthouse audits, CWV metrics, performance scoring. |
+| **DataForSEO** | `dataforseo-mcp-server` | Official extension | 9 modules, 79 tools, 22 commands. Install: `./extensions/dataforseo/install.sh`. See [extension docs](../extensions/dataforseo/README.md). |
+| **kwrds.ai** | kwrds MCP server | Community | Keyword research, search volume, difficulty scoring. |
+| **SEO Review Tools** | SEO Review Tools MCP | Community | Site auditing and on-page analysis API. |
+
+## API Usage Examples
+
+### PageSpeed Insights
+
+```python
+import requests
+
+def get_pagespeed_data(url: str, api_key: str) -> dict:
+    """Fetch PageSpeed Insights data for a URL."""
+    endpoint = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed"
+    params = {
+        "url": url,
+        "key": api_key,
+        "strategy": "mobile",  # or "desktop"
+        "category": ["performance", "accessibility", "best-practices", "seo"]
+    }
+    response = requests.get(endpoint, params=params)
+    return response.json()
+```
+
+### Core Web Vitals from CrUX
+
+```python
+def get_crux_data(url: str, api_key: str) -> dict:
+    """Fetch Chrome UX Report data for a URL."""
+    endpoint = "https://chromeuxreport.googleapis.com/v1/records:queryRecord"
+    payload = {
+        "url": url,
+        "formFactor": "PHONE"  # or "DESKTOP"
+    }
+    headers = {"Content-Type": "application/json"}
+    params = {"key": api_key}
+    response = requests.post(endpoint, json=payload, headers=headers, params=params)
+    return response.json()
+```
+
+## Metrics Available
+
+### From PageSpeed Insights
+
+| Metric | Description |
+|--------|-------------|
+| LCP | Largest Contentful Paint (lab) |
+| INP | Interaction to Next Paint (estimated) |
+| CLS | Cumulative Layout Shift (lab) |
+| FCP | First Contentful Paint |
+| TBT | Total Blocking Time |
+| Speed Index | Visual progress speed |
+
+### From CrUX (Field Data)
+
+| Metric | Description |
+|--------|-------------|
+| LCP | 75th percentile, real users |
+| INP | 75th percentile, real users |
+| CLS | 75th percentile, real users |
+| TTFB | Time to First Byte |
+
+## Best Practices
+
+1. **Rate Limiting**: Respect API quotas (typically 25k requests/day for PageSpeed)
+2. **Caching**: Cache results to avoid redundant API calls
+3. **Field vs Lab**: Prioritize field data (CrUX) for ranking signals
+4. **Error Handling**: Handle API errors gracefully
+
+## Without API Keys
+
+If you don't have API keys, SEO Kit can still:
+
+1. Analyze HTML source for potential issues
+2. Identify common performance problems
+3. Check for render-blocking resources
+4. Evaluate image optimization opportunities
+5. Detect JavaScript-heavy implementations
+
+The analysis will note that actual Core Web Vitals measurements require field data from real users.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,151 @@
+# Troubleshooting
+
+## Common Issues
+
+### Skill Not Loading
+
+**Symptom:** `/seo-audit` or other workflow commands not recognized
+
+**Solutions:**
+
+1. Verify installation:
+```bash
+ls .agent/skills/seo/SKILL.md
+```
+
+2. Check SKILL.md has proper frontmatter:
+```bash
+head -5 .agent/skills/seo/SKILL.md
+```
+Should start with `---` followed by YAML.
+
+3. Ensure `.agent/` directory is at the root of your workspace.
+
+4. Restart your AI agent and re-open the workspace.
+
+---
+
+### Python Dependency Errors
+
+**Symptom:** `ModuleNotFoundError: No module named 'requests'`
+
+**Solution:**
+
+Install dependencies from the project root:
+```bash
+pip install -r requirements.txt
+```
+
+Or install individually:
+```bash
+pip install --user beautifulsoup4 requests lxml playwright Pillow urllib3 validators
+```
+
+### requirements.txt Not Found
+
+**Symptom:** `No such file: requirements.txt` after install
+
+**Solution:** The file should be in the project root. Verify:
+```bash
+ls requirements.txt
+```
+
+### Windows Python Detection Issues
+
+**Symptom:** `python is not recognized` or `pip points to wrong Python`
+
+**Solution:**
+
+1. Install Python from [python.org](https://python.org) and check "Add to PATH"
+2. Or use the Windows launcher: `py -3 -m pip install -r requirements.txt`
+3. Use `python -m pip` instead of bare `pip`
+
+---
+
+### Playwright Screenshot Errors
+
+**Symptom:** `playwright._impl._errors.Error: Executable doesn't exist`
+
+**Solution:**
+```bash
+playwright install chromium
+```
+
+If that fails:
+```bash
+pip install playwright
+python -m playwright install chromium
+```
+
+---
+
+### Permission Denied Errors
+
+**Symptom:** `Permission denied` when running scripts
+
+**Solution:**
+```bash
+chmod +x .agent/skills/seo/scripts/*.py
+```
+
+---
+
+### Timeout Errors
+
+**Symptom:** `Request timed out after 30 seconds`
+
+**Solutions:**
+
+1. The target site may be slow: try again
+2. Increase timeout in script calls
+3. Check your network connection
+4. Some sites block automated requests
+
+---
+
+### Schema Validation False Positives
+
+**Symptom:** Schema flagged incorrectly
+
+**Check:**
+
+1. Ensure placeholders are replaced
+2. Verify @context is `https://schema.org`
+3. Check for deprecated types (HowTo, SpecialAnnouncement)
+4. Validate at [Google's Rich Results Test](https://search.google.com/test/rich-results)
+
+---
+
+### Slow Audit Performance
+
+**Symptom:** Full audit takes too long
+
+**Solutions:**
+
+1. Audit crawls up to 500 pages: large sites take time
+2. Skills can run in parallel to speed up analysis
+3. For faster checks, use `/seo-page` on specific URLs
+4. Check if site has slow response times
+
+---
+
+## Getting Help
+
+1. **Check the docs:** Review [COMMANDS.md](COMMANDS.md) and [ARCHITECTURE.md](ARCHITECTURE.md)
+
+2. **GitHub Issues:** Report bugs at the repository
+
+## Debug Mode
+
+To see detailed output, run scripts directly:
+
+```bash
+# Test fetch
+python3 .agent/skills/seo/scripts/fetch_page.py https://example.com
+
+# Test parse
+python3 .agent/skills/seo/scripts/parse_html.py page.html --json
+
+# Test screenshot
+python3 .agent/skills/seo/scripts/capture_screenshot.py https://example.com
+```