# CLAUDE.md

## Overview

Comprehensive SEO audit orchestrator. Runs 6 sub-skill audits (Technical, On-Page, CWV, Schema, Local, GSC), merges results into a unified report with weighted health score (0-100), and pushes to Notion.

## Quick Start

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

# Run full audit
python scripts/seo_audit_orchestrator.py --url https://example.com

# Skip optional stages
python scripts/seo_audit_orchestrator.py --url https://example.com --skip-local --skip-gsc

# JSON output only (no Notion push)
python scripts/seo_audit_orchestrator.py --url https://example.com --json
```

## Scripts

| Script | Purpose |
|--------|---------|
| `seo_audit_orchestrator.py` | Orchestrate all 6 audit stages and compute health score |

## Pipeline

| Stage | Audit | Script |
|-------|-------|--------|
| 1 | Technical SEO | `12-seo-technical-audit/code/scripts/robots_checker.py`, `sitemap_validator.py` |
| 2 | On-Page SEO | `13-seo-on-page-audit/code/scripts/page_analyzer.py` |
| 3 | Core Web Vitals | `14-seo-core-web-vitals/code/scripts/pagespeed_client.py` |
| 4 | Schema Validation | `16-seo-schema-validator/code/scripts/schema_validator.py` |
| 5 | Local SEO | `18-seo-local-audit/` (prompt-driven — see Stage 5 notes below) |
| 6 | Search Console | `15-seo-search-console/code/scripts/gsc_client.py` |

## Stage 5: Local SEO — Key Requirements

Stage 5 is prompt-driven and requires **Business Identity extraction as a mandatory first step**:
1. Extract Korean name, English name, address, phone from website JSON-LD schema markup (`Organization`/`Hospital`/`LocalBusiness`)
2. Check website footer, contact page, and schema `sameAs` for GBP, Naver Place, and Kakao Map URLs
3. Use layered search fallback if listing URLs are not found on the website
4. Follow `18-seo-local-audit/code/CLAUDE.md` for the full workflow
5. **Korean market priorities**: GBP and Naver Smart Place are both Critical; Kakao Map is High; US-centric directories (Yelp, Yellow Pages) are Low
6. **Important**: GBP and Naver Map are JS-rendered. Report unfound listings as "not discoverable via web search" — not "does not exist"

## Extended SEO Skills Pipeline

Beyond the 6 core audit stages, additional specialized skills are available for deeper analysis:

| Skill | Audit ID | Purpose | Command |
|-------|----------|---------|---------|
| 19 - Keyword Strategy | KW | Seed expansion, intent classification, keyword gaps | `/seo-keyword-strategy` |
| 20 - SERP Analysis | SERP | Google/Naver SERP features, competitor positions | `/seo-serp-analysis` |
| 21 - Position Tracking | RANK | Rank monitoring, visibility scores, alerts | `/seo-position-tracking` |
| 22 - Link Building | LINK | Backlink audit, toxic links, link gaps | `/seo-link-building` |
| 23 - Content Strategy | CONTENT | Content audit, decay detection, briefs | `/seo-content-strategy` |
| 24 - E-Commerce SEO | ECOM | Product page audit, product schema | `/seo-ecommerce` |
| 25 - SEO KPI Framework | KPI | Unified KPIs, health scores, ROI | `/seo-kpi-framework` |
| 26 - International SEO | INTL | Hreflang validation, content parity | `/seo-international` |
| 27 - AI Visibility | AI | AI search citations, brand radar, SOV | `/seo-ai-visibility` |
| 28 - Knowledge Graph | KG | Entity SEO, Knowledge Panel, PAA | `/seo-knowledge-graph` |
| 31 - Competitor Intel | COMP | Competitor profiling, benchmarking | `/seo-competitor-intel` |
| 32 - Crawl Budget | CRAWL | Log analysis, bot profiling, waste | `/seo-crawl-budget` |

## Health Score Weights

| Category | Weight |
|----------|--------|
| Technical SEO | 20% |
| On-Page SEO | 20% |
| Core Web Vitals | 25% |
| Schema | 15% |
| Local SEO | 10% |
| Search Console | 10% |

## 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 | `종합 SEO 감사 보고서 - [domain] - YYYY-MM-DD` |
| Site | URL | Audited website URL |
| Category | Select | Comprehensive Audit |
| Priority | Select | Based on health score |
| Found Date | Date | Audit date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: COMP-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., SEO Audit, Core Web Vitals, Schema Markup)
- URLs and code remain unchanged