# CLAUDE.md

## Overview

AI search visibility and brand radar tool for tracking how a brand appears in AI-generated search answers. Monitors AI answer citations, tracks share of voice in AI search vs competitors, analyzes cited domains and pages, and tracks impressions/mentions history. Uses Ahrefs Brand Radar APIs for comprehensive AI visibility monitoring.

## Quick Start

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

# AI visibility tracking
python scripts/ai_visibility_tracker.py --target example.com --json

# AI citation analysis
python scripts/ai_citation_analyzer.py --target example.com --json
```

## Scripts

| Script | Purpose | Key Output |
|--------|---------|------------|
| `ai_visibility_tracker.py` | Track brand visibility in AI search results | AI impressions, mentions, share of voice, trends |
| `ai_citation_analyzer.py` | Analyze AI answer citations and source pages | Cited domains, cited pages, AI response analysis |
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |

## AI Visibility Tracker

```bash
# Current visibility overview
python scripts/ai_visibility_tracker.py --target example.com --json

# With competitor comparison
python scripts/ai_visibility_tracker.py --target example.com --competitor comp1.com --competitor comp2.com --json

# Historical trend (impressions/mentions)
python scripts/ai_visibility_tracker.py --target example.com --history --json

# Share of voice analysis
python scripts/ai_visibility_tracker.py --target example.com --sov --json
```

**Capabilities**:
- AI impressions overview (how often brand appears in AI answers)
- AI mentions overview (brand mention frequency across AI engines)
- Share of Voice in AI search vs competitors
- Impressions history over time (trend tracking)
- Mentions history over time
- SOV history and trend analysis
- Competitor AI visibility comparison

## AI Citation Analyzer

```bash
# Analyze AI citations for brand
python scripts/ai_citation_analyzer.py --target example.com --json

# Cited domains analysis
python scripts/ai_citation_analyzer.py --target example.com --cited-domains --json

# Cited pages analysis
python scripts/ai_citation_analyzer.py --target example.com --cited-pages --json

# AI response content analysis
python scripts/ai_citation_analyzer.py --target example.com --responses --json
```

**Capabilities**:
- AI response analysis (how the brand appears in AI-generated answers)
- Cited domains analysis (which source domains AI engines reference)
- Cited pages analysis (which specific URLs get cited)
- Citation sentiment and context analysis
- Citation frequency ranking
- Competitor citation comparison
- Recommendation generation for improving AI visibility

## Ahrefs MCP Tools Used

| Tool | Purpose |
|------|---------|
| `brand-radar-ai-responses` | Get AI-generated responses mentioning brand |
| `brand-radar-cited-domains` | Domains cited in AI answers |
| `brand-radar-cited-pages` | Specific pages cited in AI answers |
| `brand-radar-impressions-history` | Brand impression trend over time |
| `brand-radar-impressions-overview` | Current impression metrics |
| `brand-radar-mentions-history` | Brand mention trend over time |
| `brand-radar-mentions-overview` | Current mention metrics |
| `brand-radar-sov-history` | Share of voice trend |
| `brand-radar-sov-overview` | Current share of voice |

## Output Format

```json
{
  "target": "example.com",
  "impressions": {
    "total": 15000,
    "trend": "increasing",
    "change_pct": 12.5
  },
  "mentions": {
    "total": 850,
    "trend": "stable",
    "change_pct": 2.1
  },
  "share_of_voice": {
    "brand_sov": 18.5,
    "competitors": [
      {"domain": "comp1.com", "sov": 25.3},
      {"domain": "comp2.com", "sov": 15.8}
    ]
  },
  "cited_domains": [...],
  "cited_pages": [...],
  "ai_responses_sample": [...],
  "recommendations": [...],
  "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 | Tracked website URL |
| Category | Select | AI Search Visibility |
| Priority | Select | Based on SOV trend |
| Found Date | Date | Report date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: AI-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., AI Search, Share of Voice, Brand Radar)
- URLs and code remain unchanged