# Standard analysis (CLI + Markdown report)
npm run seo

# Save as baseline for future comparison
npm run seo -- --baseline

# Compare to previous baseline
npm run seo -- --compare 2026-01-15

# Export formats
npm run seo -- --output csv    # Multi-file CSV export
npm run seo -- --output html   # Standalone HTML report
npm run seo -- --output md     # Markdown only
npm run seo -- --output both   # CLI + Markdown (default)

scripts/
├── analyze-seo.ts              # Main entry point (v1.4)
└── seo/
    ├── index.ts                # Module exports
    ├── types.ts                # TypeScript interfaces
    ├── credentials.ts          # API credential management
    ├── oauth.ts                # Google OAuth flow
    ├── cache.ts                # Response caching (TTL by source)
    ├── rate-limiter.ts         # API rate limiting
    ├── clients/
    │   ├── gsc-simple.ts       # Google Search Console
    │   ├── ga4-simple.ts       # Google Analytics 4
    │   ├── backlinks.ts        # Ahrefs/SEMrush interface
    │   └── backlinks-simple.ts # Backlink client
    ├── insights/
    │   ├── engine.ts           # Insight detection
    │   ├── playbooks.ts        # Actionable recommendations
    │   └── playbook-templates.ts # Reusable templates
    └── outputs/
        ├── csv.ts              # CSV export
        ├── html.ts             # HTML report
        └── sheets.ts           # Google Sheets (deferred)

// Example: CTR Opportunity
// Requires: GSC data
// Logic: High impressions + low CTR = title/description needs work
if (impressions > 100 && ctr < 0.02) {
  insights.push({
    type: 'ctr_opportunity',
    severity: 'warning',
    affectedPages: [url],
    recommendation: 'Improve title and description to increase clicks'
  })
}

function detectMyIssue(
  crawlData: PageAnalysis[],
  gscData?: GSCData
): CorrelationInsight[] {
  const insights: CorrelationInsight[] = []

  // Your detection logic
  for (const page of crawlData) {
    if (/* condition */) {
      insights.push({
        type: 'my_issue_type',
        severity: 'warning', // or 'critical', 'opportunity'
        title: 'Brief issue title',
        description: 'What the issue is and why it matters',
        affectedPages: [page.url],
        dataSources: ['crawl', 'gsc'], // Which sources you used
        recommendation: 'How to fix it',
        estimatedImpact: 'medium', // 'high', 'medium', 'low'
      })
    }
  }

  return insights
}

export type InsightType =
  | 'existing_types'
  | 'my_issue_type'  // Add here

export function detectInsights(...) {
  // ...existing detectors...

  if (gscData) {
    insights.push(...detectMyIssue(crawlData, gscData))
  }
}

import { getRateLimiter, withRateLimitAndRetry } from './rate-limiter.js'

const limiter = getRateLimiter('gsc') // 'gsc' | 'ga4' | 'backlinks' | 'crux'

const data = await withRateLimitAndRetry(
  limiter,
  () => apiCall(),
  (attempt, error, delay) => {
    console.log(`Retry ${attempt}: ${error.message} (waiting ${delay}ms)`)
  }
)

import { readCache, writeCache, hasValidCache, clearDomainCache } from './cache.js'

// Check if valid cache exists
if (hasValidCache(domain, 'gsc')) {
  return readCache(domain, 'gsc')
}

// Write to cache
writeCache(domain, 'gsc', data)

// Clear cache for fresh data
clearDomainCache(domain)

interface ClientStatus {
  configured: boolean    // Credentials present
  hasData: boolean       // API returned data
  message: string        // Human-readable status
}

// Example status states:
// ⬚ Not configured — Missing credentials
// ⏳ Pending — Configured but no data yet
// ❌ Error — API call failed
// ✅ Active — Data available

============================================================
🔍 SEO ANALYSIS: concerts.morperhaus.org
============================================================

📊 SCORES
  Technical Foundation    ████████████████████░░░░  22/25 (88%)
  Content Quality         █████████████████████████  27/30 (90%)
  ...

  OVERALL SCORE           █████████████████████████  91/100 (A)

# Remove or comment out env vars temporarily
npm run seo