From a0de0cf6b1b653039a4ecc51f05c7ba594a0ffee Mon Sep 17 00:00:00 2001 From: alorig <220087330+alorig@users.noreply.github.com> Date: Thu, 20 Nov 2025 04:29:48 +0500 Subject: [PATCH] Create COMPLETE_USER_WORKFLOW_GUIDE.md --- refactor-plan/COMPLETE_USER_WORKFLOW_GUIDE.md | 879 ++++++++++++++++++ 1 file changed, 879 insertions(+) create mode 100644 refactor-plan/COMPLETE_USER_WORKFLOW_GUIDE.md diff --git a/refactor-plan/COMPLETE_USER_WORKFLOW_GUIDE.md b/refactor-plan/COMPLETE_USER_WORKFLOW_GUIDE.md new file mode 100644 index 00000000..2c0d4e01 --- /dev/null +++ b/refactor-plan/COMPLETE_USER_WORKFLOW_GUIDE.md @@ -0,0 +1,879 @@ +# 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.* +