# CLAUDE.md

## Overview

SEO site migration planning and monitoring tool for comprehensive pre-migration risk assessment, redirect mapping, URL inventory, crawl baseline capture, and post-migration traffic/indexation monitoring. Supports domain moves, platform changes, URL restructuring, HTTPS migrations, and subdomain consolidation. Captures full URL inventory via Firecrawl crawl, builds traffic/keyword baselines via Ahrefs, generates redirect maps with per-URL risk scoring, and tracks post-launch recovery with automated alerts.

## Quick Start

```bash
pip install -r scripts/requirements.txt

# Pre-migration planning
python scripts/migration_planner.py --domain https://example.com --type domain-move --new-domain https://new-example.com --json

# Post-migration monitoring
python scripts/migration_monitor.py --domain https://new-example.com --migration-date 2025-01-15 --baseline baseline.json --json
```

## Scripts

| Script | Purpose | Key Output |
|--------|---------|------------|
| `migration_planner.py` | Pre-migration baseline + redirect map + risk assessment | URL inventory, redirect map, risk scores, checklist |
| `migration_monitor.py` | Post-migration traffic comparison, redirect health, indexation tracking | Traffic delta, broken redirects, ranking changes, alerts |
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |

## Migration Planner

```bash
# Domain move planning
python scripts/migration_planner.py --domain https://example.com --type domain-move --new-domain https://new-example.com --json

# Platform migration (e.g., WordPress to headless)
python scripts/migration_planner.py --domain https://example.com --type platform --json

# URL restructuring
python scripts/migration_planner.py --domain https://example.com --type url-restructure --json

# HTTPS migration
python scripts/migration_planner.py --domain http://example.com --type https --json

# Subdomain consolidation
python scripts/migration_planner.py --domain https://blog.example.com --type subdomain --new-domain https://example.com/blog --json
```

**Capabilities**:
- URL inventory via Firecrawl crawl (capture all URLs + status codes)
- Ahrefs top-pages baseline (traffic, keywords per page)
- Redirect map generation (old URL -> new URL mapping)
- Risk scoring per URL (based on traffic + backlinks + keyword rankings)
- Pre-migration checklist generation
- Support for migration types:
  - Domain move (old domain -> new domain)
  - Platform change (CMS/framework swap)
  - URL restructuring (path/slug changes)
  - HTTPS migration (HTTP -> HTTPS)
  - Subdomain consolidation (subdomain -> subfolder)

## Migration Monitor

```bash
# Post-launch traffic comparison
python scripts/migration_monitor.py --domain https://new-example.com --migration-date 2025-01-15 --baseline baseline.json --json

# Monitor with custom period
python scripts/migration_monitor.py --domain https://new-example.com --migration-date 2025-01-15 --baseline baseline.json --json

# Quick redirect health check
python scripts/migration_monitor.py --domain https://new-example.com --migration-date 2025-01-15 --json
```

**Capabilities**:
- Post-launch traffic comparison (pre vs post, by page group)
- Redirect chain/loop detection
- 404 monitoring for high-value pages
- Indexation tracking (indexed pages before vs after)
- Ranking change tracking for priority keywords
- Recovery timeline estimation
- Alert generation for traffic drops >20%

## Ahrefs MCP Tools Used

| Tool | Purpose |
|------|---------|
| `site-explorer-metrics` | Current organic metrics (traffic, keywords) |
| `site-explorer-metrics-history` | Historical metrics for pre/post comparison |
| `site-explorer-top-pages` | Top performing pages for baseline |
| `site-explorer-pages-by-traffic` | Pages ranked by traffic for risk scoring |
| `site-explorer-organic-keywords` | Keyword rankings per page |
| `site-explorer-referring-domains` | Referring domains per page for risk scoring |
| `site-explorer-backlinks-stats` | Backlink overview for migration impact |

## Output Format

```json
{
  "domain": "example.com",
  "migration_type": "domain-move",
  "baseline": {
    "total_urls": 1250,
    "total_traffic": 45000,
    "total_keywords": 8500,
    "top_pages": []
  },
  "redirect_map": [
    {
      "source": "https://example.com/page-1",
      "target": "https://new-example.com/page-1",
      "status_code": 301,
      "priority": "critical"
    }
  ],
  "risk_assessment": {
    "high_risk_urls": 45,
    "medium_risk_urls": 180,
    "low_risk_urls": 1025,
    "overall_risk": "medium"
  },
  "pre_migration_checklist": [],
  "timestamp": "2025-01-01T00:00:00"
}
```

## Notion Output (Required)

**IMPORTANT**: All audit reports MUST be saved to the OurDigital SEO Audit Log database.

### Database Configuration

| Field | Value |
|-------|-------|
| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
| URL | https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef |

### Required Properties

| Property | Type | Description |
|----------|------|-------------|
| Issue | Title | Report title (Korean + date) |
| Site | URL | Target website URL |
| Category | Select | SEO Migration |
| Priority | Select | Based on risk level |
| Found Date | Date | Report date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: MIGR-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., Redirect Map, Risk Score, Traffic Baseline, Indexation)
- URLs and code remain unchanged