Refactor SEO automation into unified CLI application

Major refactoring to create a clean, integrated CLI application: ### New Features: - Unified CLI executable (./seo) with simple command structure - All commands accept optional CSV file arguments - Auto-detection of latest files when no arguments provided - Simplified output directory structure (output/ instead of output/reports/) - Cleaner export filename format (all_posts_YYYY-MM-DD.csv) ### Commands: - export: Export all posts from WordPress sites - analyze [csv]: Analyze posts with AI (optional CSV input) - recategorize [csv]: Recategorize posts with AI - seo_check: Check SEO quality - categories: Manage categories across sites - approve [files]: Review and approve recommendations - full_pipeline: Run complete workflow - analytics, gaps, opportunities, report, status ### Changes: - Moved all scripts to scripts/ directory - Created config.yaml for configuration - Updated all scripts to use output/ directory - Deprecated old seo-cli.py in favor of new ./seo - Added AGENTS.md and CHANGELOG.md documentation - Consolidated README.md with updated usage ### Technical: - Added PyYAML dependency - Removed hardcoded configuration values - All scripts now properly integrated - Better error handling and user feedback Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-02-16 14:24:44 +01:00
parent 3b51952336
commit 8c7cd24685
57 changed files with 16095 additions and 560 deletions
--- a/guides/ANALYZER_SUMMARY.md
+++ b/guides/ANALYZER_SUMMARY.md
@@ -0,0 +1,382 @@
+# Multi-Site SEO Analyzer - Implementation Summary
+
+## What Was Created
+
+### New Script: `scripts/multi_site_seo_analyzer.py`
+
+A Python script that automatically:
+
+1. **Connects to 3 WordPress sites** (mistergeek.net, webscroll.fr, hellogeek.net)
+2. **Fetches all published posts** using WordPress REST API
+3. **Analyzes titles** for:
+   - Length (optimal: 50-70 chars)
+   - Power words (best, complete, guide, etc.)
+   - Numbers (2025, top 10, etc.)
+   - Readability and special characters
+4. **Analyzes meta descriptions** for:
+   - Presence (missing = 0 score)
+   - Length (optimal: 120-160 chars)
+   - Call-to-action language
+5. **Scores each post** (0-100) based on SEO best practices
+6. **Generates AI recommendations** (optional) for top priority posts using Claude via OpenRouter
+7. **Exports results** to:
+   - CSV file with detailed analysis
+   - Markdown summary report
+
+---
+
+## Features
+
+### Automatic Title Analysis
+- Detects titles that are too short/long
+- Identifies missing power words
+- Checks for numbers/statistics
+- Flags problematic special characters
+- Scoring algorithm: 0-100
+
+### Automatic Meta Description Analysis
+- Detects missing meta descriptions (0 score)
+- Validates length (120-160 chars optimal)
+- Checks for call-to-action language
+- Scoring algorithm: 0-100
+
+### Combined SEO Scoring
+```
+Overall Score = (Title Score × 40%) + (Meta Description Score × 60%)
+```
+Meta descriptions weighted heavier because they directly impact CTR from search results.
+
+### AI-Powered Recommendations (Optional)
+- Uses Claude 3.5 Sonnet via OpenRouter
+- Generates specific, actionable recommendations
+- Cost-optimized: Only analyzes top priority posts (default 10, configurable)
+- Estimated cost: $0.10 per 10 posts analyzed
+
+### Multi-Site Support
+- Fetches from all 3 sites simultaneously
+- Per-site breakdown in reports
+- Identifies top 5 posts to optimize per site
+- Consolidates analysis across all sites
+
+---
+
+## Configuration Changes
+
+### Updated `scripts/config.py`
+Added multi-site configuration support:
+
+```python
+WORDPRESS_SITES = {
+    'mistergeek.net': {'url': '...', 'username': '...', 'password': '...'},
+    'webscroll.fr': {'url': '...', 'username': '...', 'password': '...'},
+    'hellogeek.net': {'url': '...', 'username': '...', 'password': '...'}
+}
+```
+
+New methods:
+- `get_site_config(site_name)` - Get config for specific site
+- `get_all_sites()` - Get all configured sites
+
+### Updated `.env.example`
+Added variables for each site:
+```
+WORDPRESS_MISTERGEEK_URL=...
+WORDPRESS_MISTERGEEK_USERNAME=...
+WORDPRESS_MISTERGEEK_PASSWORD=...
+
+WORDPRESS_WEBSCROLL_URL=...
+[etc for each site]
+```
+
+---
+
+## Documentation Created
+
+### 1. `guides/SEO_ANALYZER_GUIDE.md` (Comprehensive)
+- Complete setup instructions
+- Detailed usage examples
+- How to interpret scores
+- Understanding title and meta analysis
+- Action plan for implementation
+- Cost estimation
+- Troubleshooting guide
+- Advanced usage examples
+- FAQ section
+
+### 2. `guides/QUICKSTART_ANALYZER.md` (Fast Reference)
+- 30-second setup
+- One-liners for different scenarios
+- Common commands
+- Quick troubleshooting
+- Cost comparison table
+
+### 3. `guides/ANALYZER_SUMMARY.md` (This document)
+- Overview of what was created
+- Feature summary
+- Usage instructions
+- Output explanation
+
+---
+
+## Usage
+
+### Basic Command
+
+```bash
+python scripts/multi_site_seo_analyzer.py
+```
+
+**What it does:**
+- Fetches posts from all 3 sites
+- Analyzes titles and meta descriptions
+- Generates AI recommendations for top 10 worst-scoring posts
+- Exports CSV and Markdown report
+
+### Command Options
+
+```bash
+# Skip AI recommendations (free, faster)
+python scripts/multi_site_seo_analyzer.py --no-ai
+
+# AI recommendations for top 20 posts
+python scripts/multi_site_seo_analyzer.py --top-n 20
+
+# Custom output file
+python scripts/multi_site_seo_analyzer.py --output my_report.csv
+```
+
+---
+
+## Output Files
+
+### Location: `output/reports/`
+
+### 1. CSV File: `seo_analysis_YYYYMMDD_HHMMSS.csv`
+
+Contains one row per post with columns:
+- `site` - Website name
+- `post_id` - WordPress post ID
+- `title` - Post title
+- `slug` - Post slug
+- `url` - Full URL
+- `meta_description` - Current meta description
+- `title_score` - Title SEO score (0-100)
+- `title_issues` - Title problems identified
+- `title_recommendations` - How to improve title
+- `meta_score` - Meta description SEO score (0-100)
+- `meta_issues` - Meta description problems
+- `meta_recommendations` - How to improve meta
+- `overall_score` - Combined score (40% title + 60% meta)
+- `ai_recommendations` - Claude-generated specific recommendations
+
+**Use for:**
+- Importing to Excel/Google Sheets
+- Filtering and sorting
+- Bulk editing preparations
+- Tracking changes over time
+
+### 2. Markdown Report: `seo_analysis_YYYYMMDD_HHMMSS_summary.md`
+
+Contains:
+- Summary statistics (total posts, average scores, cost)
+- Priority issues breakdown (missing meta, weak titles, etc.)
+- Per-site analysis and top 5 posts to optimize per site
+- Human-readable explanations
+
+**Use for:**
+- Quick overview
+- Sharing with team
+- Understanding key metrics
+- Decision-making
+
+---
+
+## Score Interpretation
+
+### Score Ranges
+
+| Range | Interpretation | Action |
+|-------|-----------------|--------|
+| 0-25 | Critical | Fix immediately - major SEO issues |
+| 25-50 | Poor | Optimize soon - multiple issues |
+| 50-75 | Fair | Improve when convenient - some issues |
+| 75-90 | Good | Minor tweaks only - mostly optimized |
+| 90-100 | Excellent | No changes needed - well optimized |
+
+### Example Scores
+
+**Poor Post (Score: 12)**
+```
+Title: "VPN"
+- Issues: Too short (3 chars), no power words, no numbers
+- Title Score: 5/100
+
+Meta Description: [MISSING]
+- Issues: Missing entirely
+- Meta Score: 0/100
+
+Overall: 12/100 (Critical - needs work)
+```
+
+**Good Post (Score: 88)**
+```
+Title: "Best VPN Services 2025: Complete Review"
+- Issues: None
+- Title Score: 95/100
+
+Meta Description: "Compare 50+ VPN services with speed tests, security reviews, and pricing. Find the best VPN for your needs."
+- Issues: None
+- Meta Score: 85/100
+
+Overall: 88/100 (Good - minimal changes)
+```
+
+---
+
+## Cost Breakdown
+
+### Using AI Recommendations
+
+**Pricing:** Claude 3.5 Sonnet via OpenRouter = $3/$15 per 1M input/output tokens
+
+**Per run examples:**
+
+| Posts Analyzed | Tokens | Cost |
+|---|---|---|
+| 10 posts | ~30k input, 5k output | ~$0.10 |
+| 20 posts | ~60k input, 10k output | ~$0.20 |
+| 50 posts | ~150k input, 25k output | ~$0.50 |
+| 100 posts | ~300k input, 50k output | ~$1.00 |
+
+### Monthly Budget
+
+- **Weekly no-AI:** $0/month
+- **Weekly with AI (top 10):** ~$0.40/month
+- **Monthly with AI (top 50):** ~$0.50/month
+- **Fits easily in €50 budget ✓**
+
+---
+
+## Prerequisites
+
+Before running, ensure:
+
+1. **WordPress credentials** for all 3 sites (API/app passwords)
+2. **OpenRouter API key** (for AI recommendations)
+3. **REST API enabled** on all 3 WordPress sites
+4. **Python 3.8+** installed
+5. **Dependencies installed:** `pip install -r requirements.txt`
+
+---
+
+## Workflow Example
+
+### Week 1: Initial Analysis
+
+```bash
+# Run analyzer with AI for top 10
+python scripts/multi_site_seo_analyzer.py --top-n 10
+
+# Review results
+open output/reports/seo_analysis_*_summary.md
+
+# See top 10 posts to optimize on each site
+# Note: AI cost ~$0.10
+```
+
+### Week 1-4: Implementation
+
+For each of top 10 posts per site:
+
+1. Open WordPress editor
+2. Review AI recommendation
+3. Update title (if needed)
+4. Update meta description (if needed)
+5. Publish changes
+
+Average time: 2-3 minutes per post = 30-45 minutes total
+
+### Week 5: Re-analysis
+
+```bash
+# Run analyzer again to track progress
+python scripts/multi_site_seo_analyzer.py --no-ai
+
+# Compare with Week 1 results
+# Identify next batch of 10 posts to optimize
+```
+
+Repeat as needed.
+
+---
+
+## Expected Improvements
+
+### Short-term (Month 1)
+- **Reduced posts with score < 50:** 30-50% fewer critical issues
+- **Meta descriptions added:** Most missing descriptions now present
+- **Title improvements:** Clearer, more compelling titles
+
+### Medium-term (Month 3)
+- **CTR improvement:** 10-20% increase in click-through rate from search results
+- **Keyword rankings:** Some keywords move up 1-3 positions
+- **Organic traffic:** 5-10% increase as improved titles/descriptions increase clicks
+
+### Long-term (Months 3-6)
+- **Compound effect:** Better CTR signals boost rankings
+- **Authority:** Focused content with optimized SEO
+- **Traffic:** 20-30% total increase from all factors
+
+---
+
+## Next Steps
+
+1. **Update .env** with your 3 site credentials
+2. **Run analyzer:** `python scripts/multi_site_seo_analyzer.py`
+3. **Review report:** `open output/reports/seo_analysis_*_summary.md`
+4. **Implement:** Start with top 5 posts per site
+5. **Re-run:** Monthly to track progress and identify next batch
+
+---
+
+## Troubleshooting
+
+### Connection Issues
+- Verify site URLs (https, www)
+- Check WordPress credentials
+- Test: `curl https://yoursite.com/wp-json/wp/v2/posts?per_page=1`
+
+### No Posts Found
+- Check credentials have read permissions
+- Verify posts are published (not draft)
+- Try disabling SSL verification (last resort)
+
+### AI Errors
+- Verify OPENROUTER_API_KEY is set
+- Check key has API credits
+- Use --no-ai to skip AI (still analyzes)
+
+See `guides/SEO_ANALYZER_GUIDE.md` for detailed troubleshooting.
+
+---
+
+## Files Summary
+
+| File | Purpose |
+|------|---------|
+| `scripts/multi_site_seo_analyzer.py` | Main analyzer script |
+| `scripts/config.py` | Updated with multi-site config |
+| `.env` | Your site credentials (not in repo) |
+| `.env.example` | Example config (with all fields) |
+| `guides/SEO_ANALYZER_GUIDE.md` | Comprehensive guide |
+| `guides/QUICKSTART_ANALYZER.md` | Quick reference |
+| `guides/ANALYZER_SUMMARY.md` | This file |
+| `output/reports/` | Where results are saved |
+
+---
+
+## Questions?
+
+See the full guide: `guides/SEO_ANALYZER_GUIDE.md`
+
+Ready to analyze? Run: `python scripts/multi_site_seo_analyzer.py`