igny8/docs/wordpress-integration-and-other/WP-PUBLISHING-SIMPLE-REFERENCE.md

# WordPress Publishing - Simplified Field Reference

**Last Updated**: 2025-12-01  
**Purpose**: Simple reference for IGNY8 → WordPress one-way publishing

---

## 🔄 Publishing Flow (One-Way Only)

```
IGNY8 Review.tsx
    ↓ User clicks "Publish to WordPress"
    ↓ POST /v1/publisher/publish/
Backend WordPressAdapter
    ↓ POST {site_url}/wp-json/igny8/v1/publish (with all content data)
WordPress Plugin
    ↓ wp_insert_post() + taxonomies + images + meta
    ↓ IMMEDIATE RETURN: {post_id, post_url, term_ids}
IGNY8 Backend
    ↓ Saves: external_id, external_url, status='published'
    ✅ DONE - No automatic sync, no bidirectional updates
```

**Publishing Timing**: Immediate (synchronous) - WordPress returns data right after post creation

---

## 📊 Published Fields Reference

| Field | IGNY8 → WordPress | WordPress Stores As | Notes |
|-------|-------------------|---------------------|-------|
| **CORE CONTENT** |
| title | `title` | `wp_posts.post_title` | Required |
| content_html | `content_html` | `wp_posts.post_content` | Required, sanitized |
| status | `status` | `wp_posts.post_status` | User-configurable: draft or publish (WP admin setting) |
| **SEO FIELDS** (Need Meta Boxes) |
| meta_title | `seo_title` OR `meta_title` | `_yoast_wpseo_title`, `_seopress_titles_title`, `_aioseo_title`, `_igny8_meta_title` | **⚠️ No UI in WP editor yet** |
| meta_description | `seo_description` OR `meta_description` | `_yoast_wpseo_metadesc`, `_seopress_titles_desc`, `_aioseo_description`, `_igny8_meta_description` | **⚠️ No UI in WP editor yet** |
| **KEYWORDS** (Need Meta Boxes) |
| primary_keyword | `primary_keyword` | `_igny8_primary_keyword` (post_meta) + added as tag | **⚠️ Should be custom field, not just tag** |
| secondary_keywords | `secondary_keywords` (JSON array) | `_igny8_secondary_keywords` (post_meta) + each added as tag | **⚠️ Should be custom field, not just tag** |
| **TAXONOMIES** |
| categories (from taxonomy_terms) | `categories` (array of names) | `wp_term_relationships` (category taxonomy) | ✅ Working |
| tags (from taxonomy_terms) | `tags` (array of names) | `wp_term_relationships` (post_tag taxonomy) | ✅ Working |
| **CUSTOM TAXONOMIES** (Currently Broken) |
| cluster | `cluster_id` | ~~`_igny8_cluster_id` (post_meta)~~ + `igny8_clusters` (taxonomy) | **⚠️ Currently saved as post_meta, should ONLY be taxonomy** |
| sector | `sector_id` | ~~`_igny8_sector_id` (post_meta)~~ + `igny8_sectors` (taxonomy) | **⚠️ Currently saved as post_meta, should ONLY be taxonomy** |
| **IMAGES** |
| featured_image | `featured_image_url` | `_thumbnail_id` (post_meta) → attachment | ✅ Working |
| gallery_images | `gallery_images` (array) | `_igny8_gallery_images`, `_product_image_gallery`, `_gallery_images` | **❌ BROKEN - Not saving** |
| **TRACKING FIELDS** (Show in Meta Box) |
| content_id | `content_id` | `_igny8_content_id` (post_meta) | ✅ Saved, **⚠️ Not visible in editor** |
| content_type | `content_type` | `_igny8_content_type` (post_meta) | ✅ Saved, **⚠️ Not visible in editor** |
| content_structure | `content_structure` | `_igny8_content_structure` (post_meta) | ✅ Saved, **⚠️ Not visible in editor** |
| **AUTO-GENERATED** |
| excerpt | Generated from content_html (first 150 chars) | `wp_posts.post_excerpt` | ✅ Working |
| **RETURN VALUES** (WordPress → IGNY8) |
| - | `post_id` | Returned immediately | Saved to `content.external_id` |
| - | `post_url` | Returned immediately | Saved to `content.external_url` |
| - | `category_term_ids` | Returned immediately | **⚠️ Need to return for mapping** |
| - | `tag_term_ids` | Returned immediately | **⚠️ Need to return for mapping** |
| - | `cluster_term_id` | Returned immediately | **⚠️ Need to return for mapping** |
| - | `sector_term_id` | Returned immediately | **⚠️ Need to return for mapping** |

---

## 🔧 Required Fixes

### 1. **Add Meta Boxes in WordPress Post Editor**
**Missing UI for these 4 fields:**
- `primary_keyword` - Custom field (text input) 
- `secondary_keywords` - Custom field (tag-style input)
- `meta_title` - SEO field (text input)
- `meta_description` - SEO field (textarea)

**Action**: Create new meta boxes in `class-post-meta-boxes.php`

---

### 2. **Fix Cluster/Sector as Pure Taxonomies**
**Current**: Saved as both post_meta AND taxonomy  
**Required**: Save ONLY as taxonomy, remove post_meta storage

**Code locations to fix:**
- `sync/igny8-to-wp.php` lines 141-175 (remove `_igny8_cluster_id`, `_igny8_sector_id` post_meta)
- Keep only `wp_set_post_terms()` for `igny8_clusters` and `igny8_sectors` taxonomies

