igny8/refactor-plan/COMPLETE_USER_WORKFLOW_GUIDE.md

# IGNY8 Complete User Workflow Guide - From Signup to Publishing

**Version:** 1.0  
**Last Updated:** 2025-01-27  
**Status:** Comprehensive End-to-End Guide

---

## Table of Contents

1. [Getting Started - Signup & Onboarding](#1-getting-started---signup--onboarding)
2. [System Overview & Navigation](#2-system-overview--navigation)
3. [Workflow A: New IGNY8-Hosted Site (Complete Build)](#3-workflow-a-new-igny8-hosted-site-complete-build)
4. [Workflow B: Existing Site Management](#4-workflow-b-existing-site-management)
5. [Workflow C: WordPress Sync - New Site](#5-workflow-c-wordpress-sync---new-site)
6. [Workflow D: WordPress Sync - Existing Site](#6-workflow-d-wordpress-sync---existing-site)
7. [Module Deep Dives](#7-module-deep-dives)
8. [Advanced Features & Tips](#8-advanced-features--tips)

---

## 1. Getting Started - Signup & Onboarding

### 1.1 User Registration

**Path:** `/signup`

**Process:**
1. User visits signup page
2. Fills in registration form:
   - First Name (required)
   - Last Name (required)
   - Email (required, must be unique)
   - Password (required, must meet security requirements)
   - Username (optional, auto-generated from email if not provided)
   - Terms & Conditions acceptance (required)
3. System automatically:
   - Creates `User` account with role `owner`
   - Creates `Account` with auto-generated name (from user's name)
   - Links user to account as owner
   - Assigns default plan (usually free tier)
   - Generates JWT tokens (access + refresh)
   - Logs user in automatically

**Post-Registration:**
- User redirected to Dashboard (`/`)
- Account is ready to use immediately
- Initial credit balance assigned based on plan

### 1.2 First Login

**Path:** `/signin`

**Process:**
1. User enters email and password
2. System validates credentials
3. JWT tokens generated (15 min access, 7 day refresh)
4. User redirected to Dashboard

**Account Structure:**
```
Account (Your Organization)
  └── Sites (One or more websites)
      └── Sectors (Content categories/divisions)
          └── Keywords, Clusters, Ideas, Tasks, Content
```

### 1.3 Dashboard Overview

**Path:** `/` (Home Dashboard)

**What You See:**
- **Quick Stats:** Keywords, Clusters, Ideas, Tasks, Content counts
- **Workflow Steps:** Visual guide showing 7-step content creation process
- **Recent Activity:** Latest content, tasks, ideas
- **Quick Actions:** Links to key modules
- **Credit Balance:** Current credits and usage

**Key Navigation:**
- **Sidebar Menu:** Planner, Writer, Thinker, Linker, Optimizer, Sites, Settings
- **Top Bar:** User profile, notifications, credits display

---

## 2. System Overview & Navigation

### 2.1 Main Modules

| Module | Purpose | Key Features |
|--------|---------|--------------|
| **Planner** | Keyword research & clustering | Keywords import, auto-clustering, ideas generation |
| **Writer** | Content creation & management | Task creation, AI content generation, content editing |
| **Thinker** | AI configuration | Prompt management, author profiles, strategies |
| **Linker** | Internal linking | Automatic link suggestions, link management |
| **Optimizer** | Content optimization | SEO scoring, optimization suggestions |
| **Sites** | Site management & building | Site builder wizard, deployment, WordPress sync |

### 2.2 Access Control

**User Roles:**
- **Developer:** Full system access, bypasses all restrictions
- **Owner:** Full account access, can manage users
- **Admin:** Full site access, can manage site users
- **Editor:** Can create/edit content, limited settings access
- **Viewer:** Read-only access

**Scoping:**
- All data is scoped to Account → Site → Sector
- Users see only data for their assigned sites
- Admin/Developer can access all sites

### 2.3 Credit System

**How Credits Work:**
- Credits are the sole limiter (no per-plan feature restrictions)
- Operations consume credits:
  - Auto-clustering: 1 credit per 30 keywords (min 1)
  - Idea generation: 1 credit per idea
  - Content generation: 3 credits per content piece
  - Image generation: 1 credit per image
  - Re-optimization: 1 credit per rerun
- Credits deducted post-success
- Low balance warnings shown before operations
- Purchase credits on-demand via Billing

---

## 3. Workflow A: New IGNY8-Hosted Site (Complete Build)

### Overview
This workflow covers creating a brand new site from scratch, hosted on IGNY8's platform. This is the most comprehensive workflow.

### Step-by-Step Process

#### Phase 1: Planning & Keyword Research

**3.1.1 Discover Keywords**
- **Path:** `/planner/keyword-opportunities`
- **Action:** Browse keyword database, search by intent/volume/difficulty
- **Result:** Identify target keywords for your site

**3.1.2 Import Keywords**
- **Path:** `/planner/keywords`
- **Actions:**
  - **CSV Import:** Upload CSV with columns: `keyword`, `intent`, `volume`, `difficulty`
  - **Manual Entry:** Add keywords one by one
- **Validation:** System prevents duplicates (same keyword + site + sector)
- **Result:** Keywords stored with account/site/sector context

**3.1.3 Auto-Cluster Keywords**
- **Path:** `/planner/keywords`
- **Action:** Select keywords → Click "Auto-Cluster"
- **Process:**
  - System calls AI clustering service
  - Keywords grouped by semantic similarity
  - Clusters created with `context_type` (topic/attribute/service_line)
  - Credits deducted: 1 per 30 keywords (min 1)
- **Result:** Clusters visible in `/planner/clusters`

**3.1.4 Review & Refine Clusters**
- **Path:** `/planner/clusters`
- **Actions:**
  - Review cluster assignments
  - View cluster metrics (keyword count, volume, difficulty)
  - Merge or split clusters if needed
  - Assign cluster roles (hub/supporting/attribute) if desired
- **Result:** Refined cluster structure ready for site building

#### Phase 2: Site Builder Wizard

**3.2.1 Start Site Builder**
- **Path:** `/sites/builder` or `/sites/builder/workflow/:blueprintId`
- **Action:** Click "Create New Site" or "New Blueprint"
- **Result:** New `SiteBlueprint` created, `WorkflowState` initialized

**3.2.2 Step 1: Business Details**
- **Required Fields:**
  - Site Name
  - Site Description
  - Site Type: `blog` | `ecommerce` | `company`
  - Hosting Type: `igny8_sites` (for IGNY8 hosting)
- **Auto-Detection:** If WordPress integration exists, hosting type auto-detected
- **Action:** Save → Workflow state updated to `business_details: ready`
- **Result:** Blueprint saved, proceed to Step 2

**3.2.3 Step 2: Cluster Assignment**
- **Requirement:** Must attach ≥1 cluster before proceeding
- **Actions:**
  - View available clusters from Planner
  - Filter by intent, volume, context type
  - Select clusters to attach
  - Assign cluster roles:
    - **Hub:** Main pillar pages
    - **Supporting:** Supporting content pages
    - **Attribute:** Product/service attribute pages
  - Click "Attach Clusters"
- **Validation:** Backend enforces minimum cluster count
- **Result:** `SiteBlueprintCluster` records created, state → `clusters_ready`

**3.2.4 Step 3: Taxonomy Builder**
- **Requirement:** Must define taxonomies before sitemap generation
- **Taxonomy Types:**
  - Blog: Categories, Tags
  - Ecommerce: Product Categories, Product Tags, Product Attributes
  - Company: Service Categories, Service Groups
- **Actions:**
  - **Create Manually:** Add taxonomy items with name, slug, description
  - **Import from WordPress:** If WP integration exists, import existing taxonomies
  - **Link to Clusters:** Map each taxonomy to relevant clusters
  - **Auto-Suggestions:** System suggests taxonomies based on cluster metadata
- **Result:** `SiteBlueprintTaxonomy` records created, state → `taxonomies_ready`

**3.2.5 Step 4: AI Sitemap Review**
- **Requirement:** Clusters + Taxonomies must be ready
- **Process:**
  - System calls AI structure generation service
  - AI analyzes clusters + taxonomies
  - Generates page structure with:
    - Page titles
    - Slugs
    - Entity types (blog_post/product/service_page/taxonomy_page)
    - Cluster assignments
    - Taxonomy assignments
  - Credits deducted (varies by page count)
- **Actions:**
  - Review generated pages in grid view
  - Edit page titles, slugs, types
  - Reorder pages
  - Remove unwanted pages
  - Regenerate if needed (costs credits)
- **Result:** `PageBlueprint` records created, state → `sitemap_ready`

**3.2.6 Step 5: Coverage Validation**
- **Purpose:** Ensure all clusters have required page coverage
- **Checks:**
  - Each cluster has at least 1 hub page
  - Supporting pages present for major clusters
  - Attribute pages for ecommerce/service sites
  - Taxonomy pages for category/tag hubs
- **Actions:**
  - Review coverage cards
  - Fix gaps by returning to Step 4
  - Approve when all checks pass
- **Result:** State → `ideas_ready`

**3.2.7 Step 6: Ideas Hand-off**
- **Actions:**
  - Select pages to convert to Ideas
  - Optionally add secondary prompt/guidance
  - Click "Create Ideas"
- **Process:**
  - System calls `bulk_from_blueprint` API
  - Ideas created with metadata:
    - `cluster_id`
    - `taxonomy_id`
    - `site_entity_type`
    - `cluster_role`
  - Ideas appear in Planner Ideas queue
- **Result:** State → `ideas_in_progress`, Ideas ready in `/planner/ideas`

#### Phase 3: Content Creation (Writer)

**3.3.1 Review Ideas**
- **Path:** `/planner/ideas`
- **View:** Ideas list with entity types, cluster roles, taxonomy badges
- **Actions:** Filter by entity type, cluster, status

**3.3.2 Queue Ideas to Writer**
- **Action:** Select ideas → Click "Queue to Writer"
- **Process:**
  - Ideas converted to Writer Tasks
  - Tasks inherit metadata:
    - `entity_type`
    - `taxonomy_id`
    - `cluster_role`
    - Keywords from cluster
  - Tasks appear in `/writer/tasks`

**3.3.3 Generate Content**
- **Path:** `/writer/tasks`
- **Action:** Select tasks → Click "Generate Content"
- **Process:**
  - System queues AI content generation (Celery task)
  - AI receives:
    - Task details
    - Cluster context
    - Taxonomy context
    - Product attributes (if applicable)
    - Cluster role guidance
  - AI generates:
    - HTML content
    - Structured blocks (`json_blocks`) for products/services
    - Meta title, description
    - Primary/secondary keywords
  - Credits deducted: 3 per content piece
- **Result:** Content created, linked to task, appears in `/writer/content`

**3.3.4 Review & Edit Content**
- **Path:** `/writer/content` → Click content item
- **Editor Features:**
  - HTML editor with preview
  - Metadata sidebar showing:
    - Entity type
    - Cluster name & role
    - Taxonomy assignment
    - Validation status
  - Validation panel:
    - Checks for required metadata
    - Taxonomy assignment
    - Attribute completeness
    - Publish readiness
  - Publish button (disabled until validation passes)

**3.3.5 Generate Images**
- **Path:** `/writer/images`
- **Actions:**
  - System extracts image prompts from content
  - Generate featured images
  - Generate gallery images
  - Generate product variant images (ecommerce)
- **Credits:** 1 per image
- **Result:** Images linked to content

#### Phase 4: Optimization & Linking

**3.4.1 Internal Linking (Linker)**
- **Path:** `/linker/content`
- **Process:**
  - System analyzes content
  - Suggests internal links based on:
    - Cluster relationships (hub ↔ supporting)
    - Taxonomy matches
    - Entity type compatibility
    - Keyword relevance
  - Suggestions grouped by priority:
    - **High Priority:** Cluster matches
    - **Other Suggestions:** General relevance
- **Actions:**
  - Review link suggestions
  - Accept/reject suggestions
  - Insert links into content
- **Result:** Content enriched with internal links

**3.4.2 Content Optimization (Optimizer)**
- **Path:** `/optimizer/content`
- **Process:**
  - System analyzes content for:
    - SEO score
    - Readability
    - Engagement potential
    - Metadata completeness (Stage 3)
    - Cluster coverage
    - Taxonomy alignment
  - Scorecards displayed:
    - Overall score (0-100)
    - Metadata completeness
    - Cluster dimension coverage
- **Actions:**
  - Review optimization suggestions
  - Apply improvements
  - Re-optimize if needed (1 credit)
- **Result:** Optimized content ready for publishing

#### Phase 5: Validation & Publishing

**3.5.1 Content Validation**
- **Path:** `/sites/:id/posts/:postId` (Post Editor)
- **Validation Checks:**
  - Entity type assigned
  - Cluster mapping present
  - Taxonomy assignment complete
  - Required attributes filled (products/services)
  - Meta title/description present
- **Result:** Publish button enabled when all checks pass

**3.5.2 Site Progress Check**
- **Path:** `/sites/:id` (Site Dashboard)
- **Widget Shows:**
  - Overall site status
  - Cluster coverage (X/Y clusters complete)
  - Cluster details:
    - Hub pages count
    - Supporting pages count
    - Attribute pages count
    - Completion status
  - Validation flags
- **Actions:** Click incomplete clusters to view details

**3.5.3 Deployment Readiness**
- **Path:** `/sites/:id/deploy` (Deployment Panel)
- **Readiness Checks:**
  - Cluster coverage complete
  - Content validation passed
  - Taxonomy completeness
  - Sync status (if WordPress)
- **Actions:**
  - Review checklist
  - Fix any blocking issues
  - Click "Deploy" when ready

**3.5.4 Deploy to IGNY8**
- **Action:** Click "Deploy" button
- **Process:**
  - `SitesRendererAdapter` builds site definition
  - Includes:
    - Page definitions with content
    - Navigation structure (from clusters)
    - Taxonomy hierarchy
    - Internal links
    - Metadata (entity types, cluster roles)
  - Writes to `/data/app/sites-data/clients/{site_id}/v{version}`
  - Renderer serves site at `https://sites.igny8.com/{siteSlug}`
- **Result:** Site live on IGNY8 hosting

---

## 4. Workflow B: Existing Site Management

### Overview
Managing an existing site that's already created, adding content, updating pages, managing deployments.

### Key Workflows

#### 4.1 Adding New Content to Existing Site

**4.1.1 Create New Ideas**
- **Path:** `/planner/ideas`
- **Action:** Click "Create Idea" or import from keyword opportunities
- **Process:** Similar to Workflow A, but ideas linked to existing site

**4.1.2 Generate Content**
- Follow same process as Workflow A Phase 3
- Content automatically linked to existing site structure

#### 4.2 Managing Site Content

**4.2.1 View Site Content**
- **Path:** `/sites/:id/content`
- **View:** All content for the site, filtered by status, entity type, cluster

**4.2.2 Edit Existing Content**
- **Path:** `/sites/:id/posts/:postId/edit`
- **Actions:**
  - Edit HTML content
  - Update metadata
  - Change taxonomy assignments
  - Update cluster mappings
  - Re-validate before republishing

#### 4.3 Site Settings & Configuration

**4.3.1 General Settings**
- **Path:** `/sites/:id/settings?tab=general`
- **Settings:**
  - Site name, slug
  - Site type, hosting type
  - Active status

**4.3.2 SEO Settings**
- **Path:** `/sites/:id/settings?tab=seo`
- **Settings:**
  - Meta title, description, keywords
  - Open Graph tags
  - Schema.org markup

**4.3.3 Integrations**
- **Path:** `/sites/:id/settings?tab=integrations`
- **Actions:**
  - Configure WordPress integration
  - Test connection
  - View sync status
  - Manage sync settings

#### 4.4 Redeploying Site

**4.4.1 Check Deployment Readiness**
- **Path:** `/sites/:id/deploy`
- **Review:** Readiness checklist, fix any issues

**4.4.2 Deploy Updates**
- **Action:** Click "Deploy"
- **Process:** New version created, site updated with latest content

---

## 5. Workflow C: WordPress Sync - New Site

### Overview
Creating a new site that will sync with an existing WordPress installation. This workflow covers initial setup and first sync.

### Step-by-Step Process

#### Phase 1: WordPress Integration Setup

**5.1.1 Create Site**
- **Path:** `/sites/builder/workflow/:blueprintId`
- **Step 1:** Business Details
  - Site Type: Select appropriate type (blog/ecommerce/company)
  - Hosting Type: Select `wordpress`
  - Site Name, Description

**5.1.2 Configure WordPress Integration**
- **Path:** `/sites/:id/settings?tab=integrations`
- **Actions:**
  - Click "Connect WordPress"
  - Enter WordPress credentials:
    - WordPress Site URL
    - Application Password (or API key)
    - Username
  - Test connection
  - Save integration
- **Result:** `SiteIntegration` record created with WordPress platform

#### Phase 2: Initial Sync from WordPress

**5.2.1 Sync Taxonomies**
- **Path:** `/sites/:id/sync` (Sync Dashboard)
- **Process:**
  - System calls `ContentSyncService._sync_from_wordpress()`
  - Fetches WordPress categories, tags, product categories (WooCommerce)
  - Maps to IGNY8 `SiteBlueprintTaxonomy`
  - Stores `external_reference` (WP taxonomy ID)
  - Auto-creates missing clusters with `imported=True` flag
- **Result:** Taxonomies available in Site Builder

**5.2.2 Sync Products (Ecommerce)**
- **Process:**
  - Fetches WooCommerce products
  - Maps to IGNY8 content structure
  - Links to imported taxonomies
- **Result:** Products available as content ideas

**5.2.3 Sync Posts/Content**
- **Process:**
  - Fetches WordPress posts/pages
  - Maps to IGNY8 `Content` model
  - Links to clusters/taxonomies
  - Stores `external_reference` (WP post ID)
- **Result:** Existing content imported into IGNY8

#### Phase 3: Site Builder with Imported Data

**5.3.1 Complete Site Builder Wizard**
- **Step 2:** Cluster Assignment
  - Use imported clusters (from WordPress taxonomies)
  - Or attach Planner clusters
- **Step 3:** Taxonomy Builder
  - Review imported taxonomies
  - Add missing taxonomies if needed
  - Link to clusters
- **Step 4-6:** Continue as in Workflow A

#### Phase 4: Content Creation & Sync

**5.4.1 Create New Content in IGNY8**
- Follow Workflow A Phase 3 (Content Creation)
- Content created with metadata

**5.4.2 Sync to WordPress**
- **Path:** `/sites/:id/sync`
- **Action:** Click "Sync to WordPress"
- **Process:**
  - `ContentSyncService._sync_to_wordpress()` runs
  - Ensures taxonomies exist in WordPress (creates if missing)
  - Publishes content as WordPress posts/products
  - Updates `external_reference` after publishing
- **Result:** Content live on WordPress site

#### Phase 5: Ongoing Sync Management

**5.5.1 Monitor Sync Health**
- **Path:** `/sites/:id/sync`
- **Dashboard Shows:**
  - Overall sync status (healthy/warning/error)
  - Last sync time
  - Mismatch count
  - Integration status per platform
- **Actions:**
  - View sync logs
  - Retry failed syncs
  - Resolve mismatches

**5.5.2 Two-Way Sync**
- **From WordPress:** New posts/products in WP → Sync to IGNY8
- **To WordPress:** New content in IGNY8 → Sync to WP
- **Bidirectional:** Changes in either system sync to the other

---

## 6. Workflow D: WordPress Sync - Existing Site

### Overview
Adding WordPress sync to an existing IGNY8 site, or managing sync for an already-connected site.

### Key Workflows

#### 6.1 Connect Existing Site to WordPress

**6.1.1 Add Integration**
- **Path:** `/sites/:id/settings?tab=integrations`
- **Action:** Configure WordPress integration (same as 5.1.2)

**6.1.2 Initial Sync**
- **Path:** `/sites/:id/sync`
- **Action:** Click "Sync from WordPress"
- **Process:**
  - Imports WordPress taxonomies
  - Maps to existing IGNY8 taxonomies (by name/slug)
  - Updates `external_reference` fields
  - Imports missing content

#### 6.2 Managing Sync Mismatches

**6.2.1 View Mismatches**
- **Path:** `/sites/:id/sync`
- **Dashboard Shows:**
  - Taxonomies missing in WordPress
  - Taxonomies missing in IGNY8
  - Products/posts mismatches
- **Actions:**
  - Review mismatch details
  - Resolve by syncing missing items
  - Manual mapping if needed

**6.2.2 Resolve Mismatches**
- **Action:** Click "Retry Sync" or "Sync All"
- **Process:** System attempts to reconcile differences
- **Manual Override:** Edit taxonomy mappings if auto-resolution fails

#### 6.3 Publishing Updates

**6.3.1 Update Content in IGNY8**
- Edit content as normal (Workflow B)
- Changes saved locally

**6.3.2 Sync Updates to WordPress**
- **Path:** `/sites/:id/sync`
- **Action:** Click "Sync to WordPress"
- **Process:**
  - Updated content pushed to WordPress
  - Taxonomies updated/created as needed
  - External references maintained

---

## 7. Module Deep Dives

### 7.1 Planner Module

**Purpose:** Keyword research, clustering, idea generation

**Key Pages:**
- `/planner` - Dashboard with overview stats
- `/planner/keywords` - Keyword management
- `/planner/clusters` - Cluster management
- `/planner/ideas` - Content ideas queue
- `/planner/keyword-opportunities` - Keyword discovery

**Workflows:**
1. **Keyword Import:** CSV or manual entry
2. **Auto-Clustering:** AI groups keywords semantically
3. **Cluster Refinement:** Review, merge, split clusters
4. **Idea Generation:** Create content ideas from clusters
5. **Queue to Writer:** Convert ideas to tasks

### 7.2 Writer Module

**Purpose:** Content creation, editing, management

**Key Pages:**
- `/writer` - Dashboard
- `/writer/tasks` - Task queue
- `/writer/content` - Content library
- `/writer/images` - Image management
- `/writer/published` - Published content

**Workflows:**
1. **Task Creation:** From ideas or manual
2. **Content Generation:** AI creates full content
3. **Content Editing:** HTML editor with metadata
4. **Image Generation:** AI creates images
5. **Publishing:** Mark content ready for publish

### 7.3 Linker Module

**Purpose:** Internal linking automation

**Key Pages:**
- `/linker` - Dashboard
- `/linker/content` - Link suggestions

**Workflows:**
1. **Content Analysis:** System analyzes all content
2. **Link Suggestions:** AI suggests relevant internal links
3. **Link Insertion:** User reviews and accepts suggestions
4. **Link Management:** Edit/remove links as needed

### 7.4 Optimizer Module

**Purpose:** Content optimization & scoring

**Key Pages:**
- `/optimizer` - Dashboard
- `/optimizer/content` - Optimization analysis

**Workflows:**
1. **Content Analysis:** System scores content
2. **Optimization Suggestions:** AI provides improvement recommendations
3. **Apply Optimizations:** User implements suggestions
4. **Re-optimization:** Re-run optimization if needed

### 7.5 Sites Module

**Purpose:** Site management, building, deployment

**Key Pages:**
- `/sites` - Site list
- `/sites/:id` - Site dashboard
- `/sites/builder/workflow/:blueprintId` - Site builder wizard
- `/sites/:id/sync` - Sync dashboard
- `/sites/:id/deploy` - Deployment panel
- `/sites/:id/settings` - Site settings

**Workflows:**
1. **Site Creation:** Wizard-based site building
2. **Content Management:** View/edit site content
3. **Deployment:** Deploy to IGNY8 or WordPress
4. **Sync Management:** Manage WordPress sync
5. **Settings:** Configure site options

---

## 8. Advanced Features & Tips

### 8.1 Site Builder Wizard Tips

**Resume Capability:**
- Wizard state persists across sessions
- Return to `/sites/builder/workflow/:blueprintId` to resume
- System remembers last completed step

**Gating Logic:**
- Next buttons disabled until prerequisites met
- Hover over disabled buttons to see requirements
- Tooltips explain what's missing

**Helper Drawer:**
- Press `F1` or `?` for contextual help
- Each step has specific guidance
- Links to documentation

### 8.2 Metadata & Validation

**Why Metadata Matters:**
- Cluster assignments enable internal linking
- Taxonomy assignments enable proper categorization
- Entity types enable correct content structure
- Attributes enable rich product/service pages

**Validation Requirements:**
- Content cannot publish without required metadata
- Validation panel shows specific missing items
- Fix issues before publishing

### 8.3 Credit Management

**Best Practices:**
- Check credit balance before large operations
- Batch operations when possible (e.g., cluster multiple keyword sets)
- Monitor usage in Billing > Usage
- Set up low balance alerts

**Credit Optimization:**
- Review clusters before generating ideas (avoid duplicate ideas)
- Use linker suggestions efficiently (don't over-link)
- Re-optimize only when necessary

### 8.4 WordPress Sync Best Practices

**Initial Setup:**
- Test connection before first sync
- Review imported taxonomies carefully
- Map IGNY8 clusters to WP taxonomies properly

**Ongoing Management:**
- Monitor sync health regularly
- Resolve mismatches promptly
- Use manual sync for critical updates
- Keep external references in sync

### 8.5 Deployment Tips

**Pre-Deployment Checklist:**
- All clusters have required pages
- Content validation passes
- Taxonomies complete
- Sync status healthy (if WordPress)
- Test content on staging first

**Deployment Process:**
- Deployment creates new version
- Previous versions retained for rollback
- Deployment logs available for troubleshooting

### 8.6 Troubleshooting

**Common Issues:**

1. **Wizard Won't Progress:**
   - Check blocking issues in validation panel
   - Review tooltips on disabled buttons
   - Ensure prerequisites met (clusters, taxonomies)

2. **Content Won't Publish:**
   - Check validation panel for errors
   - Ensure required metadata assigned
   - Verify taxonomy/cluster mappings

3. **Sync Failures:**
   - Check WordPress connection
   - Review sync logs for errors
   - Verify API credentials
   - Check for rate limiting

4. **Credit Issues:**
   - Verify balance in Billing
   - Check operation costs
   - Purchase credits if needed

---

## Appendix: Quick Reference

### Key Routes

| Route | Purpose |
|------|---------|
| `/` | Dashboard |
| `/planner` | Planner dashboard |
| `/planner/keywords` | Keyword management |
| `/planner/clusters` | Cluster management |
| `/planner/ideas` | Ideas queue |
| `/writer` | Writer dashboard |
| `/writer/tasks` | Task queue |
| `/writer/content` | Content library |
| `/sites` | Site list |
| `/sites/builder/workflow/:id` | Site builder wizard |
| `/sites/:id` | Site dashboard |
| `/sites/:id/sync` | Sync dashboard |
| `/sites/:id/deploy` | Deployment panel |
| `/sites/:id/settings` | Site settings |

### Credit Costs

| Operation | Cost |
|-----------|------|
| Auto-cluster | 1 credit per 30 keywords (min 1) |
| Generate idea | 1 credit per idea |
| Generate content | 3 credits per content |
| Generate image | 1 credit per image |
| Re-optimize | 1 credit per rerun |

### Workflow Summary

**New IGNY8 Site:**
1. Keywords → Clusters → Site Builder → Ideas → Tasks → Content → Link → Optimize → Deploy

**WordPress Sync:**
1. Connect WP → Sync Taxonomies → Site Builder → Create Content → Sync to WP

**Existing Site:**
1. Add Ideas → Generate Content → Update → Redeploy

---

**End of Complete User Workflow Guide**

*This document covers all major workflows and features in IGNY8. For specific technical details, refer to architecture and implementation plans in the refactor-plan folder.*