seo/CATEGORY_MANAGEMENT_GUIDE.md

Category Management Guide

Overview

The SEO automation tool can now create and update WordPress categories based on AI propositions. This includes:

1. AI-powered category proposals - Analyze posts and suggest optimal categories
2. Automatic category creation - Create new categories in WordPress if they don't exist
3. Bulk category assignment - Assign multiple posts to categories at once
4. Confidence-based filtering - Only apply high-confidence recommendations

Workflow

1. Export posts
   ↓
2. Get AI category proposals
   ↓
3. Review proposals (optional)
   ↓
4. Apply to WordPress (with confidence filter)

Commands

1. Propose Categories (seo category_propose)

Analyze posts and generate category recommendations.

# Propose categories for latest export
./seo category_propose

# Propose for specific CSV
./seo category_propose output/all_posts_2026-02-16.csv

# Save to custom file
./seo category_propose -o output/my_proposals.csv

Output CSV columns:

• post_id - Post identifier
• title - Post title
• current_categories - Current categories
• proposed_category - AI-suggested category
• alternative_categories - Alternative suggestions
• category_reason - Explanation
• category_confidence - Confidence level (High/Medium/Low)

2. Apply Categories (seo category_apply)

Apply AI category proposals to WordPress.

# Apply with default settings (Medium confidence)
./seo category_apply -s mistergeek.net

# Apply only high-confidence recommendations
./seo category_apply -s mistergeek.net -c High

# Apply specific proposals file
./seo category_apply output/category_proposals_*.csv -s webscroll.fr

# Dry run (preview changes)
./seo category_apply -s mistergeek.net --dry-run

Options:

• -s, --site - WordPress site (required): mistergeek.net, webscroll.fr, hellogeek.net
• -c, --confidence - Minimum confidence: High, Medium, Low (default: Medium)
• --dry-run - Preview changes without applying

3. Create Category (seo category_create)

Manually create a new category.

# Create category
./seo category_create -s mistergeek.net "VPN Reviews"

# Create with description
./seo category_create -s webscroll.fr "Torrent Clients" -d "Guides about torrent clients"

# Dry run
./seo category_create -s hellogeek.net "Test Category" --dry-run

Usage Examples

Example 1: Complete Category Update Workflow

# Step 1: Export posts
./seo export

# Step 2: Get AI category proposals
./seo category_propose

# Step 3: Review proposals (open CSV in spreadsheet)
open output/category_proposals_*.csv

# Step 4: Apply high-confidence recommendations
./seo category_apply -s mistergeek.net -c High

# Step 5: Apply remaining Medium confidence (optional)
./seo category_apply -s mistergeek.net -c Medium

Example 2: Site-Specific Category Management

# For mistergeek.net (tech content)
./seo category_propose
./seo category_apply -s mistergeek.net -c Medium

# For webscroll.fr (torrent content)
./seo category_apply -s webscroll.fr -c Medium

# For hellogeek.net (misc content)
./seo category_apply -s hellogeek.net -c Low

Example 3: Manual Category Creation

# Create new categories before applying
./seo category_create -s mistergeek.net "AI Tools"
./seo category_create -s mistergeek.net "VPN Reviews"
./seo category_create -s webscroll.fr "Seedbox Guides"

# Then apply AI proposals
./seo category_apply -s mistergeek.net

Example 4: Safe Dry Run

# Preview what would happen
./seo category_propose
./seo category_apply -s mistergeek.net --dry-run

# Output shows:
# Would assign post 123 to "VPN"
# Would assign post 456 to "Software"
# etc.

# If satisfied, run without --dry-run
./seo category_apply -s mistergeek.net

How It Works

Category Creation Logic

1. Check if category exists (by slug)
2. If exists: Use existing category ID
3. If not: Create new category with AI-suggested name
4. Assign post to the category

Confidence Filtering

• High: Only apply very confident recommendations (>90% accuracy)
• Medium: Apply most recommendations (default, ~80% accuracy)
• Low: Apply all recommendations including uncertain ones

Safety Features

• Dry run mode: Preview changes before applying
• Confidence threshold: Filter out low-confidence suggestions
• Append mode: Adds to existing categories (doesn't replace)
• Error handling: Continues on errors, reports statistics

API Endpoints Used

The category manager uses WordPress REST API:

GET  /wp-json/wp/v2/categories     - List categories
POST /wp-json/wp/v2/categories     - Create category
GET  /wp-json/wp/v2/posts/{id}     - Get post details
POST /wp-json/wp/v2/posts/{id}     - Update post categories

Troubleshooting

"Site not found" error

# Use exact site name
./seo category_apply -s mistergeek.net  # ✓ Correct
./seo category_apply -s mistergeek      # ✗ Wrong

"No proposals found" error

# Run category_propose first
./seo category_propose
./seo category_apply -s mistergeek.net

Authentication errors

# Check .env file has correct credentials
# WORDPRESS_MISTERGEEK_USERNAME=...
# WORDPRESS_MISTERGEEK_PASSWORD=...

Categories not being created

# Check WordPress user has permission to create categories
# Requires 'manage_categories' capability

Best Practices

1. Start with High confidence: Test with -c High first
2. Review proposals: Open CSV and review before applying
3. Use dry run: Always test with --dry-run first
4. Backup first: Export posts before bulk changes
5. Monitor results: Check WordPress admin after applying

Programmatic Usage

from seo import SEOApp, CategoryAssignmentProcessor

app = SEOApp()

# Get proposals
proposals_file = app.category_propose()

# Apply with high confidence
stats = app.category_apply(
    proposals_csv=proposals_file,
    site_name='mistergeek.net',
    confidence='High',
    dry_run=False
)

print(f"Updated {stats['posts_updated']} posts")

Output Statistics

After applying categories, you'll see:

PROCESSING SUMMARY
Total proposals processed: 150
Categories created/found: 25
Posts updated: 142
Errors: 8

---

Version: 1.0.0
Last Updated: 2026-02-16
Related: See ENHANCED_ANALYSIS_GUIDE.md for AI analysis