---

### 3. **Fix Gallery Images Not Saving**
**Current**: Function `igny8_set_gallery_images()` doesn't exist, only `igny8_set_image_gallery()` exists  
**Issue**: Called at line 290 but function is named differently

**Action**: Fix function name or create alias

---

### 4. **Add Draft/Publish Setting in WP Admin**
**Location**: `admin/settings.php`  
**Add option**: "Default status for IGNY8 content" → Radio: Draft / Publish  
**Use in**: `igny8_create_wordpress_post_from_task()` to override `post_status`

---

### 5. **Show All IGNY8 Meta in Post Editor**
**Create meta box displaying:**
- Content ID: `_igny8_content_id`
- Content Type: `_igny8_content_type`
- Content Structure: `_igny8_content_structure`
- Cluster ID: `_igny8_cluster_id` (until removed)
- Sector ID: `_igny8_sector_id` (until removed)
- All other `_igny8_*` meta fields

**Action**: Add "IGNY8 Sync Data" meta box (read-only)

---

### 6. **Immediate Response with All IDs**
**Current return**:
```json
{
  "post_id": 123,
  "post_url": "https://...",
  "post_status": "draft"
}
```

**Required return**:
```json
{
  "post_id": 123,
  "post_url": "https://...",
  "post_status": "draft",
  "term_ids": {
    "categories": [45, 67],
    "tags": [12, 34, 56],
    "igny8_clusters": [89],
    "igny8_sectors": [101]
  }
}
```

**Action**: Modify `publish_content_to_wordpress()` to collect and return all term IDs

---

### 7. **Remove All Automatic Sync Code**
**Remove these files/functions:**
- `sync/hooks.php` - All `save_post`, `publish_post`, cron hooks
- `sync/post-sync.php` - All WordPress → IGNY8 sync functions
- `sync/taxonomy-sync.php` - Bidirectional taxonomy sync
- Cron jobs: `igny8_sync_post_statuses`, `igny8_sync_from_igny8`, etc.

**Keep only:**
- One-way publish: IGNY8 → WordPress via `/wp-json/igny8/v1/publish`
- Immediate response after post creation

---

### 8. **Remove Brief Meta Box**
**Current**: `class-post-meta-boxes.php` has "IGNY8 Planner Brief" meta box  
**Issue**: No `brief` data exists in IGNY8  
**Action**: Remove entire brief meta box and related AJAX handlers

---

### 9. **Clean Up task_id Usage**
**Current**: `_igny8_task_id` stored in post_meta  
**Question**: Is this Celery task_id or writer task_id?  
**Action**: If writer task, remove. If Celery, keep for tracking async operations.

---

## 🗂️ WordPress Database After Publishing

### Post Data
```
wp_posts:
  - post_title (from title)
  - post_content (from content_html)
  - post_excerpt (auto-generated)
  - post_status (draft or publish, from WP admin setting)
  - post_author (mapped)
```

### Post Meta
```
wp_postmeta:
  - _igny8_content_id (tracking)
  - _igny8_content_type (tracking)
  - _igny8_content_structure (tracking)
  - _igny8_primary_keyword (NEW - custom field)
  - _igny8_secondary_keywords (NEW - custom field, JSON)
  - _igny8_meta_title (SEO)
  - _igny8_meta_description (SEO)
  - _yoast_wpseo_title (SEO plugin compatibility)
  - _yoast_wpseo_metadesc (SEO plugin compatibility)
  - _thumbnail_id (featured image)
  - _igny8_gallery_images (gallery attachment IDs)
```

### Taxonomies
```
wp_term_relationships:
  - category (standard WP categories)
  - post_tag (standard WP tags)
  - igny8_clusters (custom taxonomy)
  - igny8_sectors (custom taxonomy)
```

### Attachments
```
wp_posts (type=attachment):
  - Featured image (downloaded from featured_image_url)
  - Gallery images (downloaded from gallery_images[].url)
```

---

## 🔍 Code Locations

### Backend (IGNY8)
- **Publisher**: `backend/igny8_core/business/publishing/services/adapters/wordpress_adapter.py`
- **Line 147-253**: Prepares payload with all fields

### WordPress Plugin
- **Endpoint**: `includes/class-igny8-rest-api.php` line 490
- **Post Creation**: `sync/igny8-to-wp.php` line 73
- **Taxonomies**: `includes/functions.php` line 465 (registration)
- **Meta Boxes**: `admin/class-post-meta-boxes.php`
- **Settings**: `admin/settings.php`

---

## ✅ What Works Now
- ✅ Post creation with title, content, excerpt
- ✅ Categories and tags from taxonomy_terms
- ✅ Featured image download and attachment
- ✅ SEO meta saved to plugin fields
- ✅ Cluster/sector taxonomies registered

## ❌ What's Broken
- ❌ Gallery images not saving (function name mismatch)
- ❌ No UI for primary_keyword, secondary_keywords, meta_title, meta_description
- ❌ Cluster/sector saved as both post_meta AND taxonomy (should be taxonomy only)
- ❌ No visibility of IGNY8 tracking fields in WP editor
- ❌ Brief meta box exists but has no data
- ❌ Automatic sync hooks causing unnecessary API calls

## ⚠️ What's Missing
- ⚠️ User can't choose draft vs publish in WP admin settings
- ⚠️ WordPress doesn't return term_ids for mapping
- ⚠️ Keywords stored as tags only, not as custom fields for editing