# CLAUDE.md

## Overview

SEO reporting dashboard and executive report generator. Aggregates outputs from all SEO skills (11-33) into stakeholder-ready reports with interactive HTML dashboards, trend analysis, and Korean-language executive summaries. This is the PRESENTATION LAYER that sits on top of skill 25 (KPI Framework) and all other skill outputs, providing a unified view of SEO performance across all audit dimensions.

## Quick Start

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

# Aggregate outputs from all SEO skills
python scripts/report_aggregator.py --domain https://example.com --json

# Generate HTML dashboard
python scripts/dashboard_generator.py --report aggregated_report.json --output dashboard.html

# Generate Korean executive report
python scripts/executive_report.py --report aggregated_report.json --audience c-level --output report.md
```

## Scripts

| Script | Purpose | Key Output |
|--------|---------|------------|
| `report_aggregator.py` | Collect and normalize outputs from all SEO skills | Unified aggregated report, cross-skill health score, priority issues |
| `dashboard_generator.py` | Generate interactive HTML dashboard with Chart.js | Self-contained HTML file with charts and responsive layout |
| `executive_report.py` | Korean-language executive summary generation | Markdown report tailored to audience level |
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |

## Report Aggregator

```bash
# Aggregate all skill outputs for a domain
python scripts/report_aggregator.py --domain https://example.com --json

# Specify output directory to scan
python scripts/report_aggregator.py --domain https://example.com --output-dir ./audit_outputs --json

# Filter by date range
python scripts/report_aggregator.py --domain https://example.com --from 2025-01-01 --to 2025-03-31 --json

# Save to file
python scripts/report_aggregator.py --domain https://example.com --json --output report.json
```

**Capabilities**:
- Scan for recent audit outputs from skills 11-33 (JSON files or Notion entries)
- Normalize data formats across skills into unified structure
- Merge findings by domain/date
- Compute cross-skill health scores with weighted dimensions
- Identify top-priority issues across all audits
- Timeline of audit history
- Support for both local file scanning and Notion database queries

## Dashboard Generator

```bash
# Generate HTML dashboard from aggregated report
python scripts/dashboard_generator.py --report aggregated_report.json --output dashboard.html

# Custom title
python scripts/dashboard_generator.py --report aggregated_report.json --output dashboard.html --title "OurDigital SEO Dashboard"
```

**Capabilities**:
- Generate self-contained HTML dashboard (uses Chart.js from CDN)
- Health score gauge chart
- Traffic trend line chart
- Keyword ranking distribution bar chart
- Technical issues breakdown pie chart
- Competitor comparison radar chart
- Mobile-responsive layout with CSS grid
- Export as single .html file (no external dependencies)

## Executive Report

```bash
# C-level executive summary (Korean)
python scripts/executive_report.py --report aggregated_report.json --audience c-level --output report.md

# Marketing team report
python scripts/executive_report.py --report aggregated_report.json --audience marketing --output report.md

# Technical team report
python scripts/executive_report.py --report aggregated_report.json --audience technical --output report.md

# Output to Notion instead of file
python scripts/executive_report.py --report aggregated_report.json --audience c-level --format notion
```

**Capabilities**:
- Korean-language executive summary generation
- Key wins and concerns identification
- Period-over-period comparison narrative
- Priority action items ranked by impact
- Stakeholder-appropriate language (non-technical for C-level)
- Support for C-level, marketing team, and technical team audiences
- Markdown output format

## Data Sources

| Source | Purpose |
|--------|---------|
| `our-seo-agent` CLI | Primary data source (future); use `--input` flag to provide pre-fetched JSON |
| `--output-dir` flag | Scan local JSON files from skills 11-33 |
| WebSearch / WebFetch | Supplementary data for trend context |
| Notion MCP | Query past audits from SEO Audit Log database |

## Output Format

```json
{
  "domain": "example.com",
  "report_date": "2025-01-15",
  "overall_health": 72,
  "health_trend": "improving",
  "skills_included": [
    {"skill_id": 11, "skill_name": "comprehensive-audit", "audit_date": "2025-01-14"},
    {"skill_id": 25, "skill_name": "kpi-framework", "audit_date": "2025-01-15"}
  ],
  "category_scores": {
    "technical": 85,
    "on_page": 70,
    "performance": 60,
    "content": 75,
    "links": 68,
    "local": 65,
    "keywords": 72,
    "competitor": 58
  },
  "top_issues": [
    {"severity": "critical", "category": "performance", "description": "CLS exceeds threshold on mobile"},
    {"severity": "high", "category": "technical", "description": "12 pages with noindex tag incorrectly set"}
  ],
  "top_wins": [
    {"category": "links", "description": "Domain Rating increased by 3 points"},
    {"category": "keywords", "description": "15 new keywords entered top 10"}
  ],
  "timeline": [
    {"date": "2025-01-15", "skill": "kpi-framework", "health_score": 72},
    {"date": "2025-01-14", "skill": "comprehensive-audit", "health_score": 70}
  ],
  "audit_id": "DASH-20250115-001",
  "timestamp": "2025-01-15T14:30: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 | SEO Dashboard |
| Priority | Select | Based on overall health trend |
| Found Date | Date | Report date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: DASH-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., Health Score, Domain Rating, Core Web Vitals, Chart.js)
- URLs and code remain unchanged