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.

```bash
# 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.

```bash
# 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.

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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
```bash
# Use exact site name
./seo category_apply -s mistergeek.net  # ✓ Correct
./seo category_apply -s mistergeek      # ✗ Wrong
```

### "No proposals found" error
```bash
# Run category_propose first
./seo category_propose
./seo category_apply -s mistergeek.net
```

### Authentication errors
```bash
# Check .env file has correct credentials
# WORDPRESS_MISTERGEEK_USERNAME=...
# WORDPRESS_MISTERGEEK_PASSWORD=...
```

### Categories not being created
```bash
# 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

```python
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