# CLAUDE.md

## Overview

Knowledge Graph and Entity SEO tool for analyzing brand entity presence in Google Knowledge Graph, Knowledge Panels, People Also Ask (PAA), and FAQ rich results. Checks entity attribute completeness, Wikipedia/Wikidata presence, and Korean equivalents (Naver knowledge iN, Naver encyclopedia). Uses WebSearch and WebFetch for data collection, WebSearch for SERP feature detection.

## Quick Start

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

# Knowledge Graph analysis
python scripts/knowledge_graph_analyzer.py --entity "Samsung Electronics" --json

# Entity SEO audit
python scripts/entity_auditor.py --url https://example.com --entity "Brand Name" --json
```

## Scripts

| Script | Purpose | Key Output |
|--------|---------|------------|
| `knowledge_graph_analyzer.py` | Analyze Knowledge Panel and entity presence | KP detection, entity attributes, Wikipedia/Wikidata status |
| `entity_auditor.py` | Audit entity SEO signals and PAA/FAQ presence | PAA monitoring, FAQ schema tracking, entity completeness |
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |

## Knowledge Graph Analyzer

```bash
# Analyze entity in Knowledge Graph
python scripts/knowledge_graph_analyzer.py --entity "Samsung Electronics" --json

# Check with Korean name
python scripts/knowledge_graph_analyzer.py --entity "삼성전자" --language ko --json

# Include Wikipedia/Wikidata check
python scripts/knowledge_graph_analyzer.py --entity "Samsung" --wiki --json
```

**Capabilities**:
- Knowledge Panel detection via Google search
- Entity attribute extraction (name, description, logo, type, social profiles, website)
- Entity attribute completeness scoring
- Wikipedia article presence check
- Wikidata entity presence check (QID lookup)
- Naver encyclopedia (네이버 백과사전) presence
- Naver knowledge iN (지식iN) presence
- Knowledge Panel comparison with competitors

## Entity Auditor

```bash
# Full entity SEO audit
python scripts/entity_auditor.py --url https://example.com --entity "Brand Name" --json

# PAA monitoring for brand keywords
python scripts/entity_auditor.py --url https://example.com --entity "Brand Name" --paa --json

# FAQ rich result tracking
python scripts/entity_auditor.py --url https://example.com --entity "Brand Name" --faq --json
```

**Capabilities**:
- People Also Ask (PAA) monitoring for brand-related queries
- FAQ schema presence tracking (FAQPage schema -> SERP appearance)
- Entity markup audit (Organization, Person, LocalBusiness schema on website)
- Social profile linking validation (sameAs in schema)
- Brand SERP analysis (what appears when you search the brand name)
- Entity consistency across web properties
- Korean entity optimization (Korean Knowledge Panel, Naver profiles)

## Data Sources

| Source | Purpose |
|--------|---------|
| WebSearch | Search for entity/brand to detect Knowledge Panel |
| WebFetch | Fetch Wikipedia, Wikidata, Naver pages |
| WebSearch | SERP feature detection for entity keywords |

## Output Format

```json
{
  "entity": "Samsung Electronics",
  "knowledge_panel": {
    "detected": true,
    "attributes": {
      "name": "Samsung Electronics",
      "type": "Corporation",
      "description": "...",
      "logo": true,
      "website": true,
      "social_profiles": ["twitter", "facebook", "linkedin"]
    },
    "completeness_score": 85
  },
  "wikipedia": {"present": true, "url": "..."},
  "wikidata": {"present": true, "qid": "Q20710"},
  "naver_encyclopedia": {"present": true, "url": "..."},
  "naver_knowledge_in": {"present": true, "entries": 15},
  "paa_questions": [...],
  "faq_rich_results": [...],
  "entity_schema_on_site": {
    "organization": true,
    "same_as_links": 5,
    "completeness": 78
  },
  "score": 75,
  "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 | Entity website URL |
| Category | Select | Knowledge Graph & Entity SEO |
| Priority | Select | Based on entity completeness |
| Found Date | Date | Audit date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: KG-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., Knowledge Panel, Knowledge Graph, PAA)
- URLs and code remain unchanged
