# CLAUDE.md

## Overview

Keyword strategy and research tool for SEO campaigns. Expands seed keywords via our-seo-agent CLI or pre-fetched data, classifies search intent, clusters topics, performs competitor keyword gap analysis, and supports Korean market keyword discovery including Naver autocomplete.

## Quick Start

```bash
# Install dependencies
pip install -r scripts/requirements.txt

# Keyword research from seed keyword
python scripts/keyword_researcher.py --keyword "치과 임플란트" --country kr --json

# Keyword gap analysis vs competitor
python scripts/keyword_gap_analyzer.py --target https://example.com --competitor https://competitor.com --json
```

## Scripts

| Script | Purpose | Key Output |
|--------|---------|------------|
| `keyword_researcher.py` | Expand seed keywords, classify intent, cluster topics | Keyword list with volume, KD, intent, clusters |
| `keyword_gap_analyzer.py` | Find competitor keyword gaps | Gap keywords with opportunity scores |
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |

## Keyword Researcher

```bash
# Basic expansion
python scripts/keyword_researcher.py --keyword "dental implant" --json

# Korean market with suffix expansion
python scripts/keyword_researcher.py --keyword "치과 임플란트" --country kr --korean-suffixes --json

# With volume-by-country comparison
python scripts/keyword_researcher.py --keyword "dental implant" --country kr --compare-global --json

# Output to file
python scripts/keyword_researcher.py --keyword "치과 임플란트" --country kr --output report.json
```

**Capabilities**:
- Seed keyword expansion (matching terms, related terms, search suggestions)
- Korean suffix expansion (추천, 가격, 후기, 잘하는곳, 부작용, 전후)
- Search intent classification (informational/navigational/commercial/transactional)
- Keyword clustering into topic groups
- Volume-by-country comparison (Korea vs global)
- Keyword difficulty scoring

## Keyword Gap Analyzer

```bash
# Find gaps vs one competitor
python scripts/keyword_gap_analyzer.py --target https://example.com --competitor https://competitor.com --json

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

# Filter by minimum volume
python scripts/keyword_gap_analyzer.py --target https://example.com --competitor https://competitor.com --min-volume 100 --json
```

**Capabilities**:
- Identify keywords competitors rank for but target doesn't
- Opportunity scoring based on volume, KD, and competitor positions
- Segment gaps by intent type
- Prioritize low-KD high-volume opportunities

## Data Sources

| Source | Purpose |
|--------|---------|
| `our-seo-agent` CLI | Primary data source (future); use `--input` for pre-fetched JSON |
| WebSearch / WebFetch | Supplementary live data |
| Notion MCP | Save audit report to database |

## Output Format

All scripts support `--json` flag for structured output:

```json
{
  "seed_keyword": "치과 임플란트",
  "country": "kr",
  "total_keywords": 150,
  "clusters": [
    {
      "topic": "임플란트 가격",
      "keywords": [...],
      "total_volume": 12000
    }
  ],
  "keywords": [
    {
      "keyword": "치과 임플란트 가격",
      "volume": 5400,
      "kd": 32,
      "cpc": 2.5,
      "intent": "commercial",
      "cluster": "임플란트 가격"
    }
  ],
  "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 | Keyword Research |
| Priority | Select | Based on opportunity score |
| Found Date | Date | Research date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: KW-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., Keyword Difficulty, Search Volume, CPC)
- URLs and code remain unchanged