# CLAUDE.md

## Overview

Core Web Vitals analyzer using Google PageSpeed Insights API: LCP, FID, CLS, INP, TTFB, FCP measurement and recommendations.

## Quick Start

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

# Requires API key
export PAGESPEED_API_KEY=your_api_key

python scripts/pagespeed_client.py --url https://example.com
```

## Scripts

| Script | Purpose |
|--------|---------|
| `pagespeed_client.py` | PageSpeed Insights API client |
| `base_client.py` | Shared utilities |

## Usage

```bash
# Mobile analysis (default)
python scripts/pagespeed_client.py --url https://example.com

# Desktop analysis
python scripts/pagespeed_client.py --url https://example.com --strategy desktop

# Both strategies
python scripts/pagespeed_client.py --url https://example.com --strategy both

# JSON output
python scripts/pagespeed_client.py --url https://example.com --json

# Batch analysis
python scripts/pagespeed_client.py --urls urls.txt --output results.json
```

## Core Web Vitals Metrics

| Metric | Good | Needs Improvement | Poor |
|--------|------|-------------------|------|
| LCP (Largest Contentful Paint) | ≤2.5s | 2.5s-4s | >4s |
| FID (First Input Delay) | ≤100ms | 100ms-300ms | >300ms |
| CLS (Cumulative Layout Shift) | ≤0.1 | 0.1-0.25 | >0.25 |
| INP (Interaction to Next Paint) | ≤200ms | 200ms-500ms | >500ms |

## Additional Metrics

| Metric | Description |
|--------|-------------|
| TTFB | Time to First Byte |
| FCP | First Contentful Paint |
| SI | Speed Index |
| TBT | Total Blocking Time |

## Output

```json
{
  "url": "https://example.com",
  "strategy": "mobile",
  "score": 85,
  "core_web_vitals": {
    "lcp": {"value": 2.1, "rating": "good"},
    "fid": {"value": 50, "rating": "good"},
    "cls": {"value": 0.05, "rating": "good"},
    "inp": {"value": 180, "rating": "good"}
  },
  "opportunities": [
    {
      "id": "render-blocking-resources",
      "title": "Eliminate render-blocking resources",
      "savings_ms": 1200
    }
  ],
  "diagnostics": []
}
```

## Configuration

Environment variables:
```bash
PAGESPEED_API_KEY=AIza...  # Required for higher quotas
GOOGLE_API_KEY=AIza...     # Alternative key name
```

## Rate Limits

| Tier | Limit |
|------|-------|
| No API key | 25 queries/day |
| With API key | 25,000 queries/day |

## Common Recommendations

| Issue | Fix |
|-------|-----|
| Large LCP | Optimize images, preload critical resources |
| High CLS | Set image dimensions, avoid injected content |
| Poor INP | Reduce JavaScript, optimize event handlers |
| Slow TTFB | Improve server response, use CDN |

## Dependencies

```
google-api-python-client>=2.100.0
requests>=2.31.0
python-dotenv>=1.0.0
rich>=13.7.0
```

## 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 | Technical SEO, On-page SEO, Performance, Schema/Structured Data, Sitemap, Robots.txt, Content, Local SEO |
| Priority | Select | Critical, High, Medium, Low |
| Found Date | Date | Audit date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: [TYPE]-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

### Example MCP Call

```bash
mcp-cli call notion/API-post-page '{"parent": {"database_id": "2c8581e5-8a1e-8035-880b-e38cefc2f3ef"}, "properties": {...}}'
```