pre-launch-final mods-docs

2025-12-11 07:20:21 +00:00
parent 20fdd3b295
commit a736bc3d34
8 changed files with 5464 additions and 0 deletions
--- a/Pre-Launch-Pending.md
+++ b/Pre-Launch-Pending.md
@@ -0,0 +1,556 @@
+---
+
+# **APP LAUNCH PLAN: ITEMS 1 to 3**
+
+# **Item 1: Status Modules for AI Planner and Writer**
+
+### **Objective**
+
+Ensure Planner and Writer status tracking is consistent, accurate, and fully functional across backend and frontend.
+
+### **Work Scope**
+
+#### **A. Backend**
+
+* Standardize status states for:
+
+  * Planner tasks
+  * Writer tasks
+  * Queue processing
+  * AI function progress
+* Create unified status enums and error codes.
+* Ensure all AI jobs push accurate progress updates during:
+
+  * Keyword extraction
+  * Clustering
+  * Idea generation
+  * Content generation
+  * Image generation
+* Ensure all status updates propagate through WebSockets or async polling.
+* Log transitions for debugging.
+
+#### **B. Frontend**
+
+* Display accurate status for:
+
+  * Each task
+  * Each queue item
+  * Each stage of execution
+* Ensure Planner and Writer modals show:
+
+  * Correct live progress
+  * Correct messaging
+  * Correct completion and failure notices
+* Refactor old status code to match backend changes.
+
+#### **C. QA**
+
+* Test all workflows manually on:
+
+  * Keywords
+  * Clusters
+  * Ideas
+  * Content
+  * Automation wizard
+* Test edge cases:
+
+  * Stuck tasks
+  * Failed tasks
+  * Incorrect counts
+  * Race conditions
+* Validate real-time UI updates.
+
+---
+
+# **Item 2: Credits, Billing, Pricing Logic, and Usage Limits**
+
+### **Objective**
+
+Define credit costs per AI function and define plan limits for counts and usage.
+
+### **Work Scope**
+
+#### **A. Define Credit Cost per AI Function**
+
+For each AI operation, decide exact credit cost:
+
+* Keyword extraction
+* Clustering
+* SAG mapping
+* Idea generation
+* Content generation (per word length)
+* Image generation
+* Any additional operations
+
+This defines package pricing and resource consumption.
+
+#### **B. Define Plan-Based Usage Limits**
+
+Define limits that each plan can have:
+
+* Maximum keywords saved
+* Maximum clusters
+* Maximum ideas
+* Maximum content pieces
+* Maximum images
+* Max tasks queued at a time
+* Limits for daily or monthly usage caps
+* Per-account or per-user limits
+
+These limits sit **on top of credit allocation**, or credit alone may cap output. Decision required.
+
+#### **C. Backend Implementation**
+
+* Add limit checks in API for create actions.
+* Add counters for monthly/daily usage.
+* Add logic to block or warn when limits reached.
+* Integrate credit deduction rules per function.
+
+#### **D. Frontend Implementation**
+
+* Show plan limits clearly.
+* Show remaining credits and remaining records.
+* Show warnings when nearing limits.
+* Unify progress counters in dashboards.
+
+#### **E. Pricing Plan Optimization**
+
+* After defining credit values and limits:
+
+  * Create Starter, Growth, Pro, and Enterprise plans.
+  * Set competitive credit allocations.
+  * Set record-based limits and overage policies.
+  * Ensure predictable cost for users and profitability for platform.
+
+---
+
+# **Item 3: Prompt Improvement and Model Optimization**
+
+### **Objective**
+
+Fully redesign AI prompts for extreme accuracy, consistent output, faster processing, and correct word count. Improve content quality, clustering quality, and image prompts.
+
+### **Work Scope**
+
+#### **A. SAG Clustering Prompt**
+
+Handled separately later but included as part of item 3.
+
+Goal:
+
+* Convert IGNY8 semantic architecture into an AI-usable compact prompt.
+* Include examples.
+* Produce consistent clustering across all modules.
+
+(This will be done in next phase.)
+
+---
+
+#### **B. Idea Generation Prompt (Improve Existing Prompt)**
+
+Improvements needed:
+
+* Increase semantic alignment with cluster intent.
+* Produce stronger, more realistic editorial ideas.
+* Improve JSON formatting reliability.
+* Better keyword mapping.
+* Ensure structure variation and non-repetitive logic.
+* Produce cluster hub + proper supporting ideas with strict editorial rules.
+
+Output:
+A refined prompt for idea generation with optimized structure, clarity, and output consistency.
+
+---
+
+#### **C. Content Generation Prompt (Improve Existing Prompt)**
+
+Improvements needed:
+
+1. **Precise word-count adaptation**
+
+   * 500, 1000, 1500 words
+   * Automatic proportional scaling
+2. **Better editorial quality**
+
+   * Richer depth
+   * More variation in style and examples
+   * No generic flavor
+3. **Smarter structure control**
+
+   * Paragraphs first
+   * Then list/table
+   * Never start with list
+   * Proper subsection placement
+4. **Strict SEO rules**
+
+   * Primary keyword in title, intro, and two H2s
+   * Natural secondary keywords
+5. **HTML consistency**
+
+   * Clean tags
+   * No broken JSON strings
+6. **Better image prompts**
+
+   * Clear
+   * Topic relevant
+   * Frontend-friendly
+
+Output:
+A set of optimized content prompts for 500, 1000, 1500 versions.
+
+---
+
+# **Summary of Deliverables for Items 1–3**
+
+### **Item 1 Deliverables**
+
+* Unified backend status engine
+* Clean frontend progress modals
+* Error-proof workflow states
+* Automation wizard corrections
+
+### **Item 2 Deliverables**
+
+* Full credit cost table per function
+* Pricing plan limits and counters
+* Backend logic for limit enforcement
+* Frontend display of usage and credit consumption
+
+### **Item 3 Deliverables**
+
+* Rewritten idea-generation prompt
+* Rewritten content-generation prompt (3 lengths)
+* Improved image prompt format
+* Separate SAG clustering prompt (later)
+
+---
+
+# 4. Page Flow and Workflow UX Improvements
+
+Improve the overall navigation, page structure, workflow clarity, and helper systems across all main user-facing areas.
+
+## 4.1 Improve Page Flows Across Main Menu Groups
+
+### Groups to cover
+
+* Setup
+* Workflow
+* Account
+* Settings
+
+### Required Enhancements
+
+| Area                 | Improvement                                                                          |
+| -------------------- | ------------------------------------------------------------------------------------ |
+| Navigation hierarchy | Standardize all menu groups and subpages with consistent UX patterns.                |
+| Linear workflows     | Ensure planner and writer flows follow a clear step-by-step progression.             |
+| Breadcrumbs          | Add contextual breadcrumbs for deeper sections.                                      |
+| Page orientation     | Each page requires a header with title, short description, and quick action buttons. |
+| Cross-navigation     | Add "Back to previous step", "Continue", and "View progress" controls.               |
+
+---
+
+## 4.2 Workflow UX Improvements
+
+### Planner and Writer workflows need:
+
+* Step banners
+* Clear state indicators
+* Autosave indicators
+* Better use of helper components
+
+### Helper Elements Required
+
+| Component            | Purpose                                                            |
+| -------------------- | ------------------------------------------------------------------ |
+| Helper notifications | Display small contextual guidance when entering a new screen.      |
+| Tooltips             | For icons, complex actions, and configuration options.             |
+| Inline guidance      | Small text under fields explaining purpose or required formatting. |
+| Step banners         | Persistent “Step X of Y” headers guiding the user.                 |
+
+---
+
+## 4.3 Notification System
+
+### Requirements
+
+* Event-driven notifications for task progress, completion, failure, errors, and actions required.
+* Unified notification dropdown accessible via bell icon in the header.
+
+### Notification Types
+
+| Type            | Examples                                                |
+| --------------- | ------------------------------------------------------- |
+| Progress        | Planner or writer job started, queued, processing.      |
+| Success         | Content generated, workflow completed, export success.  |
+| Failure         | API errors, workflow failure, validation issues.        |
+| Action required | Missing settings, incomplete fields, failed publishing. |
+
+### Dropdown Features
+
+* Chronological list
+* Read/unread states
+* Links to relevant pages or tasks
+* Icon-based status indicators (info, success, warning, danger)
+
+---
+
+## 4.4 Global and Page-level Metrics
+
+### Bottom Metrics Panel (per workflow page)
+
+* Move detailed metrics to the bottom of Planner and Writer workflows.
+* Collapsible panel.
+* Shows counts, progress, keyword metrics, SEO density, etc.
+
+### Header Metrics (global)
+
+Improved header-level metrics visible everywhere:
+
+* Tasks in progress
+* Completed tasks
+* Failed tasks
+* Credits remaining
+* Usage summary
+* Notification count
+
+---
+
+## 4.5 Tenant-level Settings Reorganization
+
+### Problem
+
+Settings are scattered and inconsistent.
+
+### Solution
+
+Create a centralized **Tenant Settings Hub** (superuser excluded).
+
+### New Structure
+
+| Category            | Subpages                                              |
+| ------------------- | ----------------------------------------------------- |
+| General             | Basic account settings, display options.              |
+| Publishing          | WordPress connection, publishing defaults, SEO rules. |
+| Pagination          | Control pagination for listings, workflows, results.  |
+| Branding            | Logo, colors, styling preferences.                    |
+| Workflow Defaults   | Planner, writer, auto settings, task behaviors.       |
+| Integrations        | API keys, external platforms, plugins.                |
+| Notifications       | Type preferences, email alerts, push alerts.          |
+| Account and Billing | Plan, credits, invoices, team access.                 |
+
+---
+
+# 5. WordPress Content Template Improvements and Redesign
+
+## 5.1 Image Reuse Logic
+
+Automatically reuse available images based on count.
+
+| Available Images | Behavior                                                           |
+| ---------------- | ------------------------------------------------------------------ |
+| 1                | Reuse multiple times across intro, middle, and final sections.     |
+| 2                | Alternate image placement across sections.                         |
+| 3                | Use each twice for balanced distribution.                          |
+| More than 3      | Use each once until exhausted, then reuse based on article length. |
+
+---
+
+## 5.2 Placement Rules
+
+Images must appear at predictable, meaningful points.
+
+| Placement                | Purpose                             |
+| ------------------------ | ----------------------------------- |
+| After introduction       | Establish visual tone.              |
+| Before major H2 sections | Break reading monotony.             |
+| Mid-article              | Reset attention, add visual pacing. |
+| Before conclusion        | Support final argument or CTA.      |
+
+---
+
+## 5.3 Template Versions by Article Length
+
+### A. 500-word Template
+
+* Intro (1 paragraph)
+* H2 Section 1 (1 paragraph)
+* H2 Section 2 (1–2 paragraphs)
+* Conclusion (1 paragraph)
+* Images: 2 to 3 placements
+
+### B. 1000-word Template
+
+* Intro (2 paragraphs)
+* H2 Section 1 (2 paragraphs)
+* H2 Section 2 (2 paragraphs)
+* H2 Section 3 (2 paragraphs)
+* Conclusion (2 paragraphs)
+* Images: 3 to 5 placements
+
+### C. 1500-word Template
+
+* Intro (2–3 paragraphs)
+* H2 Section 1 (3 paragraphs)
+* H2 Section 2 (3 paragraphs)
+* H2 Section 3 (3 paragraphs)
+* Optional additional H2 or H3 subsections
+* Conclusion with CTA
+* Images: 4 to 7 placements
+
+---
+
+## 5.4 Cluster Hub Landing Page Template
+
+This single template is reused for:
+
+* Cluster hubs
+* Category pages
+* Tag archive pages
+
+### Core Structure
+
+| Section                | Description                                       |
+| ---------------------- | ------------------------------------------------- |
+| Hero section           | Term title, description, and optional hero image. |
+| Featured visual        | Illustration or banner for cluster identity.      |
+| Overview block         | Short intro text about the topic group.           |
+| Subcluster cards       | If hierarchical categories exist.                 |
+| Latest articles list   | Auto-populated.                                   |
+| Popular articles block | Based on views or tagging.                        |
+| CTA block              | Newsletter or lead magnet.                        |
+| Footer navigation      | Internal linking anchors.                         |
+
+### Conditional Variants
+
+| Term Type   | Variation                              |
+| ----------- | -------------------------------------- |
+| Category    | Shows category tree and subcategories. |
+| Tag         | Shows related tag cloud.               |
+| Cluster Hub | Includes deeper cluster overview map.  |
+
+---
+
+# 6. Frontend Marketing Site
+
+## 6.1 Update Marketing Site Content
+
+### Pages to Update
+
+| Page           | Required Work                                                            |
+| -------------- | ------------------------------------------------------------------------ |
+| Home           | Rewrite hero, features, workflows, CTAs, add visuals.                    |
+| Features       | List key modules: planner, writer, metrics, notifications, settings hub. |
+| Product pages  | Dedicated pages for each workflow module.                                |
+| Use-case pages | For agencies, e-commerce, content teams.                                 |
+| About          | Mission, philosophy, architecture reasoning.                             |
+| Contact        | Updated contact and support flow.                                        |
+
+---
+
+## 6.2 Update Pricing Page and Plans
+
+### Required Upgrades
+
+| Area                | Details                                                 |
+| ------------------- | ------------------------------------------------------- |
+| Plan definitions    | Clearly define Free, Starter, Growth, Enterprise tiers. |
+| Usage-based pricing | Explain credit system and workflow limits.              |
+| Add-ons             | Extra users, domains, integrations.                     |
+| Comparison tables   | Feature-by-feature breakdown.                           |
+| Billing cycles      | Monthly and annual toggles.                             |
+| Global currencies   | USD baseline, PK optional.                              |
+| FAQs under pricing  | Immediate resolution for common objections.             |
+
+---
+
+# 7. Documentation
+
+## 7.1 In-app Documentation
+
+### Areas to update
+
+| Section            | Required Documentation                            |
+| ------------------ | ------------------------------------------------- |
+| Planner workflow   | Step-by-step guides, tooltips, screenshots.       |
+| Writer workflow    | Drafting, editing, optimization, publishing.      |
+| Tenant settings    | Publishing, pagination, defaults, integrations.   |
+| Metrics            | Definitions, data refresh rules, interpretation.  |
+| Notifications      | Event types, triggers, statuses, troubleshooting. |
+| Account management | Team roles, permissions, billing, usage.          |
+
+### Placement
+
+* Floating help icon
+* Embedded guides per workflow
+* Onboarding tutorials
+
+---
+
+## 7.2 Marketing Site Documentation
+
+### Includes
+
+| Area                | Content Needed                         |
+| ------------------- | -------------------------------------- |
+| API documentation   | Endpoints, auth, requests, responses.  |
+| Integration guides  | WordPress setup, API keys, automation. |
+| Workflow guides     | Planner-to-writer SEO flow.            |
+| AI usage            | Credit consumption and behavior specs. |
+| Notification events | JSON payloads, event types, callbacks. |
+| Data privacy        | Storage, security, backups.            |
+
+---
+
+## 7.3 FAQ Updates
+
+### Categories
+
+* General
+* Pricing
+* Content generation
+* Integrations
+* Settings
+* Technical troubleshooting
+* Data handling
+
+### Structure
+
+* Accordion layout
+* Search bar
+* Support CTA
+
+
+---
+Known bugs and issues
+1. AI functions
+Manual run on pages
+For pages: Keywords, Cluster, and Tasks, for clustering, idea generation, content generation:
+
+The texts shown in manual AI function run for Planner and Writer progress modals:
+
+Text is not accurate.
+Needs to be fixed for all different modals based on the specific function running.
+Process to fix:
+
+Ask AI agent to build a table of current texts.
+
+Then optimize these texts with:
+
+Better wording.
+Dynamic variables.
+Automation (Manual Run for automation wizard on automation page)
+Wrong queue items.
+
+Missing queue items.
+
+Progress bar does not progress properly.
+
+Total in queue and processed counts are buggy for many stages.
+
+Stage cards:
+
+Realtime metrics not optimized.
+Should be more robust and more user friendly.
+
+user sometimes log out atumatically , 
--- a/docs/PRE-LAUNCH/ITEM-1-STATUS-MODULES.md
+++ b/docs/PRE-LAUNCH/ITEM-1-STATUS-MODULES.md
@@ -0,0 +1,547 @@
+# Item 1: Status Modules for AI Planner and Writer
+
+**Priority:** Critical  
+**Target:** Production Launch  
+**Last Updated:** December 11, 2025
+
+---
+
+## Overview
+
+Standardize and fix status tracking across Planner and Writer modules to ensure consistent, accurate, and real-time progress updates for all AI operations. This includes backend status management, frontend progress displays, WebSocket/polling systems, and error handling.
+
+---
+
+## Current Implementation Analysis
+
+### Backend Status System
+
+#### Status Fields in Models
+
+**Location:** `backend/igny8_core/business/planning/models.py` and `backend/igny8_core/business/content/models.py`
+
+| Model | Current Status Choices | Issues |
+|-------|----------------------|---------|
+| **Keywords** | `new`, `mapped` | Limited states, no processing states |
+| **Clusters** | `new`, `mapped` | No active/processing states |
+| **ContentIdeas** | `new`, `queued`, `completed` | Missing `processing`, `failed` states |
+| **Tasks** | `queued`, `completed` | Missing intermediate states (processing, failed, cancelled) |
+| **Content** | `draft`, `review`, `published` | Separate from generation status |
+| **AutomationRun** | `running`, `paused`, `cancelled`, `completed`, `failed` | Well-defined but isolated |
+
+**Key Problem:** Status choices are inconsistent across models. Some models track generation status, others track editorial status, causing confusion.
+
+---
+
+### AI Function Progress Tracking
+
+**Location:** `backend/igny8_core/ai/tracker.py`, `backend/igny8_core/ai/engine.py`
+
+#### Progress Phases
+
+All AI functions emit standard progress phases:
+
+| Phase | Default Label | Percentage Range | Purpose |
+|-------|--------------|------------------|---------|
+| `INIT` | Initializing... | 0-10% | Validation, setup |
+| `PREP` | Preparing data... | 10-20% | Data loading, preparation |
+| `AI_CALL` | Processing with AI... | 20-80% | AI model execution |
+| `PARSE` | Parsing response... | 80-90% | Response validation, parsing |
+| `SAVE` | Saving results... | 90-100% | Database operations |
+| `DONE` | Complete! | 100% | Final state |
+
+**Implementation:** 
+- `StepTracker` class emits step-level events
+- `ProgressTracker` class manages Celery task state updates
+- `AIEngine` orchestrates phase transitions
+
+**Issues:**
+- Phase messages are generic and don't reflect actual counts
+- Percentage calculations sometimes inconsistent
+- No clear error state handling in phases
+
+---
+
+### Frontend Progress Modal System
+
+**Location:** `frontend/src/hooks/useProgressModal.ts`, `frontend/src/components/common/ProgressModal.tsx`
+
+#### Current Modal Implementation
+
+**Hook:** `useProgressModal`
+- Manages modal state, task polling, progress updates
+- Polls backend every 1 second for task status
+- Maps backend phases to user-friendly messages
+- Tracks step logs for debugging
+
+**Modal Component:** `ProgressModal`
+- Displays progress bar with percentage
+- Shows current phase and message
+- Lists step-by-step progress visually
+- Provides cancel/close actions
+
+#### Step Mapping Logic
+
+**Function:** `getStepInfo()` in `useProgressModal.ts`
+
+Maps backend phases to:
+- User-friendly messages with dynamic counts
+- Adjusted percentages for smooth progression
+- Function-specific labels (clustering vs. ideas vs. content)
+
+**Problems Identified:**
+1. **Inaccurate counts in messages**: Extracts counts from messages using regex, often missing or incorrect
+2. **Generic phase labels**: Messages don't always reflect what's actually happening
+3. **Inconsistent percentage progression**: Jumps or stalls during AI_CALL phase
+4. **Status text not aligned**: Labels in modal don't match backend phase names
+
+---
+
+### Progress Display by Page
+
+| Page | Location | Progress Display | Issues |
+|------|----------|------------------|--------|
+| Keywords | `frontend/src/pages/Planner/Keywords.tsx` | ProgressModal, AI logs | Clustering progress text inaccurate |
+| Clusters | `frontend/src/pages/Planner/Clusters.tsx` | ProgressModal only | No cluster generation function exists |
+| Ideas | `frontend/src/pages/Planner/Ideas.tsx` | ProgressModal, reload on complete | Text shows generic "preparing clusters" |
+| Tasks | `frontend/src/pages/Writer/Tasks.tsx` | ProgressModal, AI logs | Content generation text inaccurate |
+| Content | `frontend/src/pages/Writer/Content.tsx` | ProgressModal | Missing real-time updates |
+| Images | `frontend/src/pages/Writer/Images.tsx` | ImageQueueModal | Uses separate queue-based system |
+
+---
+
+### Known Bugs and Issues
+
+From `Pre-Launch-Pending.md` Known Bugs section:
+
+#### Manual AI Function Run Modals
+
+**Affected Pages:** Keywords, Clusters, Ideas, Tasks
+
+**Issues:**
+- Progress modal texts are not accurate for specific functions
+- Dynamic variables not properly populated with counts
+- Generic messages instead of function-specific ones
+
+**Example:**
+- Clustering: Should say "Mapping 45 keywords into clusters" but shows "Preparing data..."
+- Ideas: Should say "Generating ideas for 3 clusters" but shows generic text
+
+---
+
+#### Automation Wizard Progress
+
+**Page:** Automation (`frontend/src/pages/Automation/AutomationWizard.tsx`)
+
+**Issues:**
+- Wrong queue items displayed
+- Missing queue items for certain stages
+- Progress bar doesn't progress properly
+- Total in queue and processed counts buggy across stages
+- Stage cards: Real-time metrics not optimized
+
+---
+
+### WebSocket vs Polling
+
+**Current Implementation:** Polling-based
+
+**Location:** `useProgressModal.ts` - polls task status every 1 second
+
+**Note:** Code mentions WebSockets but current implementation uses REST API polling via `/api/v1/...` endpoints
+
+**Improvement Needed:** Consider WebSocket implementation for real-time updates without polling overhead
+
+---
+
+## Required Changes
+
+### A. Backend Status Standardization
+
+#### 1. Unified Status Enum
+
+**Create:** `backend/igny8_core/common/status_enums.py`
+
+Define standard status choices for all modules:
+
+```
+GENERATION_STATUS_CHOICES = [
+    ('pending', 'Pending'),
+    ('queued', 'Queued'),
+    ('processing', 'Processing'),
+    ('completed', 'Completed'),
+    ('failed', 'Failed'),
+    ('cancelled', 'Cancelled'),
+]
+
+CONTENT_STATUS_CHOICES = [
+    ('draft', 'Draft'),
+    ('review', 'Review'),
+    ('published', 'Published'),
+    ('archived', 'Archived'),
+]
+```
+
+**Action:** Add `generation_status` field to models that undergo AI processing:
+- Keywords (for extraction/clustering operations)
+- Clusters (for cluster generation, if implemented)
+- ContentIdeas (for idea generation)
+- Tasks (for content generation)
+- Content (separate from editorial status)
+
+#### 2. Enhanced Progress Details
+
+**Update:** `backend/igny8_core/ai/tracker.py`
+
+**Modifications:**
+- `StepTracker.update_step()` should include:
+  - `items_total`: Total count of items being processed
+  - `items_processed`: Current count of items processed
+  - `current_item_name`: Name/title of current item
+  - `estimated_remaining_seconds`: Estimated time remaining
+
+**Example Progress Payload:**
+```json
+{
+  "phase": "AI_CALL",
+  "message": "Clustering 45 keywords",
+  "percentage": 45,
+  "items_total": 45,
+  "items_processed": 20,
+  "current_item": "best seo tools",
+  "estimated_seconds_remaining": 120
+}
+```
+
+#### 3. Function-Specific Progress Messages
+
+**Update:** Each AI function's phase messages
+
+**Files to modify:**
+- `backend/igny8_core/ai/functions/auto_cluster.py`
+- `backend/igny8_core/ai/functions/generate_ideas.py`
+- `backend/igny8_core/ai/functions/generate_content.py`
+- `backend/igny8_core/ai/functions/generate_image_prompts.py`
+- `backend/igny8_core/ai/functions/generate_images.py`
+
+**Changes per function:**
+
+| Function | Phase | Accurate Message Template |
+|----------|-------|---------------------------|
+| auto_cluster | PREP | "Loading {count} keywords for clustering" |
+| auto_cluster | AI_CALL | "Analyzing keyword relationships ({processed}/{total})" |
+| auto_cluster | SAVE | "Creating {cluster_count} clusters" |
+| generate_ideas | PREP | "Preparing {count} cluster(s) for idea generation" |
+| generate_ideas | AI_CALL | "Generating ideas for cluster: {cluster_name}" |
+| generate_ideas | SAVE | "Created {idea_count} content ideas" |
+| generate_content | PREP | "Preparing task: {task_title}" |
+| generate_content | AI_CALL | "Writing {word_count}-word article" |
+| generate_content | SAVE | "Saving article: {title}" |
+| generate_image_prompts | PREP | "Mapping content for {count} image prompts" |
+| generate_image_prompts | AI_CALL | "Writing featured image prompt" |
+| generate_image_prompts | PARSE | "Writing {count} in-article image prompts" |
+| generate_images | PREP | "Preparing {count} images for generation" |
+| generate_images | AI_CALL | "Generating image {current}/{total}: {prompt}" |
+
+**Implementation:** Use `self.tracker.update_step()` with dynamic values from actual data
+
+---
+
+### B. Frontend Progress Display Improvements
+
+#### 1. Update ProgressModal Messages
+
+**File:** `frontend/src/components/common/ProgressModal.tsx`
+
+**Function:** `getSuccessMessage()`
+
+**Current Issues:**
+- Generic success messages
+- Count extraction from logs is unreliable
+- Doesn't distinguish between function types clearly
+
+**Required Changes:**
+| Function | Current Success Message | Improved Success Message |
+|----------|------------------------|--------------------------|
+| Clustering | "Clustering complete" | "45 keywords mapped into 8 clusters" |
+| Ideas | "Content ideas created successfully" | "Generated 12 content ideas for 3 clusters" |
+| Content | "Article drafted successfully" | "1,245-word article drafted successfully" |
+| Image Prompts | Generic text | "1 Featured Image + 4 In-article Image Prompts ready" |
+| Images | "Images generated successfully" | "5 images generated successfully" |
+
+**Implementation:** Extract counts from backend `details` field, not from message strings
+
+---
+
+#### 2. Improve Step Mapping Logic
+
+**File:** `frontend/src/hooks/useProgressModal.ts`
+
+**Function:** `getStepInfo()`
+
+**Problems:**
+- Complex regex-based count extraction from messages
+- Percentage calculation doesn't match backend
+- Messages manually constructed instead of using backend messages
+
+**Solution:**
+- **Rely on backend `details` field** for counts:
+  ```typescript
+  const { items_total, items_processed, current_item } = progress.details;
+  ```
+- Use backend message directly when it contains proper counts
+- Only enhance message format, don't reconstruct it
+
+**Example Refactor:**
+```typescript
+// OLD: Complex regex extraction
+const keywordCount = extractNumber(/(\d+)\s+keyword/i, message);
+
+// NEW: Use backend details
+const percentage = details.percentage;
+const message = details.message; // Already has counts
+const itemName = details.current_item || '';
+```
+
+---
+
+#### 3. Real-Time Updates Per Page
+
+**Pages to update:** Keywords, Ideas, Tasks, Content
+
+**Current behavior:** Modal closes, then data reloads
+
+**Improved behavior:**
+- Show inline status badge in table rows during processing
+- Update table row in real-time as status changes
+- Auto-reload specific rows instead of entire table
+- Show notification when task completes in background
+
+**Implementation approach:**
+- Subscribe to task updates while modal is open
+- Update table state with new status
+- Add `status` badge column to tables showing:
+  - 🔄 Processing (animated)
+  - ✅ Completed
+  - ❌ Failed
+  - ⏸️ Paused
+
+---
+
+### C. Automation Wizard Progress Fixes
+
+**File:** `frontend/src/pages/Automation/AutomationWizard.tsx`
+
+**Issues identified:**
+1. Wrong queue items displayed
+2. Missing queue items
+3. Progress bar inaccurate
+4. Stage counts buggy
+
+**Required fixes:**
+
+#### 1. Stage Progress Cards
+
+**Current location:** Stage cards display in wizard
+
+**Problems:**
+- Counts mismatch between backend and frontend
+- "In Queue" vs "Processed" numbers don't add up
+- Real-time updates missing
+
+**Fix:**
+- Pull stage results from `AutomationRun.stage_X_result` JSON fields
+- Display accurate counts:
+  ```
+  Stage 1: Clustering
+  - Keywords Loaded: 45
+  - Clusters Created: 8
+  - Status: Completed
+  ```
+
+#### 2. Queue Item Display
+
+**Fix queue item tracking:**
+- Each stage should show items being processed
+- Items should appear in queue before processing
+- Items should move to "Completed" list after processing
+- Failed items should show in "Failed" section with retry option
+
+**Data structure per stage:**
+```json
+{
+  "pending": ["item1", "item2"],
+  "processing": ["item3"],
+  "completed": ["item4", "item5"],
+  "failed": [{"item": "item6", "error": "..."}]
+}
+```
+
+#### 3. Progress Bar Calculation
+
+**Fix:** 
+- Base percentage on actual completed stages
+- Within-stage percentage based on items processed
+- Formula: `(completed_stages * 100 / 7) + (current_stage_progress / 7)`
+
+---
+
+### D. Error State Handling
+
+#### Backend Error Logging
+
+**Location:** `backend/igny8_core/ai/engine.py`
+
+**Current:** Errors logged but status not always propagated
+
+**Improvement:**
+- Always set task state to `FAILURE` on error
+- Include detailed error in state metadata
+- Log error with context (function, input data, trace)
+
+**Error payload structure:**
+```json
+{
+  "status": "error",
+  "error_type": "InsufficientCreditsError",
+  "error_message": "Insufficient credits. Required: 45, Available: 20",
+  "phase": "INIT",
+  "timestamp": "2025-12-11T10:30:00Z"
+}
+```
+
+#### Frontend Error Display
+
+**Files:** All progress modals
+
+**Current:** Generic "Task failed" message
+
+**Improvement:**
+- Show specific error type
+- Display user-friendly error message
+- Provide actionable next steps
+- Show "Retry" button for recoverable errors
+
+**Error message mapping:**
+
+| Error Type | User Message | Action |
+|------------|--------------|--------|
+| InsufficientCreditsError | "Not enough credits. You need X credits." | "Purchase Credits" button |
+| ValidationError | "Invalid data: {details}" | "Fix Data" button |
+| AIProviderError | "AI service temporarily unavailable" | "Retry" button |
+| TimeoutError | "Request timed out. Try again." | "Retry" button |
+
+---
+
+## QA Testing Checklist
+
+### Manual AI Function Tests
+
+Test each function on each page:
+
+| Page | Function | Test Case | Expected Result |
+|------|----------|-----------|-----------------|
+| Keywords | Clustering | Select 50 keywords, run clustering | Modal shows "Clustering 50 keywords", creates clusters, shows "50 keywords mapped into X clusters" |
+| Ideas | Generate Ideas | Select 3 clusters, generate ideas | Modal shows "Generating ideas for 3 clusters", creates ideas, shows "Generated X ideas for 3 clusters" |
+| Tasks | Generate Content | Select 1 task, generate content | Modal shows "Writing {word_count}-word article", creates content, shows "{word_count}-word article drafted" |
+| Tasks | Generate Image Prompts | Select 1 content, generate prompts | Modal shows "Mapping content for X prompts", shows "1 Featured + X In-article prompts ready" |
+| Images | Generate Images | Select content with prompts, generate | ImageQueueModal shows each image generating, completes all |
+
+### Edge Case Tests
+
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| Task cancelled mid-process | Status updates to "cancelled", modal shows cancellation message |
+| Task fails due to insufficient credits | Error modal with credit purchase link |
+| Task fails due to validation error | Error modal with specific validation issue |
+| Multiple tasks running simultaneously | Each has independent progress tracking |
+| Network disconnection during task | Polling resumes when reconnected, catches up with status |
+| Task completes while modal is closed | Table updates status automatically, notification shown |
+
+### Automation Wizard Tests
+
+| Stage | Test Case | Expected Result |
+|-------|-----------|-----------------|
+| Stage 1 | Run clustering on 100 keywords | Shows batch progress, creates clusters, displays accurate counts |
+| Stage 2 | Generate ideas for 10 clusters | Shows cluster-by-cluster progress, creates ideas |
+| Stage 3 | Convert ideas to tasks | Shows conversion progress, creates tasks |
+| Stage 4 | Generate content for tasks | Shows content generation per task |
+| Stage 5 | Generate image prompts | Shows prompt creation progress |
+| Stage 6 | Generate images | Shows image generation progress |
+| Stage 7 | Final review | Shows completed content ready for publishing |
+| Pause/Resume | Pause at stage 3, resume | Continues from where it left off |
+| Cancel | Cancel at stage 4 | Stops processing, shows cancelled status |
+
+---
+
+## Implementation Priority
+
+### Phase 1: Backend Fixes (Week 1)
+1. ✅ Create unified status enums
+2. ✅ Add `generation_status` fields to models
+3. ✅ Update AI function progress messages with accurate counts
+4. ✅ Enhance tracker to include item counts and current item
+
+### Phase 2: Frontend Display (Week 1-2)
+1. ✅ Update ProgressModal success messages
+2. ✅ Refactor step mapping logic to use backend details
+3. ✅ Add real-time status badges to table rows
+4. ✅ Improve error message display
+
+### Phase 3: Automation Wizard (Week 2)
+1. ✅ Fix stage progress cards
+2. ✅ Fix queue item tracking
+3. ✅ Fix progress bar calculation
+4. ✅ Add pause/resume/cancel controls
+
+### Phase 4: QA & Polish (Week 2-3)
+1. ✅ Run all manual tests
+2. ✅ Run all edge case tests
+3. ✅ Run automation wizard tests
+4. ✅ Fix any discovered issues
+5. ✅ Performance optimization
+
+---
+
+## Success Metrics
+
+- ✅ All progress modals show accurate counts and messages
+- ✅ Progress percentages match actual work completed
+- ✅ Automation wizard shows correct queue states
+- ✅ Error messages are specific and actionable
+- ✅ Real-time updates work consistently
+- ✅ No user-reported confusion about task status
+- ✅ All QA test cases pass
+
+---
+
+## Related Files Reference
+
+### Backend
+- `backend/igny8_core/business/planning/models.py` - Keywords, Clusters, ContentIdeas models
+- `backend/igny8_core/business/content/models.py` - Tasks, Content models
+- `backend/igny8_core/business/automation/models.py` - AutomationRun model
+- `backend/igny8_core/ai/tracker.py` - ProgressTracker, StepTracker
+- `backend/igny8_core/ai/engine.py` - AIEngine orchestration
+- `backend/igny8_core/ai/functions/*.py` - All AI function implementations
+
+### Frontend
+- `frontend/src/hooks/useProgressModal.ts` - Progress modal hook
+- `frontend/src/components/common/ProgressModal.tsx` - Progress modal component
+- `frontend/src/components/common/ImageQueueModal.tsx` - Image generation modal
+- `frontend/src/pages/Planner/Keywords.tsx` - Keywords page with clustering
+- `frontend/src/pages/Planner/Ideas.tsx` - Ideas page with idea generation
+- `frontend/src/pages/Writer/Tasks.tsx` - Tasks page with content generation
+- `frontend/src/pages/Writer/Content.tsx` - Content page
+- `frontend/src/pages/Writer/Images.tsx` - Images page
+- `frontend/src/pages/Automation/AutomationWizard.tsx` - Automation wizard
+
+---
+
+## Notes
+
+- Consider WebSocket implementation for production to reduce polling overhead
+- Status badges in tables should be subtle and not distract from main content
+- Error messages should prioritize user understanding over technical accuracy
+- Progress messages should be encouraging and informative
+- Real-time updates should not cause UI flickering or performance issues
--- a/docs/PRE-LAUNCH/ITEM-2-CREDITS-BILLING-PRICING.md
+++ b/docs/PRE-LAUNCH/ITEM-2-CREDITS-BILLING-PRICING.md
@@ -0,0 +1,628 @@
+# Item 2: Credits, Billing, Pricing Logic, and Usage Limits
+
+**Priority:** Critical  
+**Target:** Production Launch  
+**Last Updated:** December 11, 2025
+
+---
+
+## Overview
+
+Define and implement a comprehensive credit cost system, plan-based usage limits, and billing logic for all AI operations. This includes setting credit costs per function, establishing plan tiers with limits, and implementing enforcement mechanisms across backend and frontend.
+
+---
+
+## Current Implementation Analysis
+
+### Credit System Architecture
+
+**Location:** `backend/igny8_core/business/billing/`
+
+#### Credit Models
+
+| Model | Purpose | Key Fields |
+|-------|---------|------------|
+| **CreditTransaction** | Tracks all credit additions/deductions | `transaction_type`, `amount`, `balance_after`, `description` |
+| **CreditUsageLog** | Detailed log per AI operation | `operation_type`, `credits_used`, `cost_usd`, `model_used`, `tokens_input`, `tokens_output` |
+| **CreditCostConfig** | Admin-configurable credit costs | `operation_type`, `credits_cost`, `unit`, `display_name` |
+
+**Credit Transaction Types:**
+- `purchase` - Credit purchase
+- `subscription` - Monthly subscription renewal
+- `refund` - Credit refund
+- `deduction` - Usage deduction (AI operations)
+- `adjustment` - Manual admin adjustment
+
+#### Credit Service
+
+**Location:** `backend/igny8_core/business/billing/services/credit_service.py`
+
+**Methods:**
+- `get_credit_cost(operation_type, amount)` - Calculate cost for operation
+- `check_credits(account, operation_type, amount)` - Validate sufficient credits
+- `deduct_credits(account, amount, operation_type, ...)` - Deduct and log
+- `deduct_credits_for_operation(...)` - Convenience method with auto-calculation
+
+**Logic:**
+1. Checks database `CreditCostConfig` first
+2. Falls back to hardcoded `CREDIT_COSTS` constants
+3. Applies unit-based calculation (per 100 words, per image, etc.)
+4. Validates sufficient balance before deduction
+5. Creates both `CreditTransaction` and `CreditUsageLog` records
+
+---
+
+### Current Credit Costs
+
+**Location:** `backend/igny8_core/business/billing/constants.py`
+
+| Operation | Current Cost | Unit | Notes |
+|-----------|--------------|------|-------|
+| `clustering` | 10 credits | per request | Clusters all submitted keywords |
+| `idea_generation` | 15 credits | per request | Ideas for one cluster |
+| `content_generation` | 1 credit | per 100 words | Word-count based |
+| `image_prompt_extraction` | 2 credits | per content | Extract prompts from content |
+| `image_generation` | 5 credits | per image | Generate single image |
+| `linking` | 8 credits | per content | Internal linking (NEW) |
+| `optimization` | 1 credit | per 200 words | Content optimization (NEW) |
+| `site_structure_generation` | 50 credits | per site | Site blueprint (Phase 7) |
+| `site_page_generation` | 20 credits | per page | Page generation (Phase 7) |
+
+**Legacy Aliases:**
+- `ideas` → `idea_generation`
+- `content` → 3 credits fixed (legacy)
+- `images` → `image_generation`
+- `reparse` → 1 credit
+
+**Issues with Current Costs:**
+1. **Not optimized for profitability** - Costs may not reflect actual AI provider costs
+2. **Arbitrary values** - No clear formula based on model costs, processing time, or value
+3. **Inconsistent granularity** - Some per-request, some per-word, some per-item
+4. **No differentiation by quality** - Same cost regardless of model quality (GPT-4 vs GPT-3.5)
+
+---
+
+### Plan Model and Limits
+
+**Location:** `backend/igny8_core/auth/models.py` - `Plan` model
+
+#### Current Plan Structure
+
+| Field | Purpose | Current State |
+|-------|---------|---------------|
+| `name`, `slug` | Plan identification | ✅ Implemented |
+| `price`, `billing_cycle` | Pricing | ✅ Monthly/Annual support |
+| `included_credits` | Monthly credit allocation | ✅ Implemented |
+| `extra_credit_price` | Per-credit overage cost | ✅ Default $0.01 |
+| `allow_credit_topup` | Can buy more credits | ✅ Boolean flag |
+| `auto_credit_topup_threshold` | Auto-buy trigger | ✅ Optional |
+| `auto_credit_topup_amount` | Auto-buy amount | ✅ Optional |
+| `max_users` | Users per account | ✅ Implemented |
+| `max_sites` | Sites per account | ✅ Implemented |
+| `max_industries` | Industries/sectors limit | ✅ Optional |
+| `max_author_profiles` | Writing styles limit | ✅ Default 5 |
+
+**What's MISSING:**
+- ❌ Max keywords limit
+- ❌ Max clusters limit
+- ❌ Max ideas limit
+- ❌ Max content pieces limit
+- ❌ Max images limit
+- ❌ Max tasks in queue limit
+- ❌ Daily/monthly usage caps (beyond credits)
+- ❌ Per-user vs per-account limits distinction
+
+---
+
+### Account Credit Balance
+
+**Location:** `backend/igny8_core/auth/models.py` - `Account` model
+
+**Field:** `credits` (IntegerField with MinValueValidator(0))
+
+**Current Behavior:**
+- Credits deducted on AI operation completion
+- Credit balance checked before operation starts
+- `InsufficientCreditsError` raised if balance < required
+
+**No Implementation For:**
+- Credit expiration dates
+- Credit rollover rules (monthly vs annual)
+- Negative balance prevention (hard stop vs warning)
+- Credit reserve for pending operations
+
+---
+
+## Pricing Plan Requirements
+
+### Recommended Plan Tiers
+
+Based on industry standards and target market:
+
+| Plan | Monthly Price | Annual Price | Included Credits | Target User |
+|------|---------------|--------------|------------------|-------------|
+| **Free** | $0 | $0 | 50 | Trial users, hobbyists |
+| **Starter** | $29 | $299 (15% off) | 500 | Solo creators, small blogs |
+| **Growth** | $99 | $1,019 (15% off) | 2,000 | Growing sites, agencies |
+| **Pro** | $299 | $3,077 (15% off) | 7,500 | Power users, large agencies |
+| **Enterprise** | Custom | Custom | Custom | Enterprise clients |
+
+**Free Plan Considerations:**
+- Should be marked `is_internal=True` to hide from public pricing
+- Limits should be strict enough to encourage upgrade
+- Should not include advanced features (automation, API access)
+
+---
+
+### Usage Limits Per Plan
+
+**Proposed Limits** (to be finalized):
+
+| Limit Type | Free | Starter | Growth | Pro | Enterprise |
+|------------|------|---------|--------|-----|------------|
+| **Monthly Credits** | 50 | 500 | 2,000 | 7,500 | Custom |
+| **Max Users** | 1 | 2 | 5 | 15 | Unlimited |
+| **Max Sites** | 1 | 3 | 10 | 50 | Unlimited |
+| **Max Keywords (saved)** | 100 | 1,000 | 5,000 | 25,000 | Unlimited |
+| **Max Clusters** | 20 | 100 | 500 | 2,500 | Unlimited |
+| **Max Ideas (saved)** | 50 | 500 | 2,500 | 12,500 | Unlimited |
+| **Max Content Pieces** | 25 | 250 | 1,250 | 6,250 | Unlimited |
+| **Max Images** | 25 | 250 | 1,250 | 6,250 | Unlimited |
+| **Max Queue Size** | 5 | 20 | 50 | 200 | Unlimited |
+| **Automation Enabled** | ❌ | ❌ | ✅ | ✅ | ✅ |
+| **API Access** | ❌ | ❌ | ✅ | ✅ | ✅ |
+| **Priority Support** | ❌ | ❌ | ❌ | ✅ | ✅ |
+
+**Notes:**
+- "Unlimited" means no hard limit, but still subject to fair use policy
+- Limits apply per account (across all sites in account)
+- Deleted items don't count toward limits (soft-delete system)
+
+---
+
+### Credit Cost Optimization Strategy
+
+**Goal:** Define credit costs that:
+1. Cover AI provider costs + margin
+2. Are competitive with market rates
+3. Encourage usage without abuse
+4. Scale predictably with usage
+
+#### Recommended Credit Cost Revisions
+
+**Analysis Required:**
+- [ ] Calculate actual AI provider costs per operation (OpenAI, Runware, etc.)
+- [ ] Add 30-50% margin for infrastructure, support, and profit
+- [ ] Compare with competitor pricing (Jasper, Copy.ai, Writesonic)
+- [ ] Test with sample use cases to ensure plan value
+
+**Proposed Adjustments** (pending analysis):
+
+| Operation | Current | Proposed | Reasoning |
+|-----------|---------|----------|-----------|
+| Clustering | 10 | **8** | Lower barrier for discovery phase |
+| Idea Generation | 15 | **12** | Encourage ideation before writing |
+| Content (100 words) | 1 | **1.5** | Reflect actual GPT-4 costs |
+| Image Prompts | 2 | **3** | More complex extraction logic |
+| Image Generation | 5 | **6** | Runware/DALL-E costs increasing |
+| Optimization | 1 per 200 words | **0.5 per 100 words** | Encourage optimization usage |
+
+**Variable Costs by Model Quality:**
+- **Option:** Charge more for GPT-4 vs GPT-3.5, DALL-E 3 vs DALL-E 2
+- **Implementation:** Add `model_tier` multiplier in `get_credit_cost()`
+
+---
+
+## Required Implementation
+
+### A. Expand Plan Model with Usage Limits
+
+**File:** `backend/igny8_core/auth/models.py` - `Plan` model
+
+**Add Fields:**
+
+```python
+# Content Creation Limits (NULL = unlimited)
+max_keywords = models.IntegerField(
+    null=True, blank=True,
+    validators=[MinValueValidator(1)],
+    help_text="Maximum keywords saved per account"
+)
+max_clusters = models.IntegerField(
+    null=True, blank=True,
+    validators=[MinValueValidator(1)],
+    help_text="Maximum clusters per account"
+)
+max_ideas = models.IntegerField(
+    null=True, blank=True,
+    validators=[MinValueValidator(1)],
+    help_text="Maximum content ideas saved per account"
+)
+max_content = models.IntegerField(
+    null=True, blank=True,
+    validators=[MinValueValidator(1)],
+    help_text="Maximum content pieces per account"
+)
+max_images = models.IntegerField(
+    null=True, blank=True,
+    validators=[MinValueValidator(1)],
+    help_text="Maximum images per account"
+)
+
+# Queue and Rate Limits
+max_queue_size = models.IntegerField(
+    default=10,
+    validators=[MinValueValidator(1)],
+    help_text="Maximum concurrent items in queue"
+)
+max_daily_ai_requests = models.IntegerField(
+    null=True, blank=True,
+    validators=[MinValueValidator(1)],
+    help_text="Maximum AI requests per day (prevents abuse)"
+)
+max_monthly_content_generated = models.IntegerField(
+    null=True, blank=True,
+    validators=[MinValueValidator(1)],
+    help_text="Maximum content pieces generated per month"
+)
+
+# Feature Access Flags
+allow_automation = models.BooleanField(
+    default=False,
+    help_text="Enable automation wizard"
+)
+allow_api_access = models.BooleanField(
+    default=False,
+    help_text="Enable API access"
+)
+allow_bulk_operations = models.BooleanField(
+    default=True,
+    help_text="Enable bulk actions (delete, export, etc.)"
+)
+```
+
+**Migration:** Create Django migration to add these fields with default NULL values
+
+---
+
+### B. Create Limit Enforcement Service
+
+**File:** `backend/igny8_core/business/billing/services/limit_service.py` (NEW)
+
+**Service Class:** `LimitService`
+
+**Methods to Implement:**
+
+| Method | Purpose | Returns |
+|--------|---------|---------|
+| `check_keyword_limit(account)` | Check if can add more keywords | `bool` or raises `LimitExceededError` |
+| `check_cluster_limit(account)` | Check if can add more clusters | `bool` or raises `LimitExceededError` |
+| `check_idea_limit(account)` | Check if can add more ideas | `bool` or raises `LimitExceededError` |
+| `check_content_limit(account)` | Check if can add more content | `bool` or raises `LimitExceededError` |
+| `check_image_limit(account)` | Check if can add more images | `bool` or raises `LimitExceededError` |
+| `check_queue_limit(account)` | Check queue capacity | `bool` or raises `LimitExceededError` |
+| `check_daily_request_limit(account)` | Check daily AI request quota | `bool` or raises `LimitExceededError` |
+| `get_usage_stats(account)` | Get current usage counts | `dict` with all counters |
+| `get_limit_stats(account)` | Get limits and remaining capacity | `dict` with limits |
+
+**Implementation Logic:**
+
+```python
+def check_keyword_limit(account):
+    plan = account.plan
+    if plan.max_keywords is None:
+        return True  # Unlimited
+    
+    current_count = Keywords.objects.filter(
+        account=account,
+        deleted_at__isnull=True  # Exclude soft-deleted
+    ).count()
+    
+    if current_count >= plan.max_keywords:
+        raise LimitExceededError(
+            f"Keyword limit reached ({plan.max_keywords}). Upgrade your plan."
+        )
+    
+    return True
+```
+
+**Exception:** `LimitExceededError` (inherit from `BillingException`)
+
+---
+
+### C. Integrate Limit Checks in API Views
+
+**Files to Update:**
+
+- `backend/igny8_core/modules/planner/views.py` - KeywordsViewSet
+- `backend/igny8_core/modules/planner/views.py` - ClustersViewSet
+- `backend/igny8_core/modules/planner/views.py` - ContentIdeasViewSet
+- `backend/igny8_core/modules/writer/views.py` - TasksViewSet
+- `backend/igny8_core/modules/writer/views.py` - ContentViewSet
+
+**Integration Points:**
+
+| ViewSet | Action | Check to Add |
+|---------|--------|--------------|
+| KeywordsViewSet | `create()` | `LimitService.check_keyword_limit(account)` |
+| KeywordsViewSet | `bulk_create()` | Check limit with proposed count |
+| ClustersViewSet | `create()` | `LimitService.check_cluster_limit(account)` |
+| ContentIdeasViewSet | `create()` | `LimitService.check_idea_limit(account)` |
+| TasksViewSet | `create()` | `LimitService.check_content_limit(account)` + `check_queue_limit()` |
+| ContentViewSet | `create()` | `LimitService.check_content_limit(account)` |
+
+**Example Integration:**
+
+```python
+def create(self, request, *args, **kwargs):
+    account = request.user.account
+    
+    # Check limit before creating
+    try:
+        LimitService.check_keyword_limit(account)
+    except LimitExceededError as e:
+        return Response({
+            'error': str(e),
+            'error_code': 'LIMIT_EXCEEDED',
+            'upgrade_url': '/pricing'
+        }, status=403)
+    
+    # Proceed with creation
+    return super().create(request, *args, **kwargs)
+```
+
+---
+
+### D. Add Usage Tracking and Counter Cache
+
+**Optimization:** Instead of counting records on every request, cache counts
+
+**Implementation Options:**
+
+#### Option 1: Add Counter Fields to Account Model
+
+```python
+# Add to Account model
+keyword_count = models.IntegerField(default=0)
+cluster_count = models.IntegerField(default=0)
+idea_count = models.IntegerField(default=0)
+content_count = models.IntegerField(default=0)
+image_count = models.IntegerField(default=0)
+```
+
+**Update counters in signals:**
+- `post_save` signal: increment counter
+- `post_delete` signal: decrement counter
+- Periodic reconciliation task to fix drift
+
+#### Option 2: Cache Usage Stats (Recommended)
+
+Use Django cache with 5-minute TTL:
+
+```python
+def get_cached_usage_stats(account):
+    cache_key = f'usage_stats_{account.id}'
+    stats = cache.get(cache_key)
+    
+    if stats is None:
+        stats = {
+            'keywords': Keywords.objects.filter(account=account, deleted_at__isnull=True).count(),
+            'clusters': Clusters.objects.filter(account=account, deleted_at__isnull=True).count(),
+            # ... etc
+        }
+        cache.set(cache_key, stats, 300)  # 5 minutes
+    
+    return stats
+```
+
+**Invalidate cache on:**
+- Create operations
+- Delete operations
+- Soft-delete operations
+
+---
+
+### E. Frontend Limit Display
+
+#### 1. Usage Dashboard Widget
+
+**Location:** `frontend/src/components/dashboard/UsageLimitsWidget.tsx` (NEW)
+
+**Display:**
+- Current usage vs limit for each resource
+- Progress bars with color coding:
+  - Green: < 70% used
+  - Yellow: 70-90% used
+  - Red: > 90% used
+- "Upgrade Plan" button when approaching limits
+
+**Example UI:**
+
+```
+Usage & Limits
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Keywords: 750 / 1,000 ████████░░ 75%
+Clusters: 45 / 100    ████░░░░░░ 45%
+Ideas: 380 / 500      ███████░░░ 76%
+Content: 120 / 250    ████░░░░░░ 48%
+
+[Upgrade Plan]
+```
+
+#### 2. Inline Warnings
+
+**Show warnings when approaching limits:**
+
+- At 80%: Yellow badge "Approaching limit"
+- At 90%: Orange warning "Near limit - Upgrade recommended"
+- At 100%: Red error "Limit reached - Upgrade required"
+
+**Display in:**
+- Header metrics
+- Page headers
+- Before bulk operations
+- In forms (disable submit if limit reached)
+
+#### 3. Create/Import Dialogs
+
+**Add limit check before showing form:**
+
+```typescript
+const handleCreateKeyword = () => {
+  const stats = usageStats; // from API
+  const limit = account.plan.max_keywords;
+  
+  if (limit && stats.keywords >= limit) {
+    toast.error('Keyword limit reached. Upgrade your plan.');
+    navigate('/settings/billing');
+    return;
+  }
+  
+  setShowCreateModal(true);
+};
+```
+
+#### 4. Upgrade Prompts
+
+**When limit error occurs:**
+- Show modal with:
+  - Current plan
+  - Current limit
+  - Recommended plan
+  - Benefits of upgrading
+  - "Upgrade Now" CTA
+
+---
+
+### F. Credit Cost Configuration UI (Admin)
+
+**Location:** Django Admin or custom Admin Panel page
+
+**Feature:** Allow superusers to edit credit costs without code changes
+
+**Admin Interface:**
+- List all operations with current costs
+- Edit cost, unit, and display name
+- Track change history (previous_cost field)
+- Enable/disable operations
+- Preview impact on sample use cases
+
+**Models Used:**
+- `CreditCostConfig` - Admin-editable costs
+- Falls back to `CREDIT_COSTS` constants if not configured
+
+---
+
+## Testing Requirements
+
+### Limit Enforcement Tests
+
+| Test Case | Expected Result |
+|-----------|-----------------|
+| Create keyword at limit | Error: "Keyword limit reached" |
+| Create keyword below limit | Success |
+| Create 10 keywords via bulk import at limit | Error with count blocked |
+| Delete keyword then create | Success (count decremented) |
+| Soft-delete keyword then restore | Counts update correctly |
+| Upgrade plan mid-session | New limits apply immediately |
+
+### Credit Deduction Tests
+
+| Test Case | Expected Result |
+|-----------|-----------------|
+| Generate content with sufficient credits | Content created, credits deducted |
+| Generate content with insufficient credits | Error: "Insufficient credits" |
+| Generate content at exact credit balance | Success, balance = 0 |
+| Generate multiple items in queue | Each deducts credits sequentially |
+| Credit deduction failure mid-operation | Transaction rolled back, no partial deduction |
+
+### Plan Limit Tests
+
+| Plan | Test Case | Expected Result |
+|------|-----------|-----------------|
+| Free | Create 101st keyword (limit: 100) | Blocked |
+| Starter | Create 6 queue items (limit: 5) | Blocked |
+| Growth | Enable automation | Success (has access) |
+| Pro | Create unlimited keywords | Success (no limit) |
+| Enterprise | All operations | No limits enforced |
+
+---
+
+## Pricing Page Updates
+
+**Location:** `frontend/src/pages/marketing/Pricing.tsx`
+
+### Required Elements
+
+1. **Plan Comparison Table**
+   - All tiers side-by-side
+   - Feature checkmarks
+   - Highlight "Most Popular" plan
+   - Monthly/Annual toggle with savings badge
+
+2. **Usage Limits Display**
+   - Show key limits per plan
+   - Use "Unlimited" label for null limits
+   - Tooltip explanations for complex limits
+
+3. **Credit System Explanation**
+   - What credits are
+   - How they're consumed
+   - How to buy more
+   - Credit rollover rules
+
+4. **FAQ Section**
+   - "What happens when I run out of credits?"
+   - "Can I change plans mid-month?"
+   - "Do unused credits roll over?"
+   - "What's included in Enterprise?"
+
+5. **Calculator Widget** (Optional)
+   - Estimate monthly usage
+   - Recommend plan based on needs
+   - Show credit consumption breakdown
+
+---
+
+## Success Metrics
+
+- ✅ All AI operations enforce credit checks
+- ✅ All create operations enforce limit checks
+- ✅ Credit costs reflect actual provider costs + margin
+- ✅ Plans are competitively priced
+- ✅ Usage dashboard shows accurate counts
+- ✅ Limit warnings prevent user frustration
+- ✅ Upgrade flow is clear and frictionless
+- ✅ Admin can adjust costs without code changes
+- ✅ All tests pass
+
+---
+
+## Related Files Reference
+
+### Backend
+- `backend/igny8_core/auth/models.py` - Account, Plan models
+- `backend/igny8_core/business/billing/models.py` - Credit models
+- `backend/igny8_core/business/billing/constants.py` - Credit costs
+- `backend/igny8_core/business/billing/services/credit_service.py` - Credit logic
+- `backend/igny8_core/business/billing/services/limit_service.py` - **NEW** Limit enforcement
+- `backend/igny8_core/modules/planner/views.py` - Planner API views
+- `backend/igny8_core/modules/writer/views.py` - Writer API views
+
+### Frontend
+- `frontend/src/components/dashboard/UsageLimitsWidget.tsx` - **NEW** Usage display
+- `frontend/src/pages/marketing/Pricing.tsx` - Pricing page
+- `frontend/src/pages/Planner/*.tsx` - Planner pages (add limit checks)
+- `frontend/src/pages/Writer/*.tsx` - Writer pages (add limit checks)
+- `frontend/src/services/api.ts` - API service (handle limit errors)
+
+---
+
+## Notes
+
+- Limits should be enforced at API level, not just UI level
+- Consider "soft limits" with warnings vs "hard limits" with blocks
+- Credit expiration and rollover rules need business decision
+- Enterprise pricing needs custom quote system
+- Monitor actual usage patterns to optimize costs and limits
+- A/B test different pricing tiers to maximize conversion
--- a/docs/PRE-LAUNCH/ITEM-3-PROMPT-OPTIMIZATION.md
+++ b/docs/PRE-LAUNCH/ITEM-3-PROMPT-OPTIMIZATION.md
@@ -0,0 +1,713 @@
+# Item 3: Prompt Improvement and Model Optimization
+
+**Priority:** High  
+**Target:** Production Launch  
+**Last Updated:** December 11, 2025
+
+---
+
+## Overview
+
+Redesign and optimize all AI prompts for clustering, idea generation, content generation, and image prompt extraction to achieve:
+- Extreme accuracy and consistent outputs
+- Faster processing with optimized token usage
+- Correct word count adherence (500, 1000, 1500 words)
+- Improved clustering quality and idea relevance
+- Better image prompt clarity and relevance
+
+---
+
+## Current Prompt System Architecture
+
+### Prompt Registry
+
+**Location:** `backend/igny8_core/ai/prompts.py`
+
+**Class:** `PromptRegistry`
+
+**Hierarchy** (resolution order):
+1. Task-level `prompt_override` (if exists on specific task)
+2. Database prompt from `AIPrompt` model (account-specific)
+3. Default fallback from `PromptRegistry.DEFAULT_PROMPTS`
+
+**Storage:**
+- Default prompts: Hardcoded in `prompts.py`
+- Account overrides: `system_aiprompt` database table
+- Task overrides: `prompt_override` field on task object
+
+---
+
+## Current Prompts Analysis
+
+### 1. Clustering Prompt
+
+**Function:** `auto_cluster`  
+**File:** `backend/igny8_core/ai/functions/auto_cluster.py`  
+**Prompt Key:** `'clustering'`
+
+#### Current Prompt Structure
+
+**Approach:** Semantic strategist + intent-driven clustering
+
+**Key Instructions:**
+- Return single JSON with "clusters" array
+- Each cluster: name, description, keywords[]
+- Multi-dimensional grouping (intent, use-case, function, persona, context)
+- Model real search behavior and user journeys
+- Avoid superficial groupings and duplicates
+- 3-10 keywords per cluster
+
+**Strengths:**
+✅ Clear JSON output format  
+✅ Detailed grouping logic with dimensions  
+✅ Emphasis on semantic strength over keyword matching  
+✅ User journey modeling (Problem → Solution, General → Specific)  
+
+**Issues:**
+❌ Very long prompt (~400+ tokens) - may confuse model  
+❌ No examples provided - model must guess formatting  
+❌ Doesn't specify what to do with outliers explicitly  
+❌ No guidance on cluster count (outputs variable)  
+❌ Description length not constrained  
+
+**Real-World Performance Issues:**
+- Sometimes creates too many small clusters (1-2 keywords each)
+- Inconsistent cluster naming convention
+- Descriptions sometimes generic ("Keywords related to...")
+
+---
+
+### 2. Idea Generation Prompt
+
+**Function:** `generate_ideas`  
+**File:** `backend/igny8_core/ai/functions/generate_ideas.py`  
+**Prompt Key:** `'ideas'`
+
+#### Current Prompt Structure
+
+**Approach:** SEO-optimized content ideas + outlines
+
+**Key Instructions:**
+- Input: Clusters + Keywords
+- Output: JSON "ideas" array
+- 1 cluster_hub + 2-4 supporting ideas per cluster
+- Fields: title, description, content_type, content_structure, cluster_id, estimated_word_count, covered_keywords
+- Outline format: intro (hook + 2 paragraphs), 5-8 H2 sections with 2-3 H3s each
+- Content mixing: paragraphs, lists, tables, blockquotes
+- No bullets/lists at start
+- Professional tone, no generic phrasing
+
+**Strengths:**
+✅ Detailed outline structure  
+✅ Content mixing guidance (lists, tables, blockquotes)  
+✅ Clear JSON format  
+✅ Tone guidelines  
+
+**Issues:**
+❌ Very complex prompt (600+ tokens)  
+❌ Outline format too prescriptive (might limit creativity)  
+❌ No examples provided  
+❌ Estimated word count often inaccurate (too high or too low)  
+❌ "hook" guidance unclear (what makes a good hook?)  
+❌ Content structure validation not enforced  
+
+**Real-World Performance Issues:**
+- Generated ideas sometimes too similar within cluster
+- Outlines don't always respect structure types (e.g., "review" vs "guide")
+- covered_keywords field sometimes empty or incorrect
+- cluster_hub vs supporting ideas distinction unclear
+
+---
+
+### 3. Content Generation Prompt
+
+**Function:** `generate_content`  
+**File:** `backend/igny8_core/ai/functions/generate_content.py`  
+**Prompt Key:** `'content_generation'`
+
+#### Current Prompt Structure
+
+**Approach:** Editorial content strategist
+
+**Key Instructions:**
+- Output: JSON {title, content (HTML)}
+- Introduction: 1 italic hook (30-40 words) + 2 paragraphs (50-60 words each), no headings
+- H2 sections: 5-8 total, 250-300 words each
+- Section format: 2 narrative paragraphs → list/table → optional closing paragraph → 2-3 subsections
+- Vary list/table types
+- Never start section with list/table
+- Tone: professional, no passive voice, no generic intros
+- Keyword usage: natural in title, intro, headings
+
+**Strengths:**
+✅ Detailed structure guidance  
+✅ Strong tone/style rules  
+✅ HTML output format  
+✅ Keyword integration guidance  
+
+**Issues:**
+❌ **Word count not mentioned in prompt** - critical flaw  
+❌ No guidance on 500 vs 1000 vs 1500 word versions  
+❌ Hook word count (30-40) + paragraph counts (50-60 × 2) don't scale proportionally  
+❌ Section word count (250-300) doesn't adapt to total target  
+❌ No example output  
+❌ Content structure (article vs guide vs review) not clearly differentiated  
+❌ Table column guidance missing (what columns? how many?)  
+
+**Real-World Performance Issues:**
+- **Output length wildly inconsistent** (generates 800 words when asked for 1500)
+- Introductions sometimes have headings despite instructions
+- Lists appear at start of sections
+- Table structure unclear (random columns)
+- Doesn't adapt content density to word count
+
+---
+
+### 4. Image Prompt Extraction
+
+**Function:** `generate_image_prompts`  
+**File:** `backend/igny8_core/ai/functions/generate_image_prompts.py`  
+**Prompt Key:** `'image_prompt_extraction'`
+
+#### Current Prompt Structure
+
+**Approach:** Extract visual descriptions from article
+
+**Key Instructions:**
+- Input: article title + content
+- Output: JSON {featured_prompt, in_article_prompts[]}
+- Extract featured image (main topic)
+- Extract up to {max_images} in-article images
+- Each prompt detailed for image generation (visual elements, style, mood, composition)
+
+**Strengths:**
+✅ Clear structure  
+✅ Separates featured vs in-article  
+✅ Emphasizes detail in descriptions  
+
+**Issues:**
+❌ No guidance on what makes a good image prompt  
+❌ No style/mood specifications  
+❌ Doesn't specify where in article to place images  
+❌ No examples  
+❌ "Detailed enough" is subjective  
+
+**Real-World Performance Issues:**
+- Prompts sometimes too generic ("Image of a person using a laptop")
+- No context from article content (extracts irrelevant visuals)
+- Featured image prompt sometimes identical to in-article prompt
+- No guidance on image diversity (all similar)
+
+---
+
+### 5. Image Generation Template
+
+**Prompt Key:** `'image_prompt_template'`
+
+#### Current Template
+
+**Approach:** Template-based prompt assembly
+
+**Format:**
+```
+Create a high-quality {image_type} image... "{post_title}"... {image_prompt}...
+Focus on realistic, well-composed scene... lifestyle/editorial web content...
+Avoid text, watermarks, logos... **not blurry.**
+```
+
+**Issues:**
+❌ {image_type} not always populated  
+❌ "high-quality" and "not blurry" redundant/unclear  
+❌ No style guidance (photographic, illustration, 3D, etc.)  
+❌ No aspect ratio specification  
+
+---
+
+## Required Improvements
+
+### A. Clustering Prompt Redesign
+
+#### Goals
+- Reduce prompt length by 30-40%
+- Add 2-3 concrete examples
+- Enforce consistent cluster count (5-15 clusters ideal)
+- Standardize cluster naming (title case, descriptive)
+- Limit description to 20-30 words
+
+#### Proposed Structure
+
+**Section 1: Role & Task** (50 tokens)
+- Clear, concise role definition
+- Task: group keywords into intent-driven clusters
+
+**Section 2: Output Format with Example** (100 tokens)
+- JSON structure
+- Show 1 complete example cluster
+- Specify exact field requirements
+
+**Section 3: Clustering Rules** (150 tokens)
+- List 5-7 key rules (bullet format)
+- Keyword-first approach
+- Intent dimensions (brief)
+- Quality thresholds (3-10 keywords per cluster)
+- No duplicates
+
+**Section 4: Quality Checklist** (50 tokens)
+- Checklist of 4-5 validation points
+- Model self-validates before output
+
+**Total:** ~350 tokens (vs current ~420)
+
+#### Example Output Format to Include
+
+```json
+{
+  "clusters": [
+    {
+      "name": "Organic Bedding Benefits",
+      "description": "Health, eco-friendly, and comfort aspects of organic cotton bedding materials",
+      "keywords": ["organic sheets", "eco-friendly bedding", "chemical-free cotton", "hypoallergenic sheets", "sustainable bedding"]
+    }
+  ]
+}
+```
+
+---
+
+### B. Idea Generation Prompt Redesign
+
+#### Goals
+- Simplify outline structure (less prescriptive)
+- Add examples of cluster_hub vs supporting ideas
+- Better covered_keywords extraction
+- Adaptive word count estimation
+- Content structure differentiation
+
+#### Proposed Structure
+
+**Section 1: Role & Objective** (40 tokens)
+- SEO content strategist
+- Task: generate content ideas from clusters
+
+**Section 2: Output Format with Examples** (150 tokens)
+- Show 1 cluster_hub example
+- Show 1 supporting idea example
+- Highlight key differences
+
+**Section 3: Idea Generation Rules** (100 tokens)
+- 1 cluster_hub (comprehensive, authoritative)
+- 2-4 supporting ideas (specific angles)
+- Word count: 1500-2200 for hubs, 1000-1500 for supporting
+- covered_keywords: extract from cluster keywords
+
+**Section 4: Outline Guidance** (100 tokens)
+- Simplified: Intro + 5-8 sections + Conclusion
+- Section types by content_structure:
+  - article: narrative + data
+  - guide: step-by-step + tips
+  - review: pros/cons + comparison
+  - listicle: numbered + categories
+  - comparison: side-by-side + verdict
+
+**Total:** ~390 tokens (vs current ~610)
+
+---
+
+### C. Content Generation Prompt Redesign
+
+**Most Critical Improvement:** Word Count Adherence
+
+#### Goals
+- **Primary:** Generate exact word count (±5% tolerance)
+- Scale structure proportionally to word count
+- Differentiate content structures clearly
+- Improve HTML quality and consistency
+- Better keyword integration
+
+#### Proposed Adaptive Word Count System
+
+**Word Count Targets:**
+- 500 words: Short-form (5 sections × 80 words + intro/outro 60 words)
+- 1000 words: Standard (6 sections × 140 words + intro/outro 120 words)
+- 1500 words: Long-form (7 sections × 180 words + intro/outro 180 words)
+
+**Prompt Variable Replacement:**
+
+Before sending to AI, calculate:
+- `{TARGET_WORD_COUNT}` - from task.word_count
+- `{INTRO_WORDS}` - 60 / 120 / 180 based on target
+- `{SECTION_COUNT}` - 5 / 6 / 7 based on target
+- `{SECTION_WORDS}` - 80 / 140 / 180 based on target
+- `{HOOK_WORDS}` - 25 / 35 / 45 based on target
+
+#### Proposed Structure
+
+**Section 1: Role & Objective** (30 tokens)
+```
+You are an editorial content writer. Generate a {TARGET_WORD_COUNT}-word article...
+```
+
+**Section 2: Word Count Requirements** (80 tokens)
+```
+CRITICAL: The content must be exactly {TARGET_WORD_COUNT} words (±5% tolerance).
+
+Structure breakdown:
+- Introduction: {INTRO_WORDS} words total
+  - Hook (italic): {HOOK_WORDS} words
+  - Paragraphs: 2 × ~{INTRO_WORDS/2} words each
+- Main Sections: {SECTION_COUNT} H2 sections
+  - Each section: {SECTION_WORDS} words
+- Conclusion: 60 words
+
+Word count validation: Count words in final output and adjust if needed.
+```
+
+**Section 3: Content Flow & HTML** (120 tokens)
+- Detailed structure per section
+- HTML tag usage (<p>, <h2>, <h3>, <ul>, <ol>, <table>)
+- Formatting rules
+
+**Section 4: Style & Quality** (80 tokens)
+- Tone guidance
+- Keyword usage
+- Avoid generic phrases
+- Examples of good vs bad openings
+
+**Section 5: Content Structure Types** (90 tokens)
+- article: {structure description}
+- guide: {structure description}
+- review: {structure description}
+- comparison: {structure description}
+- listicle: {structure description}
+- cluster_hub: {structure description}
+
+**Section 6: Output Format with Example** (100 tokens)
+- JSON structure
+- Show abbreviated example with proper HTML
+
+**Total:** ~500 tokens (vs current ~550, but much more precise)
+
+---
+
+### D. Image Prompt Improvements
+
+#### Goals
+- Generate visually diverse prompts
+- Better context from article content
+- Specify image placement guidelines
+- Improve prompt detail and clarity
+
+#### Proposed Extraction Prompt Structure
+
+**Section 1: Task & Context** (50 tokens)
+```
+Extract image prompts from this article for visual content placement.
+
+Article: {title}
+Content: {content}
+Required: 1 featured + {max_images} in-article images
+```
+
+**Section 2: Image Types & Guidelines** (100 tokens)
+```
+Featured Image:
+- Hero visual representing article's main theme
+- Broad, engaging, high-quality
+- Should work at large sizes (1200×630+)
+
+In-Article Images (place strategically):
+1. After introduction
+2. Mid-article (before major H2 sections)
+3. Supporting specific concepts or examples
+4. Before conclusion
+
+Each prompt must describe:
+- Subject & composition
+- Visual style (photographic, minimal, editorial)
+- Mood & lighting
+- Color palette suggestions
+- Avoid: text, logos, faces (unless relevant)
+```
+
+**Section 3: Prompt Quality Rules** (80 tokens)
+- Be specific and descriptive (not generic)
+- Include scene details, angles, perspective
+- Specify lighting, time of day if relevant
+- Mention style references
+- Ensure diversity across all images
+- No duplicate concepts
+
+**Section 4: Output Format** (50 tokens)
+- JSON structure
+- Show example with good vs bad prompts
+
+#### Proposed Template Prompt Improvement
+
+Replace current template with:
+
+```
+A {style} photograph for "{post_title}". {image_prompt}. 
+Composition: {composition_hint}. Lighting: {lighting_hint}. 
+Mood: {mood}. Style: clean, modern, editorial web content. 
+No text, watermarks, or logos.
+```
+
+Where:
+- {style} - photographic, minimalist, lifestyle, etc.
+- {composition_hint} - center-framed, rule-of-thirds, wide-angle, etc.
+- {lighting_hint} - natural daylight, soft indoor, dramatic, etc.
+- {mood} - professional, warm, energetic, calm, etc.
+
+---
+
+## Implementation Plan
+
+### Phase 1: Clustering Prompt (Week 1)
+
+**Tasks:**
+1. ✅ Draft new clustering prompt with examples
+2. ✅ Test with sample keyword sets (20, 50, 100 keywords)
+3. ✅ Compare outputs: old vs new
+4. ✅ Validate cluster quality (manual review)
+5. ✅ Update `PromptRegistry.DEFAULT_PROMPTS['clustering']`
+6. ✅ Deploy and monitor
+
+**Success Criteria:**
+- Consistent cluster count (5-15)
+- No single-keyword clusters
+- Clear, descriptive names
+- Concise descriptions (20-30 words)
+- 95%+ of keywords clustered
+
+---
+
+### Phase 2: Idea Generation Prompt (Week 1-2)
+
+**Tasks:**
+1. ✅ Draft new ideas prompt with examples
+2. ✅ Test with 5-10 clusters
+3. ✅ Validate cluster_hub vs supporting idea distinction
+4. ✅ Check covered_keywords accuracy
+5. ✅ Verify content_structure alignment
+6. ✅ Update `PromptRegistry.DEFAULT_PROMPTS['ideas']`
+7. ✅ Deploy and monitor
+
+**Success Criteria:**
+- Clear distinction between hub and supporting ideas
+- Accurate covered_keywords extraction
+- Appropriate word count estimates
+- Outlines match content_structure type
+- No duplicate ideas within cluster
+
+---
+
+### Phase 3: Content Generation Prompt (Week 2)
+
+**Tasks:**
+1. ✅ Draft new content prompt with word count logic
+2. ✅ Implement dynamic variable replacement in `build_prompt()`
+3. ✅ Test with 500, 1000, 1500 word targets
+4. ✅ Validate actual word counts (automated counting)
+5. ✅ Test all content_structure types
+6. ✅ Verify HTML quality and consistency
+7. ✅ Update `PromptRegistry.DEFAULT_PROMPTS['content_generation']`
+8. ✅ Deploy and monitor
+
+**Code Change Required:**
+
+**File:** `backend/igny8_core/ai/functions/generate_content.py`
+
+**Method:** `build_prompt()`
+
+**Add word count calculation:**
+
+```python
+def build_prompt(self, data: Any, account=None) -> str:
+    task = data if not isinstance(data, list) else data[0]
+    
+    # Calculate adaptive word count parameters
+    target_words = task.word_count or 1000
+    
+    if target_words <= 600:
+        intro_words = 60
+        section_count = 5
+        section_words = 80
+        hook_words = 25
+    elif target_words <= 1200:
+        intro_words = 120
+        section_count = 6
+        section_words = 140
+        hook_words = 35
+    else:
+        intro_words = 180
+        section_count = 7
+        section_words = 180
+        hook_words = 45
+    
+    # Get prompt and replace variables
+    prompt = PromptRegistry.get_prompt(
+        function_name='generate_content',
+        account=account,
+        task=task,
+        context={
+            'TARGET_WORD_COUNT': target_words,
+            'INTRO_WORDS': intro_words,
+            'SECTION_COUNT': section_count,
+            'SECTION_WORDS': section_words,
+            'HOOK_WORDS': hook_words,
+            # ... existing context
+        }
+    )
+    
+    return prompt
+```
+
+**Success Criteria:**
+- 95%+ of generated content within ±5% of target word count
+- HTML structure consistent
+- Content structure types clearly differentiated
+- Keyword integration natural
+- No sections starting with lists
+
+---
+
+### Phase 4: Image Prompt Improvements (Week 2-3)
+
+**Tasks:**
+1. ✅ Draft new extraction prompt with placement guidelines
+2. ✅ Draft new template prompt with style variables
+3. ✅ Test with 10 sample articles
+4. ✅ Validate image diversity and relevance
+5. ✅ Update both prompts in registry
+6. ✅ Update `GenerateImagePromptsFunction` to use new template
+7. ✅ Deploy and monitor
+
+**Success Criteria:**
+- No duplicate image concepts in same article
+- Prompts are specific and detailed
+- Featured image distinct from in-article images
+- Image placement logically distributed
+- Generated images relevant to content
+
+---
+
+## Prompt Versioning & Testing
+
+### Version Control
+
+**Recommendation:** Store prompt versions in database for A/B testing
+
+**Schema:**
+
+```python
+class AIPromptVersion(models.Model):
+    prompt_type = CharField(choices=PROMPT_TYPE_CHOICES)
+    version = IntegerField()
+    prompt_value = TextField()
+    is_active = BooleanField(default=False)
+    created_at = DateTimeField(auto_now_add=True)
+    performance_metrics = JSONField(default=dict)  # Track success rates
+```
+
+**Process:**
+1. Test new prompt version alongside current
+2. Compare outputs on same inputs
+3. Measure quality metrics (manual + automated)
+4. Gradually roll out if better
+5. Keep old version as fallback
+
+---
+
+### Automated Quality Metrics
+
+**Implement automated checks:**
+
+| Metric | Check | Threshold |
+|--------|-------|-----------|
+| Word Count Accuracy | `abs(actual - target) / target` | < 0.05 (±5%) |
+| HTML Validity | Parse with BeautifulSoup | 100% valid |
+| Keyword Presence | Count keyword mentions | ≥ 3 for primary |
+| Structure Compliance | Check H2/H3 hierarchy | Valid structure |
+| Cluster Count | Number of clusters | 5-15 |
+| Cluster Size | Keywords per cluster | 3-10 |
+| No Duplicates | Keyword appears once | 100% unique |
+
+**Log results:**
+- Track per prompt version
+- Identify patterns in failures
+- Use for prompt iteration
+
+---
+
+## Model Selection & Optimization
+
+### Current Models
+
+**Location:** `backend/igny8_core/ai/settings.py`
+
+**Default Models per Function:**
+- Clustering: GPT-4 (expensive but accurate)
+- Ideas: GPT-4 (creative)
+- Content: GPT-4 (quality)
+- Image Prompts: GPT-3.5-turbo (simpler task)
+- Images: DALL-E 3 / Runware
+
+### Optimization Opportunities
+
+**Cost vs Quality Tradeoffs:**
+
+| Function | Current | Alternative | Cost Savings | Quality Impact |
+|----------|---------|-------------|--------------|----------------|
+| Clustering | GPT-4 | GPT-4-turbo | 50% | Minimal |
+| Ideas | GPT-4 | GPT-4-turbo | 50% | Minimal |
+| Content | GPT-4 | GPT-4-turbo | 50% | Test required |
+| Image Prompts | GPT-3.5 | Keep | - | - |
+
+**Recommendation:** Test GPT-4-turbo for all text generation tasks
+- Faster response time
+- 50% cost reduction
+- Similar quality for structured outputs
+
+---
+
+## Success Metrics
+
+- ✅ Word count accuracy: 95%+ within ±5%
+- ✅ Clustering quality: No single-keyword clusters
+- ✅ Idea generation: Clear hub vs supporting distinction
+- ✅ HTML validity: 100%
+- ✅ Keyword integration: Natural, not stuffed
+- ✅ Image prompt diversity: No duplicates
+- ✅ User satisfaction: Fewer manual edits needed
+- ✅ Processing time: <10s for 1000-word article
+- ✅ Credit cost: 30% reduction with model optimization
+
+---
+
+## Related Files Reference
+
+### Backend
+- `backend/igny8_core/ai/prompts.py` - Prompt registry and defaults
+- `backend/igny8_core/ai/functions/auto_cluster.py` - Clustering function
+- `backend/igny8_core/ai/functions/generate_ideas.py` - Ideas function
+- `backend/igny8_core/ai/functions/generate_content.py` - Content function
+- `backend/igny8_core/ai/functions/generate_image_prompts.py` - Image prompts
+- `backend/igny8_core/ai/settings.py` - Model configuration
+- `backend/igny8_core/modules/system/models.py` - AIPrompt model
+
+### Testing
+- Create test suite: `backend/igny8_core/ai/tests/test_prompts.py`
+- Test fixtures with sample inputs
+- Automated quality validation
+- Performance benchmarks
+
+---
+
+## Notes
+
+- All prompt changes should be tested on real data first
+- Keep old prompts in version history for rollback
+- Monitor user feedback on content quality
+- Consider user-customizable prompt templates (advanced feature)
+- Document prompt engineering best practices for team
+- SAG clustering prompt (mentioned in original doc) to be handled separately as specialized architecture
--- a/docs/PRE-LAUNCH/ITEM-4-PAGE-FLOW-UX.md
+++ b/docs/PRE-LAUNCH/ITEM-4-PAGE-FLOW-UX.md
@@ -0,0 +1,745 @@
+# Item 4: Page Flow and Workflow UX Improvements
+
+**Priority:** High  
+**Target:** Production Launch  
+**Last Updated:** December 11, 2025
+
+---
+
+## Overview
+
+Improve overall navigation, page structure, workflow clarity, and helper systems across all main user-facing areas including Setup, Workflow (Planner/Writer), Account, and Settings. This encompasses page flow standardization, helper notifications, tooltips, metrics panels, and notification systems.
+
+---
+
+## Current Implementation Analysis
+
+### Main Menu Groups
+
+**Location:** `frontend/src/layout/AppLayout.tsx` and navigation components
+
+**Current Groups:**
+1. **Setup** - Sites, Sectors, Integrations setup
+2. **Workflow** - Planner (Keywords, Clusters, Ideas) and Writer (Tasks, Content, Images)
+3. **Account** - Billing, Team, Profile
+4. **Settings** - System settings, prompts, preferences
+
+**Issues:**
+- Inconsistent page header patterns across groups
+- Some pages missing breadcrumbs or context
+- Linear workflows (Planner → Writer) not clearly guided
+- Cross-navigation between related pages unclear
+
+---
+
+### Page Header Component
+
+**Location:** `frontend/src/components/common/PageHeader.tsx`
+
+**Current Features:**
+- Page title
+- Last updated timestamp
+- Site/Sector selector (can be hidden)
+- Optional refresh button
+- Optional badge
+- Optional navigation tabs
+
+**Strengths:**
+✅ Standardized across modules  
+✅ Site/sector context management  
+✅ Auto-loads sectors when site changes  
+
+**Missing:**
+❌ No breadcrumbs for deeper navigation  
+❌ No contextual help link  
+❌ No step indicators for workflows  
+❌ No quick action buttons section  
+
+---
+
+### Module Navigation Tabs
+
+**Location:** `frontend/src/components/navigation/ModuleNavigationTabs.tsx`
+
+**Current Usage:**
+- Planner pages: Keywords | Clusters | Ideas | Mapping
+- Writer pages: Tasks | Content | Images
+
+**Strengths:**
+✅ Consistent tab design  
+✅ Active tab highlighting  
+✅ Responsive layout  
+
+**Missing:**
+❌ No tab progress indicators  
+❌ No disabled state for incomplete prerequisites  
+❌ No tooltips explaining each tab  
+
+---
+
+### Helper Systems
+
+**Current State:**
+- No systematic helper notifications
+- No onboarding tooltips
+- No inline guidance text
+- No contextual help system
+
+**What's Needed:**
+- Welcome messages for first-time page visits
+- Tooltips for icons and complex actions
+- Inline help text under form fields
+- Step-by-step workflow banners
+- Contextual "Learn more" links
+
+---
+
+### Metrics Display
+
+**Current Locations:**
+- Dashboard: Overview metrics
+- Individual pages: Table counts, filters
+- Footer: Module-specific metrics (some pages only)
+
+**Component:** `frontend/src/components/dashboard/ModuleMetricsFooter.tsx`
+
+**Issues:**
+- Inconsistent placement (some pages have footer metrics, some don't)
+- No collapsible panel option
+- Metrics not updated in real-time
+- No metric explanations (tooltips)
+
+---
+
+## Required Improvements
+
+### A. Standardize Page Structure
+
+#### Universal Page Template
+
+All workflow pages should follow this structure:
+
+```tsx
+<div className="page-container">
+  {/* 1. Page Header */}
+  <PageHeader 
+    title="Page Title"
+    badge={badge}
+    navigation={<ModuleNavigationTabs tabs={tabs} />}
+  />
+  
+  {/* 2. Step Banner (if workflow page) */}
+  {isWorkflowPage && <StepBanner currentStep={2} totalSteps={5} />}
+  
+  {/* 3. Helper Notification (first visit or contextual) */}
+  {showHelper && <HelperNotification message="..." />}
+  
+  {/* 4. Page Actions Bar */}
+  <PageActionsBar 
+    primaryAction={primaryAction}
+    secondaryActions={secondaryActions}
+    filters={filters}
+  />
+  
+  {/* 5. Main Content */}
+  <MainContent>
+    {/* Tables, forms, cards, etc. */}
+  </MainContent>
+  
+  {/* 6. Bottom Metrics Panel (collapsible) */}
+  <MetricsPanel metrics={metrics} collapsible={true} />
+</div>
+```
+
+---
+
+### B. New Components to Create
+
+#### 1. StepBanner Component
+
+**File:** `frontend/src/components/workflow/StepBanner.tsx` (NEW)
+
+**Purpose:** Show current step in multi-step workflows
+
+**Props:**
+```typescript
+interface StepBannerProps {
+  currentStep: number;
+  totalSteps: number;
+  steps: Array<{
+    label: string;
+    href: string;
+    completed: boolean;
+  }>;
+  onStepClick?: (stepIndex: number) => void;
+}
+```
+
+**UI Design:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Step 2 of 5: Organize into Clusters
+
+1. Extract Keywords ✓ → 2. Cluster Keywords ● → 3. Generate Ideas → 4. Create Content → 5. Publish
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**States:**
+- ✓ Completed (green, clickable)
+- ● Current (blue, active)
+- Pending (gray, disabled or clickable)
+
+**Usage:**
+```tsx
+<StepBanner 
+  currentStep={2}
+  totalSteps={5}
+  steps={[
+    { label: 'Extract Keywords', href: '/planner/keywords', completed: true },
+    { label: 'Cluster Keywords', href: '/planner/clusters', completed: false },
+    { label: 'Generate Ideas', href: '/planner/ideas', completed: false },
+    { label: 'Create Content', href: '/writer/tasks', completed: false },
+    { label: 'Publish', href: '/writer/content', completed: false },
+  ]}
+/>
+```
+
+---
+
+#### 2. HelperNotification Component
+
+**File:** `frontend/src/components/helper/HelperNotification.tsx` (NEW)
+
+**Purpose:** Display contextual guidance and tips
+
+**Types:**
+- **Welcome**: First-time page visit
+- **Info**: General information
+- **Tip**: Best practice suggestion
+- **Warning**: Potential issue
+- **Success**: Achievement/milestone
+
+**Props:**
+```typescript
+interface HelperNotificationProps {
+  type: 'welcome' | 'info' | 'tip' | 'warning' | 'success';
+  title: string;
+  message: string;
+  actions?: Array<{
+    label: string;
+    href?: string;
+    onClick?: () => void;
+  }>;
+  dismissible?: boolean;
+  onDismiss?: () => void;
+}
+```
+
+**UI Design:**
+```
+┌─────────────────────────────────────────────────┐
+│ 💡 Welcome to Keywords                          │
+│                                                 │
+│ This is where you extract and manage SEO        │
+│ keywords. Start by adding keywords manually or  │
+│ importing from a CSV file.                      │
+│                                                 │
+│ [Import CSV] [Learn More] [Got it] [×]         │
+└─────────────────────────────────────────────────┘
+```
+
+**Persistence:**
+- Store dismissed state in localStorage per page
+- Key: `helper_dismissed_{page_slug}`
+- Option to show "Show hints again" in settings
+
+---
+
+#### 3. Tooltip Component Enhancement
+
+**File:** `frontend/src/components/ui/Tooltip.tsx` (enhance existing)
+
+**Add:**
+- Keyboard accessibility (ESC to close, tab navigation)
+- Delay before show (300ms hover)
+- Max width constraints
+- Arrow positioning
+- Rich content support (not just text)
+
+**Usage Examples:**
+
+```tsx
+{/* Simple text tooltip */}
+<Tooltip content="Click to cluster all keywords">
+  <button>Cluster</button>
+</Tooltip>
+
+{/* Rich content tooltip */}
+<Tooltip content={
+  <div>
+    <strong>Clustering</strong>
+    <p>Groups keywords by semantic similarity</p>
+    <a href="/help/clustering">Learn more →</a>
+  </div>
+}>
+  <InfoIcon />
+</Tooltip>
+```
+
+---
+
+#### 4. InlineGuidance Component
+
+**File:** `frontend/src/components/helper/InlineGuidance.tsx` (NEW)
+
+**Purpose:** Small help text under form fields
+
+**Props:**
+```typescript
+interface InlineGuidanceProps {
+  text: string;
+  type?: 'info' | 'warning' | 'error';
+  icon?: ReactNode;
+}
+```
+
+**UI Design:**
+```
+[Input Field: Enter keyword]
+ℹ️ Use lowercase, no special characters. Separate multiple keywords with commas.
+```
+
+**Usage:**
+```tsx
+<FormField label="Keywords">
+  <input type="text" placeholder="Enter keyword" />
+  <InlineGuidance 
+    text="Use lowercase, no special characters. Separate multiple keywords with commas."
+  />
+</FormField>
+```
+
+---
+
+#### 5. Enhanced MetricsPanel Component
+
+**File:** `frontend/src/components/dashboard/ModuleMetricsPanel.tsx` (NEW)
+
+**Improvements over current MetricsFooter:**
+- Collapsible/expandable
+- Fixed to bottom or inline at page bottom
+- Real-time updates
+- Tooltips explaining each metric
+- Click to filter/drill-down
+- Export metrics option
+
+**Props:**
+```typescript
+interface MetricsPanelProps {
+  title: string;
+  metrics: Array<{
+    label: string;
+    value: string | number;
+    subtitle?: string;
+    icon?: ReactNode;
+    color?: string;
+    tooltip?: string;
+    onClick?: () => void;
+  }>;
+  collapsible?: boolean;
+  defaultCollapsed?: boolean;
+  position?: 'fixed' | 'relative';
+}
+```
+
+**UI Design (Expanded):**
+```
+┌─────────────────────────────────────────────────────────┐
+│ ▼ Keyword Metrics                          [Collapse] × │
+├─────────────────────────────────────────────────────────┤
+│ Total: 450   │ New: 120   │ Mapped: 330   │ Vol: 125K  │
+│ ℹ️ All saved │ ℹ️ Unmapped │ ℹ️ In cluster │ ℹ️ Search  │
+│              │             │               │   volume   │
+└─────────────────────────────────────────────────────────┘
+```
+
+**UI Design (Collapsed):**
+```
+▶ Keyword Metrics: 450 total, 120 new, 330 mapped
+```
+
+---
+
+### C. Navigation Improvements
+
+#### 1. Add Breadcrumbs
+
+**Component:** `frontend/src/components/navigation/Breadcrumbs.tsx` (NEW)
+
+**Usage:**
+```tsx
+<Breadcrumbs 
+  items={[
+    { label: 'Setup', href: '/setup' },
+    { label: 'Sites', href: '/setup/sites' },
+    { label: 'Site Settings' }, // Current page (no href)
+  ]}
+/>
+```
+
+**Display:**
+```
+Home > Setup > Sites > Site Settings
+```
+
+**Rules:**
+- Show for pages 3+ levels deep
+- Current page not clickable
+- Auto-hide on mobile if > 3 items
+
+---
+
+#### 2. Cross-Navigation Links
+
+**Add "Next Step" buttons between related pages:**
+
+**Examples:**
+
+| Current Page | Next Step Button | Action |
+|--------------|------------------|---------|
+| Keywords | "Cluster Keywords →" | Navigate to Clusters page |
+| Clusters | "Generate Ideas →" | Navigate to Ideas page |
+| Ideas | "Create Tasks →" | Convert ideas to tasks, navigate to Tasks |
+| Tasks | "Generate Content →" | Trigger content generation |
+| Content | "Generate Images →" | Navigate to Images page |
+
+**Implementation:**
+```tsx
+<PageActionsBar
+  primaryAction={{
+    label: 'Cluster Keywords',
+    icon: <ArrowRightIcon />,
+    onClick: () => navigate('/planner/clusters'),
+    variant: 'primary'
+  }}
+/>
+```
+
+---
+
+#### 3. Workflow Progress Indicator (Global)
+
+**Location:** Header or sidebar
+
+**Display current workflow stage:**
+
+```
+Planner Workflow: Step 2/3
+├─ Keywords ✓
+├─ Clusters ● (in progress)
+└─ Ideas
+
+Writer Workflow: Not started
+```
+
+**Click to navigate to any completed or current step**
+
+---
+
+### D. Settings Reorganization
+
+#### Current Problems
+- Settings scattered across multiple locations
+- Inconsistent categories
+- Hard to find specific settings
+
+#### Proposed Structure
+
+**New Layout:** `frontend/src/pages/Settings/`
+
+```
+Settings/
+├── index.tsx (Settings hub with cards)
+├── General.tsx
+├── Publishing.tsx
+├── Pagination.tsx
+├── Branding.tsx
+├── WorkflowDefaults.tsx
+├── Integrations.tsx
+├── Notifications.tsx
+├── Account.tsx
+└── Billing.tsx (redirect to /billing)
+```
+
+**Settings Categories:**
+
+| Category | Subcategories | What It Contains |
+|----------|---------------|------------------|
+| **General** | Account basics | Display name, timezone, language, date format |
+| **Publishing** | WordPress settings | Connection, publishing defaults, SEO rules, auto-publish options |
+| **Pagination** | List controls | Items per page for each module (keywords, clusters, ideas, etc.) |
+| **Branding** | Appearance | Logo, colors, custom CSS (if applicable) |
+| **Workflow Defaults** | AI settings | Default word count, tone, structure, author profile |
+| **Integrations** | External services | API keys, OAuth connections, webhooks |
+| **Notifications** | Alert preferences | Email alerts, in-app notifications, notification types |
+| **Account & Billing** | Subscription | Plan details, usage, credits, invoices, team members |
+
+**Settings Hub (Landing Page):**
+
+```tsx
+<SettingsHub>
+  <SettingsCard 
+    icon={<GeneralIcon />}
+    title="General"
+    description="Basic account settings and preferences"
+    href="/settings/general"
+  />
+  <SettingsCard 
+    icon={<PublishIcon />}
+    title="Publishing"
+    description="WordPress connection and publishing rules"
+    href="/settings/publishing"
+  />
+  {/* ... more cards */}
+</SettingsHub>
+```
+
+---
+
+### E. Notification System
+
+#### Notification Types
+
+| Type | Use Case | Display | Action |
+|------|----------|---------|--------|
+| **Progress** | Task started, queued, processing | Blue info icon | View progress modal |
+| **Success** | Task completed, export success | Green check icon | View result |
+| **Failure** | API error, validation failed | Red error icon | View error details, retry |
+| **Action Required** | Missing settings, incomplete setup | Orange warning icon | Navigate to fix |
+
+#### Notification Dropdown
+
+**Location:** Header, bell icon with badge count
+
+**Features:**
+- List notifications chronologically
+- Read/unread states
+- Mark all as read
+- Filter by type
+- Clear all button
+- Links to relevant pages
+
+**Example Notification:**
+```
+┌─────────────────────────────────────────────┐
+│ 🔵 Content Generation Started               │
+│ "Best SEO Tools 2024" - 2 minutes ago      │
+│ [View Progress]                             │
+├─────────────────────────────────────────────┤
+│ ✅ Clustering Completed                      │
+│ 45 keywords → 8 clusters - 10 min ago      │
+│ [View Clusters]                             │
+├─────────────────────────────────────────────┤
+│ ❌ Image Generation Failed                   │
+│ Insufficient credits - 1 hour ago          │
+│ [Purchase Credits] [Dismiss]               │
+└─────────────────────────────────────────────┘
+```
+
+#### Implementation
+
+**Backend:**
+- Create `Notification` model with account FK
+- API endpoints: list, mark read, clear
+- Emit notifications on key events
+
+**Frontend:**
+- `useNotifications()` hook
+- `NotificationDropdown` component
+- Auto-refresh every 30 seconds
+- WebSocket support (future enhancement)
+
+---
+
+### F. Header Metrics Enhancement
+
+**Current:** Basic stats in dashboard
+
+**Improved:** Always-visible header metrics
+
+**Location:** Right side of header (next to user menu)
+
+**Display:**
+```
+[Icon] 3 In Progress  |  [Icon] 5 Completed  |  [Icon] 2,450 Credits  |  [Bell] 7
+```
+
+**Click to expand:**
+- In Progress: Show list of running tasks
+- Completed: Recent completions
+- Credits: Usage breakdown, purchase link
+- Bell: Notification dropdown
+
+---
+
+## Page-Specific Improvements
+
+### Planner Pages
+
+#### Keywords Page
+
+**Add:**
+- ✅ Helper: "Import keywords or add manually to start"
+- ✅ Tooltip on "Cluster" button: "Group keywords by semantic similarity"
+- ✅ Inline guidance on import: "CSV format: keyword, volume, difficulty"
+- ✅ Next step button: "Cluster Keywords →"
+- ✅ Metrics panel: Total, New, Mapped, Avg Volume
+
+#### Clusters Page
+
+**Add:**
+- ✅ Helper: "Clusters organize keywords into topic groups"
+- ✅ Step banner: Step 2/3 in Planner workflow
+- ✅ Tooltip on cluster cards: Show keyword count, volume
+- ✅ Next step: "Generate Ideas →"
+- ✅ Metrics panel: Clusters, Avg size, Total volume
+
+#### Ideas Page
+
+**Add:**
+- ✅ Helper: "Content ideas are generated from your clusters"
+- ✅ Step banner: Step 3/3 in Planner workflow
+- ✅ Content structure badge with tooltip
+- ✅ Next step: "Create Tasks →" (converts to tasks)
+- ✅ Metrics panel: Ideas, Cluster hubs, Word count estimates
+
+---
+
+### Writer Pages
+
+#### Tasks Page
+
+**Add:**
+- ✅ Helper: "Tasks are content generation jobs queued for AI"
+- ✅ Step banner: Step 1/3 in Writer workflow
+- ✅ Status badges with tooltips
+- ✅ Next step: "Generate Content →"
+- ✅ Metrics panel: Total tasks, Queued, Completed, Total words
+
+#### Content Page
+
+**Add:**
+- ✅ Helper: "Review and edit AI-generated content before publishing"
+- ✅ Step banner: Step 2/3 in Writer workflow
+- ✅ Status badges (draft/review/published)
+- ✅ Next step: "Generate Images →"
+- ✅ Metrics panel: Total content, Drafts, Published, Total words
+
+#### Images Page
+
+**Add:**
+- ✅ Helper: "Generate images for your content from AI prompts"
+- ✅ Step banner: Step 3/3 in Writer workflow
+- ✅ Image preview on hover
+- ✅ Next step: "Publish to WordPress →"
+- ✅ Metrics panel: Total images, Generated, Published
+
+---
+
+### Automation Page
+
+**Add:**
+- ✅ Helper: "Automation runs the entire workflow automatically"
+- ✅ Stage progress cards with clear metrics
+- ✅ Pause/Resume/Cancel controls
+- ✅ Real-time stage updates
+- ✅ Estimated completion time
+- ✅ Credit consumption display
+
+---
+
+## Implementation Plan
+
+### Phase 1: New Components (Week 1)
+1. ✅ Create StepBanner component
+2. ✅ Create HelperNotification component
+3. ✅ Enhance Tooltip component
+4. ✅ Create InlineGuidance component
+5. ✅ Create MetricsPanel component
+
+### Phase 2: Navigation (Week 1-2)
+1. ✅ Create Breadcrumbs component
+2. ✅ Add cross-navigation buttons
+3. ✅ Implement workflow progress indicator
+4. ✅ Update ModuleNavigationTabs with tooltips
+
+### Phase 3: Settings Reorganization (Week 2)
+1. ✅ Create new Settings pages structure
+2. ✅ Migrate existing settings
+3. ✅ Create Settings hub landing page
+4. ✅ Add category cards
+
+### Phase 4: Notification System (Week 2-3)
+1. ✅ Create Notification model (backend)
+2. ✅ Create notification endpoints
+3. ✅ Create NotificationDropdown component
+4. ✅ Integrate with existing workflows
+5. ✅ Add bell icon with badge to header
+
+### Phase 5: Page Updates (Week 3)
+1. ✅ Update all Planner pages with new components
+2. ✅ Update all Writer pages with new components
+3. ✅ Update Automation page
+4. ✅ Add helpers, tooltips, metrics to each page
+
+---
+
+## Success Metrics
+
+- ✅ All workflow pages have step banners
+- ✅ All pages have helper notifications on first visit
+- ✅ All icons and actions have tooltips
+- ✅ All form fields have inline guidance
+- ✅ Settings are organized and easy to find
+- ✅ Users receive notifications for all key events
+- ✅ Cross-navigation reduces clicks to complete workflows
+- ✅ Metrics panels show real-time data
+- ✅ User feedback indicates clearer navigation
+
+---
+
+## Related Files Reference
+
+### Components (NEW)
+- `frontend/src/components/workflow/StepBanner.tsx`
+- `frontend/src/components/helper/HelperNotification.tsx`
+- `frontend/src/components/helper/InlineGuidance.tsx`
+- `frontend/src/components/navigation/Breadcrumbs.tsx`
+- `frontend/src/components/dashboard/MetricsPanel.tsx`
+- `frontend/src/components/notifications/NotificationDropdown.tsx`
+
+### Components (Enhance)
+- `frontend/src/components/common/PageHeader.tsx`
+- `frontend/src/components/navigation/ModuleNavigationTabs.tsx`
+- `frontend/src/components/ui/Tooltip.tsx`
+
+### Pages (Update)
+- All `frontend/src/pages/Planner/*.tsx`
+- All `frontend/src/pages/Writer/*.tsx`
+- `frontend/src/pages/Automation/*.tsx`
+- `frontend/src/pages/Settings/*.tsx` (reorganize)
+
+### Backend (NEW)
+- `backend/igny8_core/modules/system/models.py` - Add Notification model
+- `backend/igny8_core/modules/system/views.py` - Notification endpoints
+
+---
+
+## Notes
+
+- Helper notifications should be non-intrusive and dismissible
+- Tooltips should be brief (2-3 sentences max)
+- Metrics should update in real-time or near-real-time
+- Settings should be searchable (future enhancement)
+- Consider onboarding tour for new users (future phase)
+- All guidance text should be editable by admin (future enhancement)
--- a/docs/PRE-LAUNCH/ITEM-5-WORDPRESS-TEMPLATES.md
+++ b/docs/PRE-LAUNCH/ITEM-5-WORDPRESS-TEMPLATES.md
@@ -0,0 +1,736 @@
+# Item 5: WordPress Content Template Improvements and Redesign
+
+**Priority:** High  
+**Target:** Production Launch  
+**Last Updated:** December 11, 2025
+
+---
+
+## Overview
+
+Redesign WordPress content templates to optimize image placement, content structure, and cluster hub landing pages. Implement adaptive templates for different article lengths (500, 1000, 1500 words) with intelligent image reuse logic and proper HTML formatting.
+
+---
+
+## Current Implementation Analysis
+
+### Content Template System
+
+**Location:** `backend/igny8_core/modules/publisher/` and content generation
+
+**Current State:**
+- Content generated as HTML in `Content.content_html` field
+- Images generated separately with prompts
+- No formal template system for WordPress publishing
+- Image placement done during content generation, not during publishing
+
+**Issues:**
+- No consistent image placement strategy
+- No adaptation for article length
+- Image reuse logic not implemented
+- Cluster hub pages not differentiated from regular content
+
+---
+
+### Content HTML Structure
+
+**Generated by:** `backend/igny8_core/ai/functions/generate_content.py`
+
+**Current Format:**
+```html
+<p><em>Hook text...</em></p>
+<p>Introduction paragraph 1...</p>
+<p>Introduction paragraph 2...</p>
+
+<h2>Section Heading 1</h2>
+<p>Section content...</p>
+<ul>
+  <li>List item 1</li>
+  <li>List item 2</li>
+</ul>
+
+<h2>Section Heading 2</h2>
+<p>Section content...</p>
+<table>
+  <tr><th>Column 1</th><th>Column 2</th></tr>
+  <tr><td>Data 1</td><td>Data 2</td></tr>
+</table>
+
+<!-- More sections... -->
+```
+
+**Issues:**
+- No image tags in HTML (images added separately)
+- No placeholder markers for image insertion
+- Section lengths not adaptive to total word count
+- Table structures sometimes inconsistent
+
+---
+
+### Image System
+
+**Models:**
+- `ContentImage` - Stores image URL, prompt, type (featured/in-article), position
+- Linked to `Content` via foreign key
+
+**Current Image Generation:**
+1. Content generated with HTML
+2. Image prompts extracted from content
+3. Images generated from prompts
+4. Images stored in `ContentImage` table
+5. Publishing combines content HTML + image URLs
+
+**Issues:**
+- No clear insertion points in HTML
+- Image position field not always used correctly
+- Featured image vs in-article distinction unclear
+- No reuse logic when fewer images than placeholders
+
+---
+
+## Image Placement Strategy
+
+### Placement Rules by Article Length
+
+#### 500-Word Article
+**Structure:** Intro + 2 sections + Conclusion
+
+**Image Placement:**
+- Position 1: After introduction (before first H2)
+- Position 2: Mid-article (before second H2 or within)
+- Position 3: Before conclusion (optional, if 3 images available)
+
+**Total Images:** 2-3
+
+---
+
+#### 1000-Word Article
+**Structure:** Intro + 4-5 sections + Conclusion
+
+**Image Placement:**
+- Position 1: After introduction
+- Position 2: After section 2
+- Position 3: After section 3 or 4 (mid-article)
+- Position 4: Before conclusion
+- Position 5: Within longest section (optional)
+
+**Total Images:** 3-5
+
+---
+
+#### 1500-Word Article
+**Structure:** Intro + 6-8 sections + Conclusion
+
+**Image Placement:**
+- Position 1: After introduction
+- Position 2: After section 2
+- Position 3: Mid-article (after section 4)
+- Position 4: After section 5 or 6
+- Position 5: Before conclusion
+- Position 6-7: Within longer sections (optional)
+
+**Total Images:** 4-7
+
+---
+
+### Image Reuse Logic
+
+**Scenario:** Not enough images for all placement positions
+
+| Available Images | Reuse Strategy |
+|------------------|----------------|
+| 1 image | Use 3 times: after intro, mid-article, before conclusion |
+| 2 images | Alternate: Image 1 → Image 2 → Image 1 → Image 2 (repeat pattern) |
+| 3 images | Use each twice: distribute evenly across positions |
+| 4+ images | Use each once until exhausted, then reuse starting from first |
+
+**Implementation Logic:**
+
+```python
+def get_image_for_position(position: int, available_images: list) -> Image:
+    """
+    Get image for a specific position using reuse logic.
+    
+    Args:
+        position: 0-indexed position (0 = after intro, 1 = mid-article, etc.)
+        available_images: List of ContentImage objects
+    
+    Returns:
+        ContentImage object to use at this position
+    """
+    if not available_images:
+        return None
+    
+    num_images = len(available_images)
+    
+    if num_images == 1:
+        # Reuse single image everywhere
+        return available_images[0]
+    
+    elif num_images == 2:
+        # Alternate between images
+        return available_images[position % 2]
+    
+    elif num_images == 3:
+        # Use each twice (0,1,2,0,1,2)
+        return available_images[position % 3]
+    
+    else:
+        # Use each once, then repeat
+        return available_images[position % num_images]
+```
+
+---
+
+## Template System Design
+
+### Template Structure
+
+**Create:** `backend/igny8_core/modules/publisher/templates.py` (NEW)
+
+**Purpose:** Format content + images for WordPress publishing
+
+---
+
+### Base Content Template
+
+**Class:** `ContentTemplate`
+
+**Methods:**
+
+| Method | Purpose | Returns |
+|--------|---------|---------|
+| `prepare_content(content, images)` | Main entry point | Formatted HTML |
+| `insert_images(html, images, word_count)` | Insert images at positions | HTML with images |
+| `get_image_positions(word_count)` | Calculate insertion points | List of positions |
+| `format_image_html(image, alt_text)` | Format single image tag | HTML string |
+| `add_featured_image_meta(content, image)` | Set WordPress featured image | Meta dict |
+
+---
+
+### 500-Word Template
+
+**Class:** `ShortFormTemplate(ContentTemplate)`
+
+**Structure:**
+```html
+<div class="content-wrapper">
+  <!-- Introduction -->
+  <p><em>Hook...</em></p>
+  <p>Intro paragraph 1...</p>
+  <p>Intro paragraph 2...</p>
+  
+  <!-- Image 1: After introduction -->
+  <figure class="wp-block-image">
+    <img src="..." alt="..." />
+    <figcaption>Image caption (optional)</figcaption>
+  </figure>
+  
+  <!-- Section 1 -->
+  <h2>Section Heading 1</h2>
+  <p>Section content...</p>
+  
+  <!-- Image 2: Mid-article -->
+  <figure class="wp-block-image">
+    <img src="..." alt="..." />
+  </figure>
+  
+  <!-- Section 2 -->
+  <h2>Section Heading 2</h2>
+  <p>Section content...</p>
+  
+  <!-- Conclusion -->
+  <p>Conclusion...</p>
+</div>
+```
+
+**Characteristics:**
+- 2-3 images total
+- Shorter sections (80-100 words each)
+- Minimal subsections
+- Concise lists and tables
+
+---
+
+### 1000-Word Template
+
+**Class:** `StandardTemplate(ContentTemplate)`
+
+**Structure:**
+```html
+<div class="content-wrapper">
+  <!-- Introduction -->
+  <p><em>Hook...</em></p>
+  <p>Intro paragraphs...</p>
+  
+  <!-- Image 1 -->
+  <figure>...</figure>
+  
+  <!-- Section 1 -->
+  <h2>Section Heading 1</h2>
+  <p>Paragraphs...</p>
+  <h3>Subsection 1.1</h3>
+  <p>Content...</p>
+  
+  <!-- Section 2 -->
+  <h2>Section Heading 2</h2>
+  <p>Content...</p>
+  
+  <!-- Image 2 -->
+  <figure>...</figure>
+  
+  <!-- Section 3 -->
+  <h2>Section Heading 3</h2>
+  <ul>...</ul>
+  
+  <!-- Image 3 -->
+  <figure>...</figure>
+  
+  <!-- Section 4 -->
+  <h2>Section Heading 4</h2>
+  <table>...</table>
+  
+  <!-- Image 4 -->
+  <figure>...</figure>
+  
+  <!-- Conclusion -->
+  <h2>Conclusion</h2>
+  <p>Summary and CTA...</p>
+</div>
+```
+
+**Characteristics:**
+- 3-5 images
+- Standard sections (140-160 words each)
+- 2-3 subsections per section
+- Mix of content types (paragraphs, lists, tables)
+
+---
+
+### 1500-Word Template
+
+**Class:** `LongFormTemplate(ContentTemplate)`
+
+**Structure:**
+```html
+<div class="content-wrapper">
+  <!-- Introduction (180 words) -->
+  <p><em>Hook (45 words)...</em></p>
+  <p>Intro paragraph 1 (70 words)...</p>
+  <p>Intro paragraph 2 (65 words)...</p>
+  
+  <!-- Image 1 -->
+  <figure>...</figure>
+  
+  <!-- Section 1 (180 words) -->
+  <h2>Section Heading 1</h2>
+  <p>Opening paragraph (80 words)...</p>
+  <h3>Subsection 1.1</h3>
+  <p>Content (50 words)...</p>
+  <h3>Subsection 1.2</h3>
+  <p>Content (50 words)...</p>
+  
+  <!-- Section 2 -->
+  <h2>Section Heading 2</h2>
+  <p>Content...</p>
+  
+  <!-- Image 2 -->
+  <figure>...</figure>
+  
+  <!-- ... More sections with strategic image placement ... -->
+  
+  <!-- Section 7 -->
+  <h2>Section Heading 7</h2>
+  <p>Final content section...</p>
+  
+  <!-- Image 5 -->
+  <figure>...</figure>
+  
+  <!-- Conclusion (60 words) -->
+  <h2>Conclusion</h2>
+  <p>Summary paragraph...</p>
+  <p>Call to action...</p>
+</div>
+```
+
+**Characteristics:**
+- 4-7 images
+- Longer sections (180-200 words each)
+- 3-4 subsections per section
+- Deeper content with more examples
+- Optional info boxes or callouts
+
+---
+
+## Cluster Hub Landing Page Template
+
+**Purpose:** Comprehensive resource page for topic clusters
+
+**Class:** `ClusterHubTemplate(ContentTemplate)`
+
+### Structure
+
+```html
+<div class="cluster-hub">
+  <!-- Hero Section -->
+  <section class="hero">
+    <h1>{Cluster Name}</h1>
+    <p class="subtitle">{Cluster Description}</p>
+    <figure class="hero-image">
+      <img src="..." alt="..." />
+    </figure>
+  </section>
+  
+  <!-- Overview Block -->
+  <section class="overview">
+    <h2>What is {Cluster Name}?</h2>
+    <p>Comprehensive introduction to the topic...</p>
+    <p>Why it matters and what you'll learn...</p>
+  </section>
+  
+  <!-- Key Concepts Grid -->
+  <section class="key-concepts">
+    <h2>Key Concepts</h2>
+    <div class="concept-grid">
+      <div class="concept-card">
+        <h3>Concept 1</h3>
+        <p>Brief explanation...</p>
+      </div>
+      <!-- More concept cards -->
+    </div>
+  </section>
+  
+  <!-- Featured Image -->
+  <figure>...</figure>
+  
+  <!-- Subcluster Cards (if hierarchical) -->
+  <section class="subclusters">
+    <h2>Explore Related Topics</h2>
+    <div class="subcluster-grid">
+      <div class="subcluster-card">
+        <h3>Subcluster Name</h3>
+        <p>Description...</p>
+        <a href="...">Learn more →</a>
+      </div>
+      <!-- More subclusters -->
+    </div>
+  </section>
+  
+  <!-- Latest Articles -->
+  <section class="latest-articles">
+    <h2>Latest Articles</h2>
+    <div class="article-list">
+      <!-- Auto-populated from content in this cluster -->
+      <article class="article-preview">
+        <img src="..." alt="..." />
+        <h3>Article Title</h3>
+        <p>Excerpt...</p>
+        <a href="...">Read more →</a>
+      </article>
+      <!-- More articles -->
+    </div>
+  </section>
+  
+  <!-- Popular Articles -->
+  <section class="popular-articles">
+    <h2>Most Popular</h2>
+    <div class="article-list">
+      <!-- Sorted by views or engagement -->
+    </div>
+  </section>
+  
+  <!-- CTA Block -->
+  <section class="cta">
+    <h2>Stay Updated</h2>
+    <p>Get the latest insights on {Cluster Name}...</p>
+    <form>
+      <input type="email" placeholder="Enter your email" />
+      <button>Subscribe</button>
+    </form>
+  </section>
+  
+  <!-- Footer Navigation -->
+  <section class="footer-nav">
+    <h3>Related Topics</h3>
+    <ul>
+      <li><a href="...">Related Cluster 1</a></li>
+      <li><a href="...">Related Cluster 2</a></li>
+      <!-- More links -->
+    </ul>
+  </section>
+</div>
+```
+
+---
+
+### Cluster Hub Features
+
+| Feature | Implementation | Purpose |
+|---------|----------------|---------|
+| **Hero Image** | Full-width banner | Visual impact, brand identity |
+| **Concept Cards** | 3-6 key concepts | Quick overview, scannable |
+| **Subcluster Grid** | Links to child clusters | Hierarchy navigation |
+| **Latest Articles** | Auto-query by cluster_id | Fresh content |
+| **Popular Articles** | Sorted by view_count | Engagement driver |
+| **CTA Block** | Email signup or action | Lead generation |
+| **Footer Nav** | Related cluster links | Internal linking |
+
+---
+
+### Conditional Variants
+
+#### Category Archive (WordPress Taxonomy)
+
+**Differences from Cluster Hub:**
+- Shows WordPress category tree
+- Includes post count per category
+- Pagination for article list
+- Filter by date, popularity
+
+#### Tag Archive
+
+**Differences:**
+- Shows related tags as cloud
+- Simpler layout (no hero, no concepts)
+- Focus on article list
+- Sorted by relevance
+
+#### Attribute Archive (Product/Service)
+
+**Differences:**
+- Shows attribute filter options
+- Product/service grid instead of article list
+- Comparison table
+- Filter by attribute values
+
+---
+
+## Implementation Plan
+
+### Phase 1: Template System Foundation (Week 1)
+
+**Tasks:**
+1. ✅ Create `ContentTemplate` base class
+2. ✅ Implement image position calculator
+3. ✅ Implement image reuse logic
+4. ✅ Create image HTML formatter with figure tags
+5. ✅ Add WordPress meta integration (featured image)
+
+**File:** `backend/igny8_core/modules/publisher/templates.py` (NEW)
+
+---
+
+### Phase 2: Article Length Templates (Week 1-2)
+
+**Tasks:**
+1. ✅ Implement `ShortFormTemplate` (500 words)
+2. ✅ Implement `StandardTemplate` (1000 words)
+3. ✅ Implement `LongFormTemplate` (1500 words)
+4. ✅ Test image insertion for each template
+5. ✅ Validate HTML output
+
+**Testing:**
+- Generate 10 articles per template
+- Verify word counts
+- Check image placement
+- Validate HTML structure
+
+---
+
+### Phase 3: Cluster Hub Template (Week 2)
+
+**Tasks:**
+1. ✅ Implement `ClusterHubTemplate`
+2. ✅ Create hero section builder
+3. ✅ Create concept card generator
+4. ✅ Implement article list query
+5. ✅ Add related cluster links
+6. ✅ Test with real clusters
+
+**File:** Same as Phase 1
+
+---
+
+### Phase 4: Publishing Integration (Week 2-3)
+
+**Tasks:**
+1. ✅ Update WordPress publisher to use templates
+2. ✅ Pass content + images to template
+3. ✅ Generate final HTML
+4. ✅ Send to WordPress with featured image meta
+5. ✅ Test full publishing workflow
+
+**File:** `backend/igny8_core/modules/publisher/views.py`
+
+**Method:** `publish_to_wordpress()`
+
+**Changes:**
+
+```python
+def publish_to_wordpress(content_id):
+    content = Content.objects.get(id=content_id)
+    images = ContentImage.objects.filter(content=content).order_by('position')
+    
+    # Select template based on word count
+    if content.word_count <= 600:
+        template = ShortFormTemplate()
+    elif content.word_count <= 1200:
+        template = StandardTemplate()
+    else:
+        template = LongFormTemplate()
+    
+    # Prepare content with images
+    final_html = template.prepare_content(content, images)
+    
+    # Get featured image
+    featured_image = images.filter(type='featured').first()
+    
+    # Publish to WordPress
+    wp_client.create_post(
+        title=content.title,
+        content=final_html,
+        featured_image_url=featured_image.image_url if featured_image else None,
+        # ... other meta
+    )
+```
+
+---
+
+### Phase 5: Taxonomy Templates (Week 3)
+
+**Tasks:**
+1. ✅ Implement category archive variant
+2. ✅ Implement tag archive variant
+3. ✅ Implement attribute archive variant
+4. ✅ Add conditional rendering logic
+5. ✅ Test all taxonomy types
+
+---
+
+## HTML Quality Standards
+
+### Image Tags
+
+**Format:**
+```html
+<figure class="wp-block-image size-large">
+  <img 
+    src="{image_url}" 
+    alt="{descriptive_alt_text}" 
+    class="wp-image-{id}"
+  />
+  <figcaption>{optional_caption}</figcaption>
+</figure>
+```
+
+**Alt Text Generation:**
+- Extract from image prompt
+- Include relevant keywords
+- Descriptive, not generic ("Person using laptop" → "Digital marketer analyzing SEO metrics on laptop")
+
+---
+
+### Responsive Images (Future)
+
+**Enhancement:**
+```html
+<img 
+  src="{image_url}" 
+  srcset="{image_url_600} 600w, {image_url_1200} 1200w, {image_url_1920} 1920w"
+  sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 33vw"
+  alt="{alt_text}"
+/>
+```
+
+**Requires:** Image resizing service or WordPress handling
+
+---
+
+### Content Wrapper
+
+**Purpose:** Consistent styling and layout
+
+```html
+<div class="content-wrapper entry-content">
+  <!-- Article content -->
+</div>
+```
+
+**WordPress Classes:**
+- `entry-content` - Standard WordPress content class
+- `wp-block-*` - Gutenberg block classes for proper styling
+
+---
+
+## Testing Requirements
+
+### Template Output Tests
+
+| Test Case | Expected Result |
+|-----------|-----------------|
+| 500-word article with 1 image | Image reused 3 times at strategic positions |
+| 1000-word article with 3 images | Each image used once, evenly distributed |
+| 1500-word article with 5 images | Images at intro, mid-points, and conclusion |
+| Article with 0 images | No image tags, content flows normally |
+| Cluster hub page | All sections rendered, related content populated |
+
+---
+
+### HTML Validation
+
+- ✅ All HTML valid (W3C validator)
+- ✅ All image tags have alt text
+- ✅ Heading hierarchy correct (H1 → H2 → H3)
+- ✅ No broken image links
+- ✅ Figure tags properly closed
+- ✅ WordPress classes applied correctly
+
+---
+
+### WordPress Integration Tests
+
+- ✅ Featured image set correctly
+- ✅ Images appear in correct positions
+- ✅ Content renders properly in WordPress editor
+- ✅ Mobile responsive (WordPress theme handles)
+- ✅ Image captions display correctly
+- ✅ Internal links work
+
+---
+
+## Success Metrics
+
+- ✅ 100% of articles have images placed correctly
+- ✅ Image reuse logic works for all scenarios
+- ✅ Article lengths match templates (±5% tolerance)
+- ✅ HTML validates 100%
+- ✅ Cluster hubs render all sections
+- ✅ WordPress publishing succeeds 100%
+- ✅ User feedback: content looks professional
+- ✅ No manual image placement needed
+
+---
+
+## Related Files Reference
+
+### Backend (NEW)
+- `backend/igny8_core/modules/publisher/templates.py` - Template system
+- `backend/igny8_core/modules/publisher/image_manager.py` - Image reuse logic
+
+### Backend (Update)
+- `backend/igny8_core/modules/publisher/views.py` - Publishing integration
+- `backend/igny8_core/ai/functions/generate_content.py` - Content structure
+
+### Models
+- `backend/igny8_core/business/content/models.py` - Content, ContentImage models
+
+---
+
+## Notes
+
+- Templates should be flexible enough for custom themes
+- Image captions optional (can extract from prompt or leave empty)
+- Cluster hub template can be used for category/tag pages
+- Consider adding shortcode support for advanced layouts
+- Future: Allow custom template selection per content piece
+- Future: Visual template editor for admins
--- a/docs/PRE-LAUNCH/ITEM-6-MARKETING-SITE.md
+++ b/docs/PRE-LAUNCH/ITEM-6-MARKETING-SITE.md
@@ -0,0 +1,707 @@
+# Item 6: Frontend Marketing Site Updates
+
+**Priority:** High  
+**Target:** Production Launch  
+**Last Updated:** December 11, 2025
+
+---
+
+## Overview
+
+Update and polish the marketing website including homepage, features pages, product pages, use-case pages, pricing page, about, and contact pages. Ensure consistent branding, clear value propositions, and conversion-optimized layouts.
+
+---
+
+## Current Implementation
+
+### Marketing Site Structure
+
+**Location:** `frontend/src/pages/` (marketing section)
+
+**Current Pages:**
+- Homepage
+- Features (general)
+- Pricing
+- About
+- Contact
+- (Possibly others)
+
+**Issues:**
+- Content may be outdated or generic
+- Feature descriptions don't match current capabilities
+- Pricing page needs plan updates (from Item 2)
+- No dedicated product pages for each module
+- No use-case specific pages
+- Missing social proof and testimonials
+- CTAs not optimized
+
+---
+
+## Required Pages and Updates
+
+### A. Homepage
+
+**Location:** `frontend/src/pages/marketing/Home.tsx` or similar
+
+#### Current Issues
+- Value proposition unclear or generic
+- Feature highlights incomplete
+- Workflow demonstration missing
+- CTAs not prominent
+
+#### Required Sections
+
+**1. Hero Section**
+
+**Content:**
+- **Headline:** "AI-Powered Content Creation for SEO-Driven Websites"
+- **Subheadline:** "Transform your content strategy with semantic AI. Plan, write, and publish high-quality content that ranks."
+- **Primary CTA:** "Start Free Trial" (14-day trial, no credit card)
+- **Secondary CTA:** "See How It Works" (scroll to demo video)
+- **Hero Visual:** Animated workflow diagram or product screenshot
+
+**Design:**
+- Full-width, above fold
+- Gradient background or image
+- Logo grid: "Trusted by [companies/users]"
+
+---
+
+**2. Problem Statement**
+
+**Content:**
+- "Content creation is time-consuming and expensive"
+- "SEO is complex and constantly changing"
+- "Scaling content while maintaining quality is hard"
+- Visual: Problem illustration
+
+---
+
+**3. Solution Overview**
+
+**Content:**
+- "IGNY8 uses semantic AI to automate your entire content workflow"
+- 3 key benefits:
+  1. **Plan:** AI clusters keywords into strategic topics
+  2. **Write:** Generate SEO-optimized content in minutes
+  3. **Publish:** Direct WordPress integration
+- Visual: 3-column benefit cards
+
+---
+
+**4. Feature Highlights**
+
+**Content:**
+- AI Planner: Keyword extraction → Clustering → Idea generation
+- AI Writer: Content generation → Image creation → SEO optimization
+- Automation: End-to-end workflow automation
+- Analytics: Track performance and ROI
+
+**Design:**
+- 4 feature cards with icons
+- Each card links to detailed feature page
+
+---
+
+**5. How It Works**
+
+**Content:**
+- Step-by-step workflow:
+  1. Add keywords or import from GSC
+  2. AI clusters keywords semantically
+  3. Generate content ideas for each cluster
+  4. AI writes SEO-optimized articles
+  5. Generate images with AI
+  6. Publish to WordPress automatically
+
+**Visual:**
+- Animated step diagram
+- Or short video demo (30-60 seconds)
+
+---
+
+**6. Social Proof**
+
+**Content:**
+- User testimonials (3-4 quotes)
+- Usage statistics:
+  - "10,000+ articles generated"
+  - "500+ active users"
+  - "95% time saved on content creation"
+- Company logos (if applicable)
+
+**Design:**
+- Testimonial cards with photos
+- Stats counter animation
+
+---
+
+**7. Pricing Preview**
+
+**Content:**
+- "Plans for every team size"
+- Show 3 plan tiers with key features
+- CTA: "View Full Pricing" → /pricing
+
+---
+
+**8. Final CTA**
+
+**Content:**
+- "Ready to transform your content strategy?"
+- Primary CTA: "Start Free Trial"
+- Secondary CTA: "Schedule Demo"
+
+---
+
+### B. Features Page
+
+**Location:** `frontend/src/pages/marketing/Features.tsx`
+
+#### Required Sections
+
+**1. Features Overview**
+
+**Content:**
+- List all major features with descriptions
+- Organized by category:
+  - **Planning & Strategy**
+    - Keyword Extraction
+    - Semantic Clustering
+    - Content Idea Generation
+    - SAG Mapping (if implemented)
+  - **Content Creation**
+    - AI Writing (multiple lengths)
+    - Content Structure Templates
+    - SEO Optimization
+    - Tone & Style Control
+  - **Visual Content**
+    - Image Prompt Generation
+    - AI Image Creation
+    - Image Optimization
+  - **Publishing & Distribution**
+    - WordPress Integration
+    - Automated Publishing
+    - Content Scheduling
+  - **Automation**
+    - End-to-end Workflow Automation
+    - Batch Processing
+    - Custom Workflows
+  - **Analytics & Insights**
+    - Content Performance Tracking
+    - SEO Metrics
+    - Credit Usage Reports
+
+**Design:**
+- Accordion or tab-based navigation
+- Feature cards with icons
+- "Learn More" links to detail pages
+
+---
+
+**2. Feature Comparison Table**
+
+**Content:**
+- Compare features across plans
+- Show which features are in which tier
+
+**Table:**
+
+| Feature | Free | Starter | Growth | Pro | Enterprise |
+|---------|------|---------|--------|-----|------------|
+| Keywords | 100 | 1,000 | 5,000 | 25,000 | Unlimited |
+| AI Clustering | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Content Generation | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Image Generation | ✓ | ✓ | ✓ | ✓ | ✓ |
+| WordPress Integration | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Automation | ✗ | ✗ | ✓ | ✓ | ✓ |
+| API Access | ✗ | ✗ | ✓ | ✓ | ✓ |
+| Priority Support | ✗ | ✗ | ✗ | ✓ | ✓ |
+
+---
+
+### C. Product Pages (One per Module)
+
+**Create dedicated pages:**
+
+#### 1. AI Planner Page
+
+**URL:** `/product/planner`
+
+**Sections:**
+- Hero: "Plan Your Content Strategy with AI"
+- Problem: Manual keyword research is slow
+- Solution: Automated clustering and idea generation
+- Features:
+  - Keyword extraction from GSC
+  - Semantic clustering
+  - Content idea generation with outlines
+  - Visual cluster mapping
+- Use cases:
+  - Blog content planning
+  - Topic cluster strategy
+  - Content calendar creation
+- Demo video or screenshots
+- CTA: "Try Planner Free"
+
+---
+
+#### 2. AI Writer Page
+
+**URL:** `/product/writer`
+
+**Sections:**
+- Hero: "AI-Powered Content Creation"
+- Problem: Writing is time-consuming and expensive
+- Solution: Generate SEO-optimized content in minutes
+- Features:
+  - Multiple article lengths (500, 1000, 1500 words)
+  - Content structure templates
+  - SEO keyword integration
+  - Tone and style control
+- Use cases:
+  - Blog posts
+  - Product descriptions
+  - Landing pages
+  - Guides and tutorials
+- Demo video or screenshots
+- CTA: "Start Writing with AI"
+
+---
+
+#### 3. Automation Page
+
+**URL:** `/product/automation`
+
+**Sections:**
+- Hero: "Automate Your Entire Content Workflow"
+- Problem: Managing content at scale is complex
+- Solution: End-to-end automation from keywords to publication
+- Features:
+  - 7-stage automated workflow
+  - Batch processing
+  - Scheduled runs
+  - Progress monitoring
+- Use cases:
+  - Agency content production
+  - E-commerce catalog automation
+  - Multi-site management
+- Demo video or screenshots
+- CTA: "Automate Your Workflow"
+
+---
+
+### D. Use-Case Pages
+
+**Create industry/persona-specific pages:**
+
+#### 1. For Agencies
+
+**URL:** `/use-cases/agencies`
+
+**Content:**
+- Hero: "Scale Content Production for Your Clients"
+- Challenges: Managing multiple clients, tight deadlines, budget constraints
+- Solution: Automate content at scale without sacrificing quality
+- Features relevant to agencies:
+  - Multi-site management
+  - Team collaboration
+  - White-label potential (if applicable)
+  - Bulk operations
+- Case study or testimonial
+- Pricing: Focus on Growth and Pro plans
+- CTA: "Book Agency Demo"
+
+---
+
+#### 2. For E-commerce
+
+**URL:** `/use-cases/ecommerce`
+
+**Content:**
+- Hero: "Generate Product Content at Scale"
+- Challenges: Large product catalogs, SEO for products, content updates
+- Solution: Automate product descriptions, category pages, blog content
+- Features relevant to e-commerce:
+  - Product description generation
+  - Category landing pages
+  - SEO-optimized content
+  - Image generation for products
+- Case study or testimonial
+- CTA: "Start Free Trial"
+
+---
+
+#### 3. For Content Teams
+
+**URL:** `/use-cases/content-teams`
+
+**Content:**
+- Hero: "Supercharge Your Content Team"
+- Challenges: Content velocity, consistency, SEO optimization
+- Solution: AI assists writers, not replaces them
+- Features relevant to content teams:
+  - Content planning and ideation
+  - Draft generation
+  - SEO optimization
+  - Workflow automation
+- Case study or testimonial
+- CTA: "Try Team Plan"
+
+---
+
+### E. Pricing Page
+
+**Location:** `frontend/src/pages/marketing/Pricing.tsx`
+
+#### Required Updates (From Item 2)
+
+**1. Plan Tiers**
+
+Display all 5 tiers:
+- Free (hidden from public, internal only)
+- Starter ($29/mo or $299/year)
+- Growth ($99/mo or $1,019/year)
+- Pro ($299/mo or $3,077/year)
+- Enterprise (Custom pricing)
+
+**2. Monthly/Annual Toggle**
+
+- Default: Monthly
+- Show savings badge for annual ("Save 15%")
+- Update prices dynamically on toggle
+
+**3. Plan Cards**
+
+**Each card shows:**
+- Plan name
+- Price (monthly or annual)
+- "Most Popular" badge (Growth plan)
+- Key features (5-7 bullets):
+  - Monthly credits
+  - Max keywords, clusters, content, images
+  - Key features (automation, API, support)
+- CTA button:
+  - Free: "Start Free"
+  - Paid: "Start Trial" (14 days)
+  - Enterprise: "Contact Sales"
+
+**4. Detailed Comparison Table**
+
+Show full feature comparison (expandable):
+- All features listed
+- Checkmarks or values per plan
+- Tooltips explaining features
+
+**5. Credit System Explanation**
+
+**Section:**
+- "How Credits Work"
+- What credits are used for
+- How they're consumed (per operation)
+- How to buy more
+- Credit rollover rules (if applicable)
+
+**Example:**
+
+| Operation | Credits |
+|-----------|---------|
+| Keyword Clustering | 10 credits |
+| Idea Generation | 15 credits |
+| Content Generation (1000 words) | 10 credits |
+| Image Generation | 5 credits per image |
+
+**6. FAQ Section**
+
+**Questions to answer:**
+- What happens when I run out of credits?
+- Can I change plans mid-month?
+- Do unused credits roll over?
+- What's included in Enterprise?
+- Is there a free trial?
+- Can I cancel anytime?
+- What payment methods do you accept?
+- Do you offer refunds?
+
+**7. CTA Section**
+
+- "Still have questions?"
+- CTA: "Contact Sales" or "Schedule Demo"
+- Phone number, email, or chat option
+
+---
+
+### F. About Page
+
+**Location:** `frontend/src/pages/marketing/About.tsx`
+
+#### Required Sections
+
+**1. Mission Statement**
+
+- "Our mission is to democratize AI-powered content creation..."
+- Why IGNY8 exists
+- Vision for the future
+
+**2. Team** (if applicable)
+
+- Founder(s) photo and bio
+- Key team members
+- Company history/journey
+
+**3. Technology & Approach**
+
+- "Built on semantic AI and NLP"
+- Explanation of SAG architecture (simplified)
+- Why our approach is different/better
+
+**4. Values**
+
+- Quality over quantity
+- User-centric design
+- Transparency
+- Innovation
+
+**5. Contact**
+
+- How to reach us
+- Office location (if applicable)
+- Link to Contact page
+
+---
+
+### G. Contact Page
+
+**Location:** `frontend/src/pages/marketing/Contact.tsx`
+
+#### Required Elements
+
+**1. Contact Form**
+
+**Fields:**
+- Name (required)
+- Email (required)
+- Company (optional)
+- Message (required)
+- Subject dropdown:
+  - General Inquiry
+  - Sales
+  - Support
+  - Partnership
+  - Press
+
+**2. Alternative Contact Methods**
+
+- Email: support@igny8.com (or similar)
+- Phone: (if available)
+- Live chat: (if enabled)
+- Social media links
+
+**3. Support Resources**
+
+- Link to Help Center / Documentation
+- Link to FAQ
+- Link to Community (if applicable)
+
+**4. Office Location** (if applicable)
+
+- Address
+- Map embed
+
+---
+
+## Design & Branding Guidelines
+
+### Visual Design
+
+**Color Scheme:**
+- Primary: Brand blue/purple
+- Secondary: Accent colors
+- Neutral: Grays for text and backgrounds
+
+**Typography:**
+- Headings: Bold, clear hierarchy
+- Body: Readable, 16px+ base size
+- Code/monospace: For technical content
+
+**Imagery:**
+- Product screenshots
+- Workflow diagrams
+- Illustrations for concepts
+- Real user photos for testimonials
+
+**Icons:**
+- Consistent icon set throughout
+- Use for feature highlights, benefits
+
+---
+
+### Tone & Voice
+
+**Brand Voice:**
+- Professional but approachable
+- Technical but not jargon-heavy
+- Confident but not boastful
+- Helpful and supportive
+
+**Messaging Principles:**
+- Focus on benefits, not just features
+- Use clear, concise language
+- Avoid marketing fluff
+- Be specific with numbers and results
+- Address pain points directly
+
+---
+
+### Call-to-Actions
+
+**Primary CTAs:**
+- "Start Free Trial" (most common)
+- "Get Started Free"
+- "Try IGNY8 Free"
+
+**Secondary CTAs:**
+- "Schedule Demo"
+- "Contact Sales"
+- "Learn More"
+- "View Pricing"
+
+**CTA Design:**
+- Primary: Large, prominent button (brand color)
+- Secondary: Outline button or link
+- Clear contrast with background
+- Include arrow or icon for clarity
+
+---
+
+## SEO Optimization
+
+### Meta Tags
+
+**Each page needs:**
+- Title tag (50-60 chars)
+- Meta description (150-160 chars)
+- OG tags (for social sharing)
+- Schema markup (Organization, Product, FAQ)
+
+**Example (Homepage):**
+```html
+<title>IGNY8 - AI-Powered Content Creation for SEO-Driven Websites</title>
+<meta name="description" content="Automate your content strategy with semantic AI. Generate SEO-optimized articles, cluster keywords, and publish to WordPress automatically.">
+<meta property="og:title" content="IGNY8 - AI Content Creation Platform">
+<meta property="og:description" content="Transform your content strategy with AI...">
+<meta property="og:image" content="https://igny8.com/og-image.jpg">
+```
+
+---
+
+### Keyword Optimization
+
+**Target Keywords per Page:**
+
+| Page | Primary Keyword | Secondary Keywords |
+|------|----------------|-------------------|
+| Homepage | AI content creation | SEO automation, content strategy, semantic AI |
+| Features | AI content platform features | content automation tools, SEO software |
+| Planner | AI content planning | keyword clustering, topic research, content ideation |
+| Writer | AI article writer | content generation, SEO writing, blog automation |
+| Pricing | AI content pricing | content automation cost, SEO software pricing |
+| Agencies | AI content for agencies | agency content automation, white-label content |
+
+---
+
+### Performance
+
+**Requirements:**
+- Page load time < 3 seconds
+- Lighthouse score > 90
+- Mobile-friendly (responsive)
+- Core Web Vitals: Pass all metrics
+
+---
+
+## Implementation Plan
+
+### Phase 1: Content Audit & Updates (Week 1)
+1. ✅ Audit all existing marketing pages
+2. ✅ Identify outdated or missing content
+3. ✅ Write new content for homepage
+4. ✅ Update features page content
+5. ✅ Draft about and contact pages
+
+### Phase 2: New Pages (Week 1-2)
+1. ✅ Create product pages (Planner, Writer, Automation)
+2. ✅ Create use-case pages (Agencies, E-commerce, Content Teams)
+3. ✅ Write content for each page
+4. ✅ Design page layouts
+
+### Phase 3: Pricing Page (Week 2)
+1. ✅ Implement plan comparison table
+2. ✅ Add monthly/annual toggle
+3. ✅ Add credit cost table
+4. ✅ Write FAQ section
+5. ✅ Test all CTAs
+
+### Phase 4: Design & Branding (Week 2-3)
+1. ✅ Finalize color scheme and typography
+2. ✅ Create or source imagery
+3. ✅ Design icons for features
+4. ✅ Create demo videos or screenshots
+5. ✅ Ensure mobile responsiveness
+
+### Phase 5: SEO & Performance (Week 3)
+1. ✅ Add meta tags to all pages
+2. ✅ Implement schema markup
+3. ✅ Optimize images (compression, lazy loading)
+4. ✅ Test page speed
+5. ✅ Submit sitemap to search engines
+
+---
+
+## Success Metrics
+
+- ✅ All pages load in < 3 seconds
+- ✅ Lighthouse score > 90 for all pages
+- ✅ Mobile responsive (all pages)
+- ✅ Clear value proposition on homepage
+- ✅ Pricing page matches Item 2 specifications
+- ✅ CTAs prominent and clear
+- ✅ SEO meta tags on all pages
+- ✅ Professional, consistent design
+- ✅ User feedback: easy to understand offering
+
+---
+
+## Related Files Reference
+
+### Frontend Pages
+- `frontend/src/pages/marketing/Home.tsx`
+- `frontend/src/pages/marketing/Features.tsx`
+- `frontend/src/pages/marketing/Pricing.tsx`
+- `frontend/src/pages/marketing/About.tsx`
+- `frontend/src/pages/marketing/Contact.tsx`
+- `frontend/src/pages/marketing/product/Planner.tsx` (NEW)
+- `frontend/src/pages/marketing/product/Writer.tsx` (NEW)
+- `frontend/src/pages/marketing/product/Automation.tsx` (NEW)
+- `frontend/src/pages/marketing/use-cases/Agencies.tsx` (NEW)
+- `frontend/src/pages/marketing/use-cases/Ecommerce.tsx` (NEW)
+- `frontend/src/pages/marketing/use-cases/ContentTeams.tsx` (NEW)
+
+### Components
+- `frontend/src/components/marketing/HeroSection.tsx`
+- `frontend/src/components/marketing/FeatureCard.tsx`
+- `frontend/src/components/marketing/PricingCard.tsx`
+- `frontend/src/components/marketing/TestimonialCard.tsx`
+- `frontend/src/components/marketing/CTASection.tsx`
+
+---
+
+## Notes
+
+- Keep messaging consistent across all pages
+- Test all CTAs and forms before launch
+- Consider A/B testing headlines and CTAs
+- Update screenshots when product UI changes
+- Consider adding live chat widget
+- Plan for ongoing content updates (blog, case studies)
+- Consider multilingual support (future phase)
--- a/docs/PRE-LAUNCH/ITEM-7-DOCUMENTATION.md
+++ b/docs/PRE-LAUNCH/ITEM-7-DOCUMENTATION.md
@@ -0,0 +1,832 @@
+# Item 7: Documentation Systems
+
+**Priority:** High  
+**Target:** Production Launch  
+**Last Updated:** December 11, 2025
+
+---
+
+## Overview
+
+Create comprehensive documentation systems including in-app help, marketing site documentation, API references, integration guides, workflow guides, and FAQs. Ensure users can self-serve for common questions and technical implementation.
+
+---
+
+## Current State Analysis
+
+### Existing Documentation
+
+**Location:** `docs/` folder in repository
+
+**Current Structure:**
+- System architecture docs
+- Backend models and services
+- Frontend components
+- API references (partial)
+- Deployment guides
+
+**Issues:**
+- Documentation scattered and incomplete
+- No user-facing help system
+- No in-app contextual help
+- API documentation not published
+- Integration guides missing
+- FAQ not comprehensive
+
+---
+
+## Required Documentation Types
+
+### A. In-App Documentation
+
+**Purpose:** Help users within the application
+
+---
+
+#### 1. Contextual Help System
+
+**Implementation:** Floating help icon + modal
+
+**Location:** Every major page
+
+**Features:**
+- Help icon in page header (question mark)
+- Click to open help modal
+- Modal contains:
+  - Page overview
+  - Key features explanation
+  - Quick tips
+  - Link to full documentation
+  - Video tutorial (if available)
+
+**Example (Keywords Page):**
+
+```
+┌────────────────────────────────────────────────┐
+│ Help: Keywords Page                        [×] │
+├────────────────────────────────────────────────┤
+│ Overview                                       │
+│ ───────────────────────────────────────────── │
+│ The Keywords page is where you extract and    │
+│ manage SEO keywords for your content strategy.│
+│                                                │
+│ Key Features                                   │
+│ ───────────────────────────────────────────── │
+│ • Add Keywords: Manually or import from CSV   │
+│ • Cluster: Group keywords semantically        │
+│ • Volume & Difficulty: SEO metrics            │
+│ • Status: Track mapping progress              │
+│                                                │
+│ Quick Tips                                     │
+│ ───────────────────────────────────────────── │
+│ 💡 Start with 20-50 keywords                  │
+│ 💡 Run clustering after adding keywords       │
+│ 💡 Use filters to find unmapped keywords      │
+│                                                │
+│ [Watch Tutorial Video] [View Full Docs]       │
+└────────────────────────────────────────────────┘
+```
+
+**Content per Page:**
+
+| Page | Overview | Key Actions | Tips |
+|------|----------|-------------|------|
+| **Keywords** | Extract and manage keywords | Add, Import, Cluster | Start with 20-50, run clustering |
+| **Clusters** | View keyword groups | Edit, Generate Ideas | Review cluster names for clarity |
+| **Ideas** | Content ideas from clusters | Edit, Convert to Tasks | Check word count estimates |
+| **Tasks** | Content generation queue | Generate Content | Monitor credit usage |
+| **Content** | Review generated articles | Edit, Publish | Optimize before publishing |
+| **Images** | Manage article images | Generate Images | Check image relevance |
+| **Automation** | Automate workflows | Configure, Run | Start with small batches |
+
+---
+
+#### 2. Onboarding Tour
+
+**Component:** `frontend/src/components/onboarding/OnboardingTour.tsx` (NEW)
+
+**Purpose:** First-time user walkthrough
+
+**Trigger:** First login or first page visit
+
+**Steps:**
+
+**Step 1: Welcome**
+- "Welcome to IGNY8!"
+- "Let's take a quick tour to get you started"
+- [Start Tour] [Skip]
+
+**Step 2: Setup**
+- "First, connect your site and configure settings"
+- Points to Setup menu
+- [Next]
+
+**Step 3: Keywords**
+- "Add keywords to start planning content"
+- Points to Keywords page
+- [Next]
+
+**Step 4: Planner Workflow**
+- "Use the Planner to organize keywords and generate ideas"
+- Shows workflow diagram
+- [Next]
+
+**Step 5: Writer Workflow**
+- "The Writer generates content from your ideas"
+- Shows content generation process
+- [Next]
+
+**Step 6: Credits**
+- "Each AI operation uses credits. Monitor usage here."
+- Points to credits display
+- [Next]
+
+**Step 7: Done**
+- "You're all set! Start by adding keywords."
+- [Go to Keywords] [Finish Tour]
+
+**Implementation:**
+- Use library like `react-joyride` or custom tooltips
+- Store tour completion in localStorage
+- Option to restart tour from settings
+
+---
+
+#### 3. Tooltips on UI Elements
+
+**Coverage:**
+
+| Element | Tooltip Text |
+|---------|--------------|
+| Cluster button | "Group keywords by semantic similarity using AI" |
+| Generate Ideas button | "Create content ideas from selected clusters" |
+| Generate Content button | "Write articles from tasks using AI" |
+| Generate Images button | "Create images from prompts using AI" |
+| Word count field | "Target word count: 500, 1000, or 1500 words" |
+| Content structure dropdown | "Article format: guide, review, listicle, etc." |
+| Status badges | "Current processing status: pending, completed, failed" |
+| Credit balance | "Remaining credits for AI operations" |
+| Site selector | "Select site for this workflow" |
+| Sector selector | "Select industry sector for context" |
+
+**Implementation:**
+- Use Tooltip component (from Item 4)
+- Add to all icons, dropdowns, status indicators
+- Keep text brief (1-2 sentences)
+
+---
+
+#### 4. Inline Help Text
+
+**Placement:** Under form fields
+
+**Examples:**
+
+```tsx
+<FormField label="Keywords">
+  <input type="text" placeholder="Enter keyword" />
+  <InlineHelp>
+    Use lowercase, no special characters. 
+    Separate multiple keywords with commas.
+  </InlineHelp>
+</FormField>
+
+<FormField label="Word Count">
+  <select>
+    <option value="500">500 words</option>
+    <option value="1000">1000 words</option>
+    <option value="1500">1500 words</option>
+  </select>
+  <InlineHelp>
+    Choose article length. Affects credit usage (1 credit per 100 words).
+  </InlineHelp>
+</FormField>
+```
+
+---
+
+### B. Marketing Site Documentation
+
+**Purpose:** Public-facing help center
+
+**Location:** `/help` or `/docs` section of marketing site
+
+---
+
+#### 1. Help Center Structure
+
+**Homepage:** `/help`
+
+**Categories:**
+
+```
+Help Center
+├── Getting Started
+│   ├── Creating Your Account
+│   ├── Setting Up Your First Site
+│   ├── Understanding Credits
+│   └── Quick Start Guide
+├── Planner Module
+│   ├── Adding Keywords
+│   ├── Keyword Clustering
+│   ├── Generating Ideas
+│   └── Content Planning Strategy
+├── Writer Module
+│   ├── Creating Tasks
+│   ├── Generating Content
+│   ├── Generating Images
+│   ├── Editing Content
+│   └── Publishing to WordPress
+├── Automation
+│   ├── Setting Up Automation
+│   ├── Configuring Stages
+│   ├── Monitoring Progress
+│   └── Troubleshooting Automation
+├── Integrations
+│   ├── WordPress Setup
+│   ├── Google Search Console
+│   ├── API Integration
+│   └── OAuth Connections
+├── Billing & Plans
+│   ├── Understanding Plans
+│   ├── Managing Credits
+│   ├── Upgrading Your Plan
+│   └── Invoices and Payments
+├── Troubleshooting
+│   ├── Common Errors
+│   ├── API Issues
+│   ├── Publishing Problems
+│   └── Credit Deduction Issues
+└── FAQ
+    ├── General Questions
+    ├── Pricing Questions
+    ├── Technical Questions
+    └── Account Questions
+```
+
+**Each article contains:**
+- Title
+- Last updated date
+- Estimated reading time
+- Content with screenshots/gifs
+- Related articles
+- "Was this helpful?" feedback
+- Contact support link
+
+---
+
+#### 2. API Documentation
+
+**Location:** `/docs/api` or `/api-docs`
+
+**Format:** OpenAPI/Swagger or similar
+
+**Sections:**
+
+**Authentication**
+- Getting API keys
+- Authentication methods (Bearer token)
+- Rate limits
+- Error codes
+
+**Endpoints by Module:**
+
+**Planner API**
+- `GET /api/v1/planner/keywords/` - List keywords
+- `POST /api/v1/planner/keywords/` - Create keyword
+- `POST /api/v1/planner/keywords/auto_cluster/` - Trigger clustering
+- `GET /api/v1/planner/clusters/` - List clusters
+- `POST /api/v1/planner/ideas/generate/` - Generate ideas
+
+**Writer API**
+- `GET /api/v1/writer/tasks/` - List tasks
+- `POST /api/v1/writer/tasks/` - Create task
+- `POST /api/v1/writer/tasks/{id}/generate_content/` - Generate content
+- `GET /api/v1/writer/content/` - List content
+- `POST /api/v1/writer/content/{id}/generate_images/` - Generate images
+
+**Automation API**
+- `GET /api/v1/automation/runs/` - List runs
+- `POST /api/v1/automation/runs/start/` - Start automation
+- `POST /api/v1/automation/runs/{id}/pause/` - Pause automation
+- `POST /api/v1/automation/runs/{id}/resume/` - Resume automation
+
+**Billing API**
+- `GET /api/v1/billing/credits/` - Get credit balance
+- `GET /api/v1/billing/usage/` - Get usage logs
+- `GET /api/v1/billing/invoices/` - List invoices
+
+**System API**
+- `GET /api/v1/system/prompts/` - List prompts
+- `GET /api/v1/system/settings/` - Get settings
+- `POST /api/v1/system/settings/` - Update settings
+
+**For Each Endpoint Document:**
+- HTTP method and path
+- Description
+- Authentication required
+- Request parameters
+- Request body schema
+- Response schema
+- Example request
+- Example response
+- Possible error codes
+
+**Example Entry:**
+
+```markdown
+## Generate Content
+
+`POST /api/v1/writer/tasks/{id}/generate_content/`
+
+Generate AI content for a specific task.
+
+### Authentication
+Required. Bearer token.
+
+### Parameters
+- `id` (path, required): Task ID
+
+### Request Body
+```json
+{
+  "word_count": 1000,
+  "content_structure": "article"
+}
+```
+
+### Response
+```json
+{
+  "status": "success",
+  "task_id": "celery-task-uuid",
+  "message": "Content generation started"
+}
+```
+
+### Errors
+- `400 Bad Request`: Invalid parameters
+- `403 Forbidden`: Insufficient credits
+- `404 Not Found`: Task not found
+- `429 Too Many Requests`: Rate limit exceeded
+
+### Credit Cost
+1 credit per 100 words (10 credits for 1000-word article)
+```
+
+---
+
+#### 3. Integration Guides
+
+**Purpose:** Step-by-step setup instructions
+
+---
+
+**A. WordPress Integration Guide**
+
+**Location:** `/docs/integrations/wordpress`
+
+**Sections:**
+
+1. **Prerequisites**
+   - WordPress 5.0+ required
+   - Admin access
+   - REST API enabled
+
+2. **Installation Steps**
+   - Install WordPress plugin (if applicable) or use API
+   - Generate application password in WordPress
+   - Enter credentials in IGNY8
+
+3. **Configuration**
+   - Set default post type
+   - Set default category
+   - Configure SEO settings
+   - Set featured image rules
+
+4. **Publishing Workflow**
+   - How content syncs
+   - How images are uploaded
+   - How meta tags are set
+   - How to schedule posts
+
+5. **Troubleshooting**
+   - Connection errors
+   - Publishing failures
+   - Image upload issues
+   - Permission problems
+
+6. **Screenshots**
+   - Annotated screenshots for each step
+
+---
+
+**B. Google Search Console Integration**
+
+**Location:** `/docs/integrations/google-search-console`
+
+**Sections:**
+
+1. **Setup**
+   - OAuth authentication
+   - Site verification
+   - Permission requirements
+
+2. **Keyword Import**
+   - Importing search queries
+   - Volume and position data
+   - Filtering options
+
+3. **Syncing**
+   - Auto-sync frequency
+   - Manual sync
+   - Data refresh
+
+4. **Troubleshooting**
+   - OAuth errors
+   - Permission issues
+   - Data not syncing
+
+---
+
+**C. API Integration Guide**
+
+**Location:** `/docs/integrations/api`
+
+**Sections:**
+
+1. **Getting Started**
+   - Generating API keys
+   - Testing with cURL
+   - Rate limits
+
+2. **Authentication**
+   - Bearer token usage
+   - Security best practices
+
+3. **Common Workflows**
+   - Automated keyword import
+   - Bulk content generation
+   - Publishing pipelines
+
+4. **Webhooks** (if implemented)
+   - Setting up webhooks
+   - Event types
+   - Payload structure
+
+5. **Code Examples**
+   - Python example
+   - JavaScript example
+   - PHP example
+
+---
+
+#### 4. Workflow Guides
+
+**Purpose:** End-to-end workflow documentation
+
+---
+
+**A. Planner to Writer SEO Flow**
+
+**Location:** `/docs/workflows/seo-content-flow`
+
+**Content:**
+
+**Step 1: Keyword Research**
+- Add keywords manually or import from GSC
+- Aim for 50-100 keywords per topic area
+- Include variety of search volumes
+
+**Step 2: Keyword Clustering**
+- Run AI clustering on keywords
+- Review cluster names and descriptions
+- Merge or split clusters as needed
+
+**Step 3: Idea Generation**
+- Select clusters
+- Generate content ideas
+- Review cluster hub vs supporting ideas
+- Check word count estimates
+
+**Step 4: Task Creation**
+- Convert ideas to tasks
+- Set word count and structure
+- Organize by priority
+
+**Step 5: Content Generation**
+- Generate content for tasks
+- Monitor credit usage
+- Review generated content
+
+**Step 6: Image Generation**
+- Generate image prompts
+- Generate images from prompts
+- Review and approve images
+
+**Step 7: Publishing**
+- Edit content as needed
+- Publish to WordPress
+- Monitor performance
+
+**Screenshots/Videos for each step**
+
+---
+
+**B. Automation Workflow**
+
+**Location:** `/docs/workflows/automation`
+
+**Content:**
+
+**Overview**
+- What automation does
+- When to use it
+- Prerequisites
+
+**Configuration**
+- Stage batch sizes
+- Delays between stages
+- Credit budgets
+
+**Execution**
+- Starting a run
+- Monitoring progress
+- Pausing and resuming
+
+**Results**
+- Reviewing output
+- Handling failures
+- Re-running stages
+
+---
+
+#### 5. Credit System Documentation
+
+**Location:** `/docs/billing/credits`
+
+**Sections:**
+
+**How Credits Work**
+- What credits are
+- How they're used
+- How to purchase
+
+**Credit Costs**
+
+| Operation | Credits | Example |
+|-----------|---------|---------|
+| Keyword Clustering | 10 | Cluster 50 keywords = 10 credits |
+| Idea Generation | 15 per cluster | 3 clusters = 45 credits |
+| Content Generation | 1 per 100 words | 1000-word article = 10 credits |
+| Image Prompt Extraction | 3 | 1 article = 3 credits |
+| Image Generation | 6 per image | 5 images = 30 credits |
+
+**Credit Management**
+- Viewing balance
+- Monitoring usage
+- Auto top-up
+- Purchasing credits
+
+**Rollover Policy**
+- Monthly credits
+- Expiration rules
+- Unused credit handling
+
+---
+
+#### 6. Data Privacy & Security
+
+**Location:** `/docs/security`
+
+**Sections:**
+
+**Data Storage**
+- Where data is stored
+- Data encryption
+- Backup frequency
+
+**Access Control**
+- User roles and permissions
+- Account isolation
+- API security
+
+**Compliance**
+- GDPR compliance
+- Data deletion
+- Export your data
+
+**Best Practices**
+- Password requirements
+- Two-factor authentication (if available)
+- API key management
+
+---
+
+### C. FAQ System
+
+**Purpose:** Quick answers to common questions
+
+**Location:** `/help/faq` and in-app FAQ modal
+
+---
+
+#### FAQ Categories
+
+**1. General Questions**
+
+Q: What is IGNY8?
+A: IGNY8 is an AI-powered content creation platform...
+
+Q: How does the AI work?
+A: We use advanced NLP and semantic AI...
+
+Q: Is my content unique?
+A: Yes, all content is generated fresh for you...
+
+Q: Can I edit AI-generated content?
+A: Yes, you have full control to edit...
+
+---
+
+**2. Pricing Questions**
+
+Q: What happens when I run out of credits?
+A: You can purchase more credits or upgrade your plan...
+
+Q: Can I change plans mid-month?
+A: Yes, you can upgrade anytime. Prorated refunds for downgrades...
+
+Q: Do unused credits roll over?
+A: Monthly credits expire at the end of your billing cycle...
+
+Q: What's included in Enterprise?
+A: Custom credit allocations, priority support, dedicated account manager...
+
+Q: Is there a free trial?
+A: Yes, 14-day free trial on paid plans, no credit card required...
+
+Q: Can I cancel anytime?
+A: Yes, cancel anytime from your account settings...
+
+---
+
+**3. Content Generation Questions**
+
+Q: How long does content generation take?
+A: Typically 10-30 seconds per 1000-word article...
+
+Q: Can I control the writing style?
+A: Yes, choose tone, structure, and use author profiles...
+
+Q: What languages are supported?
+A: Currently English, with more languages planned...
+
+Q: Can I generate product descriptions?
+A: Yes, select "product_page" content structure...
+
+Q: How accurate is SEO optimization?
+A: Content includes primary keywords, proper structure, and meta tags...
+
+---
+
+**4. Integration Questions**
+
+Q: Which WordPress versions are supported?
+A: WordPress 5.0 and above...
+
+Q: Do I need a plugin?
+A: No, uses WordPress REST API. Plugin optional for advanced features...
+
+Q: Can I publish to multiple sites?
+A: Yes, create multiple site connections...
+
+Q: Does it work with WooCommerce?
+A: Yes, can generate product descriptions and category content...
+
+Q: Can I import from Google Docs?
+A: Not directly, but you can copy/paste or import CSV...
+
+---
+
+**5. Technical Questions**
+
+Q: Is there an API?
+A: Yes, full REST API available on Growth plan and above...
+
+Q: What are the rate limits?
+A: API: 100 requests/minute. Content generation: No limit but subject to credits...
+
+Q: Can I use webhooks?
+A: Yes, webhook support for automation events (Enterprise)...
+
+Q: How do I get API keys?
+A: Generate from Settings > Integrations > API Access...
+
+Q: Is there a mobile app?
+A: Not yet, but the web app is mobile-responsive...
+
+---
+
+**6. Account & Billing Questions**
+
+Q: How do I upgrade my plan?
+A: Go to Settings > Billing > Upgrade Plan...
+
+Q: What payment methods do you accept?
+A: Credit/debit cards via Stripe, PayPal, bank transfer (Enterprise)...
+
+Q: Can I get an invoice?
+A: Yes, invoices are automatically generated and emailed...
+
+Q: How do I add team members?
+A: Settings > Team > Invite User (available on Starter and above)...
+
+Q: Can I delete my account?
+A: Yes, Settings > Account > Delete Account. Data deleted after 14 days...
+
+---
+
+## Implementation Plan
+
+### Phase 1: In-App Help (Week 1-2)
+1. ✅ Create contextual help component
+2. ✅ Write help content for each page
+3. ✅ Add help icons to all pages
+4. ✅ Create onboarding tour component
+5. ✅ Implement tour steps
+
+### Phase 2: Help Center (Week 2)
+1. ✅ Set up help center structure
+2. ✅ Write Getting Started guides
+3. ✅ Write module-specific guides
+4. ✅ Create workflow documentation
+5. ✅ Add screenshots and videos
+
+### Phase 3: API Documentation (Week 2-3)
+1. ✅ Document all API endpoints
+2. ✅ Create code examples
+3. ✅ Set up API documentation tool (Swagger/Redoc)
+4. ✅ Test all endpoints
+5. ✅ Publish API docs
+
+### Phase 4: Integration Guides (Week 3)
+1. ✅ Write WordPress integration guide
+2. ✅ Write GSC integration guide
+3. ✅ Write API integration guide
+4. ✅ Create screenshots
+5. ✅ Test guides with fresh account
+
+### Phase 5: FAQ (Week 3)
+1. ✅ Compile common questions
+2. ✅ Write answers
+3. ✅ Categorize questions
+4. ✅ Create searchable FAQ interface
+5. ✅ Add FAQ to help center and in-app
+
+---
+
+## Success Metrics
+
+- ✅ Help content available for all major pages
+- ✅ Onboarding tour completed by 70%+ of new users
+- ✅ Help center covers 100% of core features
+- ✅ API documentation complete for all endpoints
+- ✅ Integration guides tested and validated
+- ✅ FAQ answers top 50 common questions
+- ✅ User support requests decrease by 40%
+- ✅ Documentation feedback positive (thumbs up > 80%)
+
+---
+
+## Related Files Reference
+
+### Frontend (NEW)
+- `frontend/src/components/help/HelpModal.tsx`
+- `frontend/src/components/onboarding/OnboardingTour.tsx`
+- `frontend/src/pages/Help/` - Help center pages
+- `frontend/src/pages/Docs/` - API documentation
+
+### Content (NEW)
+- `docs/help/` - Help center articles (Markdown)
+- `docs/api/` - API documentation (OpenAPI spec)
+- `docs/guides/` - Integration and workflow guides
+
+### Backend
+- API endpoint for serving documentation
+- Search functionality for help center
+
+---
+
+## Notes
+
+- Keep documentation up to date with product changes
+- Use analytics to track which docs are most viewed
+- Collect user feedback on helpfulness
+- Consider video tutorials for complex workflows
+- Plan for multilingual documentation (future)
+- Consider community forum or knowledge base (future)
+- Regular doc reviews (monthly or after major updates)
+- Use simple language, avoid jargon
+- Include lots of examples and screenshots
+- Test documentation with actual users before launch