diff --git a/IMPLEMENTATION-AUDIT-AND-ACTION-PLAN.md b/IMPLEMENTATION-AUDIT-AND-ACTION-PLAN.md
index c44749b4..81feba6a 100644
--- a/IMPLEMENTATION-AUDIT-AND-ACTION-PLAN.md
+++ b/IMPLEMENTATION-AUDIT-AND-ACTION-PLAN.md
@@ -1,54 +1,161 @@
-# Implementation Audit & Action Plan
-**Pre-Launch Items 1 & 4: Status Modules + Page Flow UX**
+# Implementation Audit - Reality Check
+**Based on Actual Codebase Analysis**
**Date:** December 15, 2025
-**Status:** Complete System Audit
-**Purpose:** Identify current implementation state and define exact changes needed
+**Status:** Code-Verified Action Plan
+**Purpose:** Ground implementation in what actually exists, not assumptions
---
-## Table of Contents
+## Executive Summary
-1. [UX Components Audit](#ux-components-audit)
-2. [Page Structure Audit](#page-structure-audit)
-3. [Module-by-Module Implementation Status](#module-by-module-implementation-status)
+### What Actually Works (Code-Verified)
+
+✅ **PageHeader Component** (`frontend/src/components/common/PageHeader.tsx`, 170 lines)
+- Handles site/sector selectors, badges, navigation tabs, last updated timestamp
+- Used consistently across all Planner/Writer pages
+- **No changes needed**
+
+✅ **ProgressModal Component** (`frontend/src/components/common/ProgressModal.tsx`, 822 lines)
+- Shows step-by-step progress for AI operations
+- Has visual step indicators, handles all AI functions
+- Extracts success messages with counts
+- **Works well, but has fragile regex parsing**
+
+✅ **useProgressModal Hook** (`frontend/src/hooks/useProgressModal.ts`, 815 lines)
+- Polls Celery task status every 2 seconds
+- Has elaborate `getStepInfo()` function (146 lines) that uses regex to extract counts
+- **Problem**: Relies on message format, not structured data
+
+✅ **Backend ProgressTracker** (`backend/igny8_core/ai/tracker.py`, 347 lines)
+- Has `update(phase, percentage, message, current, total, current_item, meta)` method
+- **Supports structured data via `meta` dict**
+- **Problem**: AI functions don't actually use `meta` to pass structured details
+
+✅ **Model Status Fields Work Fine**
+- Keywords: `status` = `('new', 'New'), ('mapped', 'Mapped')`
+- Clusters: `status` = `('new', 'New'), ('mapped', 'Mapped')`
+- ContentIdeas: `status` = `('new', 'New'), ('queued', 'Queued'), ('completed', 'Completed')`
+- Tasks: `status` = `('queued', 'Queued'), ('completed', 'Completed')`
+- Content: `status` = `('draft', 'Draft'), ('review', 'Review'), ('published', 'Published')`
+- **These work for workflow state tracking - don't need to change**
+
+### The Actual Problems
+
+❌ **Problem 1: Fragile Progress Data Extraction**
+- Frontend uses regex to parse counts from messages: `/(\d+)\s+keyword/i`, `/(\d+)\s+cluster/i`
+- **146 lines** of extraction logic in `getStepInfo()` function
+- Breaks if message wording changes
+- **Solution**: Backend should pass structured details, frontend reads directly
+
+❌ **Problem 2: Missing Workflow Guidance**
+- Users don't know where they are in the workflow (no "Step 2 of 3")
+- No contextual help for first-time users
+- No quick metrics summary visible
+- **Solution**: Add StepBanner, HelperNotification, MetricsPanel components
+
+❌ **Problem 3: Automation Progress Parsing Issues**
+- AutomationPage tries to parse `stage_X_result` JSON
+- Queue item display incorrect
+- Progress bar doesn't reflect actual progress
+- **Solution**: Fix stage result structure and parsing logic
---
+## Action Plan (Reality-Based)
-## UX Components Audit
+### Phase 1: Backend - Emit Structured Progress Details (Week 1)
-### Components Required by ITEM-4 but Missing
+**Goal**: Make AI functions pass structured data instead of just messages
-| Component | Status | Purpose | Priority |
-|-----------|--------|---------|----------|
-| **StepBanner** | 🔴 Missing | Show workflow step progress (Step 2/5) | High |
-| **HelperNotification** | 🔴 Missing | Contextual guidance messages | High |
-| **InlineGuidance** | 🔴 Missing | Help text under form fields | Medium |
-| **Breadcrumbs** | 🔴 Missing | Navigation breadcrumb trail | Medium |
-| **MetricsPanel** | 🔴 Missing | Collapsible bottom metrics panel | High |
-| **NotificationDropdown** | 🔴 Missing | Bell icon notifications | Medium |
+**Files to Update:**
+1. `backend/igny8_core/ai/functions/auto_cluster.py` (347 lines)
+2. `backend/igny8_core/ai/functions/generate_ideas.py`
+3. `backend/igny8_core/ai/functions/generate_content.py`
+4. `backend/igny8_core/ai/functions/generate_image_prompts.py`
+5. `backend/igny8_core/ai/functions/generate_images.py`
-### Existing Components (Good)
+**Change Pattern:**
-| Component | Status | Location | Notes |
-|-----------|--------|----------|-------|
-| **PageHeader** | ✅ Exists | `frontend/src/components/common/PageHeader.tsx` | Well-implemented, standardized |
-| **ModuleNavigationTabs** | ✅ Exists | `frontend/src/components/navigation/ModuleNavigationTabs.tsx` | Works well, needs tooltips |
-| **Tooltip** | ✅ Exists | `frontend/src/components/ui/tooltip/Tooltip.tsx` | Basic implementation, needs enhancement |
-| **ProgressModal** | ✅ Exists | `frontend/src/components/common/ProgressModal.tsx` | Needs refactoring |
+**Before:**
+```python
+tracker.update(
+ phase='SAVE',
+ percentage=90,
+ message=f"Creating {len(clusters)} clusters"
+)
+```
+
+**After:**
+```python
+tracker.update(
+ phase='SAVE',
+ percentage=90,
+ message=f"Creating {len(clusters)} clusters",
+ meta={
+ 'items_total': len(keywords),
+ 'items_processed': processed_count,
+ 'items_created': len(clusters),
+ 'current_item_name': current_cluster.name if current_cluster else None
+ }
+)
+```
+
+**Effort:** ~3-4 hours per function = 15-20 hours total
---
-### New Components to Create
+### Phase 2: Frontend - Simplify Progress Modal (Week 1-2)
-#### 1. StepBanner Component
+**Goal**: Remove regex parsing, read structured details directly
-**Purpose:** Display workflow step progress (e.g., "Step 2 of 5: Cluster Keywords")
+**Files to Update:**
+1. `frontend/src/hooks/useProgressModal.ts` (815 lines)
+ - **Remove**: Lines 96-242 (146 lines of regex extraction)
+ - **Add**: Simple `details` accessor from `state.meta.details`
-**Location:** `frontend/src/components/workflow/StepBanner.tsx` (NEW)
+2. `frontend/src/components/common/ProgressModal.tsx` (822 lines)
+ - **Simplify**: `getSuccessMessage()` to read from backend
+ - **Remove**: Regex patterns for extracting counts
-**Props:**
+**Before (useProgressModal.ts, ~146 lines):**
+```typescript
+const getStepInfo = (stepName: string, message: string, allSteps: any[]) => {
+ // Extract keyword count
+ let keywordCount = extractNumber(/(\d+)\s+keyword/i, message);
+ // ... 140 more lines of extraction logic
+};
+```
+
+**After (~20 lines):**
+```typescript
+const getStepInfo = (state: any): ProgressDisplay => {
+ const details = state.meta?.details || {};
+
+ return {
+ percentage: state.meta?.percentage || 0,
+ message: state.meta?.message || 'Processing...',
+ itemsTotal: details.items_total,
+ itemsProcessed: details.items_processed,
+ itemsCreated: details.items_created,
+ currentItemName: details.current_item_name,
+ };
+};
+```
+
+**Effort:** ~6-8 hours
+
+---
+
+### Phase 3: Create Missing UX Components (Week 2)
+
+#### 3.1 StepBanner Component
+
+**File:** `frontend/src/components/workflow/StepBanner.tsx` (NEW)
+
+**Purpose:** Show "Step 2 of 3: Organize Clusters" with clickable progress
+
+**Interface:**
```typescript
interface StepBannerProps {
currentStep: number;
@@ -58,830 +165,24 @@ interface StepBannerProps {
href: string;
completed: boolean;
}>;
- onStepClick?: (stepIndex: number) => void;
}
```
-**Visual:**
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Step 2 of 5: Organize into Clusters
-
-1. Extract Keywords ✓ → 2. Cluster Keywords ● → 3. Generate Ideas → 4. Create Content → 5. Publish
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
**Usage:**
```tsx
+// In Clusters.tsx
```
----
-
-#### 2. HelperNotification Component
-
-**Purpose:** Show contextual guidance (welcome, tips, warnings)
-
-**Location:** `frontend/src/components/helper/HelperNotification.tsx` (NEW)
-
-**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;
-}
-```
-
-**Visual:**
-```
-┌─────────────────────────────────────────────────┐
-│ 💡 Welcome to Keywords │
-│ │
-│ Extract and manage SEO keywords. Start by │
-│ adding keywords manually or importing CSV. │
-│ │
-│ [Import CSV] [Learn More] [Got it] [×] │
-└─────────────────────────────────────────────────┘
-```
-
-**Persistence:** Store dismissed state in localStorage per page
-
----
-
-#### 3. InlineGuidance Component
-
-**Purpose:** Small help text under form fields
-
-**Location:** `frontend/src/components/helper/InlineGuidance.tsx` (NEW)
-
-**Props:**
-```typescript
-interface InlineGuidanceProps {
- text: string;
- type?: 'info' | 'warning' | 'error';
- icon?: ReactNode;
-}
-```
-
-**Visual:**
-```
-[Input Field: Enter keyword]
-ℹ️ Use lowercase, no special characters. Separate with commas.
-```
-
----
-
-#### 4. Breadcrumbs Component
-
-**Purpose:** Navigation breadcrumb trail
-
-**Location:** `frontend/src/components/navigation/Breadcrumbs.tsx` (NEW)
-
-**Props:**
-```typescript
-interface BreadcrumbsProps {
- items: Array<{
- label: string;
- href?: string; // No href = current page
- }>;
-}
-```
-
-**Visual:**
-```
-Home > Setup > Sites > Site Settings
-```
-
----
-
-#### 5. MetricsPanel Component
-
-**Purpose:** Collapsible metrics panel at page bottom
-
-**Location:** `frontend/src/components/dashboard/MetricsPanel.tsx` (NEW)
-
-**Props:**
-```typescript
-interface MetricsPanelProps {
- title: string;
- metrics: Array<{
- label: string;
- value: string | number;
- subtitle?: string;
- icon?: ReactNode;
- tooltip?: string;
- onClick?: () => void;
- }>;
- collapsible?: boolean;
- defaultCollapsed?: boolean;
-}
-```
-
-**Visual (Expanded):**
-```
-┌─────────────────────────────────────────────────────────┐
-│ ▼ Keyword Metrics [Collapse] × │
-├─────────────────────────────────────────────────────────┤
-│ Total: 450 │ New: 120 │ Mapped: 330 │ Vol: 125K │
-│ ℹ️ All saved │ ℹ️ Unmapped │ ℹ️ In cluster │ ℹ️ Search │
-└─────────────────────────────────────────────────────────┘
-```
-
----
-
-#### 6. NotificationDropdown Component
-
-**Purpose:** Bell icon with notification list
-
-**Location:** `frontend/src/components/notifications/NotificationDropdown.tsx` (NEW)
-
-**Backend Required:** `Notification` model with account FK
-
-**Props:**
-```typescript
-interface NotificationDropdownProps {
- notifications: Notification[];
- unreadCount: number;
- onMarkRead: (id: number) => void;
- onClearAll: () => void;
-}
-```
-
----
-
-### Tooltip Component Enhancement
-
-**Current Location:** `frontend/src/components/ui/tooltip/Tooltip.tsx`
-
-**Current Implementation:** Basic hover tooltip with portal rendering
-
-**Required Enhancements:**
-
-| Enhancement | Current | Required |
-|-------------|---------|----------|
-| Keyboard accessibility | ❌ No ESC handler | ✅ ESC to close, tab navigation |
-| Hover delay | ❌ Immediate show | ✅ 300ms delay before show |
-| Max width | ❌ Whitespace nowrap | ✅ Max-width with wrapping |
-| Rich content | ❌ Text only | ✅ Support ReactNode content |
-| Arrow positioning | ✅ Has arrow | ✅ Keep current (good) |
-
-**Example Usage (Enhanced):**
-```tsx
-
- Clustering
- Groups keywords by semantic similarity
- Learn more →
-
-}>
-
-
-```
-
----
-
-## Page Structure Audit
-
-### Current Page Structure (Planner/Writer Pages)
-
-**Example: Keywords.tsx**
-
-```tsx
-
-
, color: 'blue' }}
- navigation={
}
- />
-
- {/* Actions bar */}
-
-
-
-
-
- {/* Main content - table */}
-
-
- {/* No metrics panel */}
-
- {/* 1. Page Header (EXISTS) */}
-
}
- />
-
- {/* 2. Step Banner (MISSING - needs creation) */}
- {isWorkflowPage &&
}
-
- {/* 3. Helper Notification (MISSING - needs creation) */}
- {showHelper &&
}
-
- {/* 4. Breadcrumbs (MISSING - needs creation) */}
- {showBreadcrumbs &&
}
-
- {/* 5. Page Actions Bar (EXISTS, needs standardization) */}
-
-
- {/* 6. Main Content (EXISTS) */}
-
- {/* Tables, forms, cards */}
-
-
- {/* 7. Metrics Panel (MISSING - needs creation) */}
-
-
- {keyword.generation_status === 'processing' && (
- }>
- Processing
-
- )}
- {keyword.generation_status === 'completed' && (
- Completed
- )}
- |
-```
-
----
-
-### Phase 3: Create New UX Components (Week 2)
-
-#### 3.1 StepBanner Component
-
-**File:** `frontend/src/components/workflow/StepBanner.tsx` (NEW)
-
-**Implementation:**
-```tsx
-import React from 'react';
-import { Link } from 'react-router-dom';
-
-interface Step {
- label: string;
- href: string;
- completed: boolean;
-}
-
-interface StepBannerProps {
- currentStep: number;
- totalSteps: number;
- steps: Step[];
-}
-
-export default function StepBanner({ currentStep, totalSteps, steps }: StepBannerProps) {
- return (
-
-
- Step {currentStep} of {totalSteps}: {steps[currentStep - 1]?.label}
-
-
- {steps.map((step, idx) => (
-
- {step.completed ? (
-
- ✓ {idx + 1}. {step.label}
-
- ) : idx === currentStep - 1 ? (
-
- ● {idx + 1}. {step.label}
-
- ) : (
-
- {idx + 1}. {step.label}
-
- )}
- {idx < steps.length - 1 && (
- →
- )}
-
- ))}
-
-
-
-
{icons[type]}
-
-
{title}
-
{message}
- {actions && actions.length > 0 && (
-
- {actions.map((action, idx) => (
-
- ))}
-
- )}
-
- {dismissible && (
-
- )}
-
-