# CLAUDE.md

## Overview

Link building diagnosis tool for backlink profile analysis, toxic link detection, competitor link gap identification, and link velocity tracking. Supports Korean platform link mapping (Naver Blog, Cafe, Tistory, Brunch, Korean news sites).

## Quick Start

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

# Backlink profile audit
python scripts/backlink_auditor.py --url https://example.com --json

# Link gap analysis vs competitors
python scripts/link_gap_finder.py --target https://example.com --competitor https://competitor.com --json
```

## Scripts

| Script | Purpose | Key Output |
|--------|---------|------------|
| `backlink_auditor.py` | Analyze backlink profile, detect toxic links | DR, referring domains, anchor distribution, toxic links |
| `link_gap_finder.py` | Find link gap opportunities vs competitors | Domains linking to competitors but not target |
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |

## Backlink Auditor

```bash
# Full backlink audit
python scripts/backlink_auditor.py --url https://example.com --json

# Check link velocity (new/lost over time)
python scripts/backlink_auditor.py --url https://example.com --velocity --json

# Find broken backlinks for recovery
python scripts/backlink_auditor.py --url https://example.com --broken --json

# Korean platform link analysis
python scripts/backlink_auditor.py --url https://example.com --korean-platforms --json
```

**Capabilities**:
- Domain Rating (DR) and backlink stats overview
- Referring domain analysis (count, DR distribution, country distribution)
- Anchor text distribution analysis (branded, exact-match, generic, naked URL)
- Toxic link detection (PBN patterns, spammy domains, link farms)
- Link velocity tracking (new/lost referring domains over time)
- Broken backlink recovery opportunities
- Korean platform mapping (Naver Blog, Naver Cafe, Tistory, Brunch, Korean news)

## Link Gap Finder

```bash
# Gap vs one competitor
python scripts/link_gap_finder.py --target https://example.com --competitor https://comp1.com --json

# Multiple competitors
python scripts/link_gap_finder.py --target https://example.com --competitor https://comp1.com --competitor https://comp2.com --json

# Filter by minimum DR
python scripts/link_gap_finder.py --target https://example.com --competitor https://comp1.com --min-dr 30 --json
```

**Capabilities**:
- Find domains linking to competitors but not target
- Score link opportunities by DR, traffic, relevance
- Categorize link sources (editorial, directory, forum, blog, news)
- Prioritize by feasibility and impact

## Ahrefs MCP Tools Used

| Tool | Purpose |
|------|---------|
| `site-explorer-all-backlinks` | Get all backlinks for a target |
| `site-explorer-backlinks-stats` | Backlink statistics overview |
| `site-explorer-referring-domains` | List referring domains |
| `site-explorer-anchors` | Anchor text distribution |
| `site-explorer-broken-backlinks` | Find broken backlinks |
| `site-explorer-domain-rating` | Get Domain Rating |
| `site-explorer-domain-rating-history` | DR trend over time |
| `site-explorer-refdomains-history` | Referring domains trend |
| `site-explorer-linked-domains` | Domains linked from target |

## Output Format

```json
{
  "url": "https://example.com",
  "domain_rating": 45,
  "backlink_stats": {
    "total_backlinks": 12500,
    "referring_domains": 850,
    "dofollow_ratio": 0.72
  },
  "anchor_distribution": {
    "branded": 35,
    "exact_match": 12,
    "partial_match": 18,
    "generic": 20,
    "naked_url": 15
  },
  "toxic_links": [...],
  "korean_platforms": {
    "naver_blog": 45,
    "naver_cafe": 12,
    "tistory": 23,
    "brunch": 5
  },
  "link_velocity": {
    "new_last_30d": 120,
    "lost_last_30d": 35
  },
  "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 | Audited website URL |
| Category | Select | Link Building |
| Priority | Select | Based on toxic link count and gap size |
| Found Date | Date | Audit date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: LINK-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., Domain Rating, Referring Domains, Backlinks)
- URLs and code remain unchanged