# OurDigital SEO Audit - User Guide

## Table of Contents

1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Quick Start](#quick-start)
4. [Features](#features)
5. [Usage Examples](#usage-examples)
6. [API Reference](#api-reference)
7. [Notion Integration](#notion-integration)
8. [Troubleshooting](#troubleshooting)

---

## Overview

The **ourdigital-seo-audit** skill is a comprehensive SEO audit tool for Claude Code that:

- Performs technical SEO analysis
- Validates schema markup (JSON-LD, Microdata, RDFa)
- Checks sitemap and robots.txt configuration
- Measures Core Web Vitals performance
- Integrates with Google APIs (Search Console, Analytics, PageSpeed)
- Exports findings to Notion database

### Supported Audit Categories

| Category | Description |
|----------|-------------|
| Technical SEO | HTTPS, canonicals, redirects, crawlability |
| On-page SEO | Meta tags, headings, images, internal links |
| Content | Quality, duplication, freshness, E-E-A-T |
| Local SEO | NAP consistency, citations, LocalBusiness schema |
| Performance | Core Web Vitals (LCP, CLS, TBT, FCP) |
| Schema/Structured Data | JSON-LD validation, rich results eligibility |
| Sitemap | XML validation, URL accessibility |
| Robots.txt | Directive analysis, blocking issues |

---

## Prerequisites

### 1. Python Environment

```bash
# Install required packages
cd ~/.claude/skills/ourdigital-seo-audit/scripts
pip install -r requirements.txt
```

### 2. Google Cloud Service Account

The skill uses a service account for authenticated APIs:

```
File: ~/.credential/ourdigital-seo-agent.json
Service Account: ourdigital-seo-agent@ourdigital-insights.iam.gserviceaccount.com
Project: ourdigital-insights
```

**Required permissions:**
- Search Console: Add service account email as user in [Search Console](https://search.google.com/search-console)
- GA4: Add service account as Viewer in [Google Analytics](https://analytics.google.com)

### 3. API Keys

Located in `~/Workspaces/claude-workspace/.env`:

```bash
# Google API Key (for PageSpeed, Custom Search, Knowledge Graph)
GOOGLE_API_KEY=your-api-key
PAGESPEED_API_KEY=your-api-key
CUSTOM_SEARCH_API_KEY=your-api-key
CUSTOM_SEARCH_ENGINE_ID=your-cx-id
```

### 4. Enabled Google Cloud APIs

Enable these APIs in [Google Cloud Console](https://console.cloud.google.com/apis/library):

- Search Console API
- PageSpeed Insights API
- Google Analytics Admin API
- Google Analytics Data API
- Custom Search API
- Knowledge Graph Search API

---

## Quick Start

### Run a Full SEO Audit

```
Perform a comprehensive SEO audit for https://example.com
```

### Check Core Web Vitals

```
Check Core Web Vitals for https://example.com
```

### Validate Schema Markup

```
Validate schema markup on https://example.com
```

### Check Sitemap

```
Validate the sitemap at https://example.com/sitemap.xml
```

### Analyze Robots.txt

```
Analyze robots.txt for example.com
```

---

## Features

### 1. Technical SEO Analysis

Checks for:
- HTTPS/SSL implementation
- Canonical URL configuration
- Redirect chains and loops
- 404 error pages
- Mobile-friendliness
- Hreflang tags (international sites)

**Command:**
```
Check technical SEO for https://example.com
```

### 2. Schema Markup Validation

Extracts and validates structured data:
- JSON-LD (recommended)
- Microdata
- RDFa

Supported schema types:
- Organization / LocalBusiness
- Product / Offer
- Article / BlogPosting
- FAQPage / HowTo
- BreadcrumbList
- WebSite / WebPage

**Command:**
```
Validate existing schema markup on https://example.com
```

### 3. Schema Generation

Generate JSON-LD markup for your pages:

**Command:**
```
Generate Organization schema for https://example.com
```

**Available types:**
- `organization` - Company/organization info
- `local_business` - Physical business location
- `product` - E-commerce products
- `article` - Blog posts and news
- `faq` - FAQ pages
- `breadcrumb` - Navigation breadcrumbs
- `website` - Site-level schema with search

### 4. Sitemap Validation

Validates XML sitemaps for:
- XML syntax errors
- URL accessibility (HTTP status)
- URL count limits (50,000 max)
- File size limits (50MB max)
- Lastmod date validity
- Index sitemap structure

**Command:**
```
Validate the sitemap at https://example.com/sitemap.xml
```

### 5. Robots.txt Analysis

Analyzes robots.txt for:
- Syntax validation
- User-agent rules
- Disallow/Allow patterns
- Sitemap declarations
- Critical resource blocking
- URL testing against rules

**Command:**
```
Analyze robots.txt for example.com
```

### 6. Core Web Vitals

Measures performance metrics:

| Metric | Good | Needs Improvement | Poor |
|--------|------|-------------------|------|
| LCP (Largest Contentful Paint) | < 2.5s | 2.5s - 4.0s | > 4.0s |
| CLS (Cumulative Layout Shift) | < 0.1 | 0.1 - 0.25 | > 0.25 |
| TBT (Total Blocking Time) | < 200ms | 200ms - 600ms | > 600ms |
| FCP (First Contentful Paint) | < 1.8s | 1.8s - 3.0s | > 3.0s |

**Command:**
```
Check Core Web Vitals for https://example.com
```

### 7. Search Console Integration

Access search performance data:
- Top queries and pages
- Click-through rates
- Average positions
- Indexing status

**Command:**
```
Get Search Console data for sc-domain:example.com
```

### 8. GA4 Analytics Integration

Access traffic and behavior data:
- Page views
- User sessions
- Traffic sources
- Engagement metrics

**Available properties:**
- OurDigital Lab (218477407)
- OurDigital Journal (413643875)
- OurDigital Blog (489750460)

**Command:**
```
Get GA4 traffic data for OurDigital Blog
```

---

## Usage Examples

### Example 1: Full Site Audit with Notion Export

```
Perform a comprehensive SEO audit for https://blog.ourdigital.org and export findings to Notion
```

This will:
1. Check robots.txt configuration
2. Validate sitemap
3. Analyze schema markup
4. Run PageSpeed analysis
5. Export all findings to the OurDigital SEO Audit Log database

### Example 2: Schema Audit Only

```
Check schema markup on https://blog.ourdigital.org and identify any issues
```

### Example 3: Performance Deep Dive

```
Analyze Core Web Vitals for https://blog.ourdigital.org and provide optimization recommendations
```

### Example 4: Competitive Analysis

```
Compare SEO performance between https://blog.ourdigital.org and https://competitor.com
```

### Example 5: Local SEO Audit

```
Perform local SEO audit for OurDigital in Seoul, Korea
```

---

## API Reference

### Python Scripts

All scripts are located in `~/.claude/skills/ourdigital-seo-audit/scripts/`

#### robots_checker.py

```bash
python robots_checker.py --url https://example.com
```

Options:
- `--url` - Base URL to check
- `--test-url` - Specific URL to test against rules
- `--user-agent` - User agent to test (default: Googlebot)

#### sitemap_validator.py

```bash
python sitemap_validator.py --url https://example.com/sitemap.xml
```

Options:
- `--url` - Sitemap URL
- `--check-urls` - Verify URL accessibility (slower)
- `--limit` - Max URLs to check

#### schema_validator.py

```bash
python schema_validator.py --url https://example.com
```

Options:
- `--url` - Page URL to validate
- `--check-rich-results` - Check Google Rich Results eligibility

#### schema_generator.py

```bash
python schema_generator.py --type organization --url https://example.com
```

Options:
- `--type` - Schema type (organization, local_business, product, article, faq, breadcrumb, website)
- `--url` - Target URL
- `--output` - Output file (default: stdout)

#### pagespeed_client.py

```bash
python pagespeed_client.py --url https://example.com --strategy mobile
```

Options:
- `--url` - URL to analyze
- `--strategy` - mobile, desktop, or both
- `--json` - Output as JSON
- `--cwv-only` - Show only Core Web Vitals

#### gsc_client.py

```bash
python gsc_client.py --site sc-domain:example.com --action summary
```

Options:
- `--site` - Site URL (sc-domain: or https://)
- `--action` - summary, queries, pages, sitemaps, inspect
- `--days` - Days of data (default: 30)

#### full_audit.py

```bash
python full_audit.py --url https://example.com --output notion
```

Options:
- `--url` - URL to audit
- `--output` - console, notion, or json
- `--no-robots` - Skip robots.txt check
- `--no-sitemap` - Skip sitemap validation
- `--no-schema` - Skip schema validation
- `--no-performance` - Skip PageSpeed analysis

---

## Notion Integration

### Default Database

All findings are stored in the **OurDigital SEO Audit Log**:

- **Database ID**: `2c8581e5-8a1e-8035-880b-e38cefc2f3ef`
- **URL**: https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef

### Database Properties

| Property | Type | Description |
|----------|------|-------------|
| Issue | Title | Issue title |
| Site | URL | Audited site URL |
| Category | Select | Issue category |
| Priority | Select | Critical / High / Medium / Low |
| Status | Status | Not started / In progress / Done |
| URL | URL | Specific page with issue |
| Found Date | Date | Discovery date |
| Audit ID | Text | Groups findings by session |

### Page Content Template

Each finding page contains:

```
## Description
[Detailed explanation of the issue]

## Impact
⚠️ [Business/ranking impact]

## Recommendation
💡 [Actionable solution]
```

### Filtering Findings

Use Notion filters to view:
- **By Site**: Filter by Site property
- **By Category**: Filter by Category (Schema, Performance, etc.)
- **By Priority**: Filter by Priority (Critical first)
- **By Audit**: Filter by Audit ID to see all findings from one session

---

## Troubleshooting

### API Authentication Errors

**Error: "Invalid JWT Signature"**
- Check that the service account key file exists
- Verify the file path in `~/.credential/ourdigital-seo-agent.json`
- Regenerate the key in Google Cloud Console if corrupted

**Error: "Requests from referer are blocked"**
- Go to [API Credentials](https://console.cloud.google.com/apis/credentials)
- Click on your API key
- Set "Application restrictions" to "None"
- Save and wait 1-2 minutes

**Error: "API has not been enabled"**
- Enable the required API in [Google Cloud Console](https://console.cloud.google.com/apis/library)
- Wait a few minutes for propagation

### Search Console Issues

**Error: "Site not found"**
- Use domain property format: `sc-domain:example.com`
- Or URL prefix format: `https://www.example.com/`
- Add service account email as user in Search Console

### PageSpeed Rate Limiting

**Error: "429 Too Many Requests"**
- Wait a few minutes before retrying
- Use an API key for higher quotas
- Batch requests with delays

### Notion Integration Issues

**Error: "Failed to create page"**
- Verify NOTION_API_KEY is set
- Check that the integration has access to the database
- Ensure database properties match expected schema

### Python Import Errors

**Error: "ModuleNotFoundError"**
```bash
cd ~/.claude/skills/ourdigital-seo-audit/scripts
pip install -r requirements.txt
```

---

## Support

For issues or feature requests:
1. Check this guide first
2. Review the [SKILL.md](SKILL.md) for technical details
3. Check [examples.md](examples.md) for more usage examples

---

*Last updated: December 2024*