diff --git a/IMPLEMENTATION-AUDIT-AND-ACTION-PLAN.md b/IMPLEMENTATION-AUDIT-AND-ACTION-PLAN.md
new file mode 100644
index 00000000..c44749b4
--- /dev/null
+++ b/IMPLEMENTATION-AUDIT-AND-ACTION-PLAN.md
@@ -0,0 +1,1173 @@
+# Implementation Audit & Action Plan
+**Pre-Launch Items 1 & 4: Status Modules + Page Flow UX**
+
+**Date:** December 15, 2025
+**Status:** Complete System Audit
+**Purpose:** Identify current implementation state and define exact changes needed
+
+---
+
+## Table of Contents
+
+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)
+
+---
+
+
+## UX Components Audit
+
+### Components Required by ITEM-4 but Missing
+
+| 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 |
+
+### Existing Components (Good)
+
+| 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 |
+
+---
+
+### New Components to Create
+
+#### 1. StepBanner Component
+
+**Purpose:** Display workflow step progress (e.g., "Step 2 of 5: Cluster Keywords")
+
+**Location:** `frontend/src/components/workflow/StepBanner.tsx` (NEW)
+
+**Props:**
+```typescript
+interface StepBannerProps {
+ currentStep: number;
+ totalSteps: number;
+ steps: Array<{
+ label: string;
+ 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
+
+```
+
+---
+
+#### 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 && (
+
+ )}
+
+
IGNY8 Admin Dashboard
-
-
-
-
-
-
Accounts
-
-
- {{ accounts.total }}
- Total Accounts
-
-
- {{ accounts.active }}
- Active
-
-
- {{ accounts.low_credit }}
- Low Credits (< 100)
-
-
-
-
-
-
-
Content Production
-
-
- {{ content.this_week }}
- This Week
-
-
- {{ content.this_month }}
- This Month
-
-
- {{ content.tasks_pending }}
- Tasks Pending
-
-
-
-
-
-
-
Billing
-
-
-
{{ billing.pending_payments }}
-
Pending Approvals
-
- Review
-
-
-
- ${{ billing.payments_this_month|floatformat:2 }}
- Revenue This Month
-
-
- {{ billing.credit_usage_this_month }}
- Credits Used
-
-
-
-
-
-
-
Automation
-
-
- {{ automation.running }}
- Running Now
-
-
-
{{ automation.failed_this_week }}
-
Failed (7 days)
- {% if automation.failed_this_week > 0 %}
-
- Review
-
- {% endif %}
-
-
-
-
-
-
-
Integration Health
-
-
-
{{ integration.sync_failed_today }}
-
Failed Syncs Today
- {% if integration.sync_failed_today > 0 %}
-
- Review
-
- {% endif %}
-
-
-
-
- {% for alert in alerts %}
-
- {% endfor %}
-
Hello world!
')
-# Returns: 2
-```
-
-**Method:**
-1. Strips HTML tags using BeautifulSoup
-2. Fallback to regex if BeautifulSoup fails
-3. Counts words (sequences of alphanumeric characters)
-
-#### format_word_count(count)
-```python
-formatted = format_word_count(1500) # "1.5K"
-formatted = format_word_count(125000) # "125K"
-```
-
-#### validate_word_count_limit(html_content, limit)
-```python
-result = validate_word_count_limit(html, limit=100000)
-# Returns: {
-# 'allowed': True,
-# 'word_count': 2500,
-# 'limit': 100000,
-# 'remaining': 97500,
-# 'would_exceed_by': 0
-# }
-```
-
----
-
-## Scheduled Tasks
-
-**Location:** `backend/igny8_core/tasks/plan_limits.py`
-
-### 1. Reset Monthly Plan Limits
-**Task Name:** `reset_monthly_plan_limits`
-**Schedule:** Daily at 00:30 UTC
-**Purpose:** Reset monthly usage for accounts at period end
-
-**Process:**
-1. Find all active accounts with subscriptions
-2. Check if `current_period_end` <= today
-3. Call `LimitService.reset_monthly_limits(account)`
-4. Update subscription period dates
-5. Log reset summary
-
-### 2. Check Approaching Limits
-**Task Name:** `check_approaching_limits`
-**Schedule:** Daily at 09:00 UTC
-**Purpose:** Warn users when usage exceeds 80% threshold
-
-**Process:**
-1. Find all active accounts
-2. Get usage summary
-3. Check if any limit >= 80%
-4. Log warnings (future: send email notifications)
-
-**Celery Beat Configuration:**
-`backend/igny8_core/celery.py`
-
-```python
-app.conf.beat_schedule = {
- 'reset-monthly-plan-limits': {
- 'task': 'reset_monthly_plan_limits',
- 'schedule': crontab(hour=0, minute=30),
- },
- 'check-approaching-limits': {
- 'task': 'check_approaching_limits',
- 'schedule': crontab(hour=9, minute=0),
- },
-}
-```
-
----
-
-## API Endpoints
-
-### Get Usage Summary
-**Endpoint:** `GET /api/v1/billing/usage-summary/`
-**Authentication:** Required (IsAuthenticatedAndActive)
-**Response:** Usage summary for current account
-
-**Example Request:**
-```bash
-curl -H "Authorization: Bearer " \
- /api/v1/billing/usage-summary/
-```
-
-**Example Response:**
-```json
-{
- "success": true,
- "message": "Usage summary retrieved successfully.",
- "data": {
- "account_id": 1,
- "account_name": "Acme Corp",
- "plan_name": "Growth Plan",
- "period_start": "2025-12-01",
- "period_end": "2025-12-31",
- "days_until_reset": 19,
- "hard_limits": { ... },
- "monthly_limits": { ... }
- }
-}
-```
-
----
-
-## Error Handling
-
-### HardLimitExceededError
-```python
-raise HardLimitExceededError(
- f"Sites limit exceeded. Current: 5, Limit: 5. "
- f"Upgrade your plan to increase this limit."
-)
-```
-
-**HTTP Status:** 403 Forbidden
-**User Action:** Upgrade plan or delete unused resources
-
-### MonthlyLimitExceededError
-```python
-raise MonthlyLimitExceededError(
- f"Content Words limit exceeded. Used: 295000, Requested: 8000, Limit: 300000. "
- f"Resets on December 31, 2025. Upgrade your plan or wait for reset."
-)
-```
-
-**HTTP Status:** 403 Forbidden
-**User Action:** Wait for reset, upgrade plan, or reduce request size
-
----
-
-## Frontend Integration Guide
-
-### TypeScript Types
-```typescript
-interface Plan {
- id: number;
- name: string;
- // Hard limits
- max_sites: number;
- max_users: number;
- max_keywords: number;
- max_clusters: number;
- // Monthly limits
- max_content_ideas: number;
- max_content_words: number;
- max_images_basic: number;
- max_images_premium: number;
- max_image_prompts: number;
-}
-
-interface UsageSummary {
- account_id: number;
- account_name: string;
- plan_name: string;
- period_start: string;
- period_end: string;
- days_until_reset: number;
- hard_limits: {
- [key: string]: {
- display_name: string;
- current: number;
- limit: number;
- remaining: number;
- percentage_used: number;
- };
- };
- monthly_limits: {
- [key: string]: {
- display_name: string;
- current: number;
- limit: number;
- remaining: number;
- percentage_used: number;
- };
- };
-}
-```
-
-### API Hook Example
-```typescript
-// src/services/api/billing.ts
-export const getUsageSummary = async (): Promise => {
- const response = await apiClient.get('/billing/usage-summary/');
- return response.data.data;
-};
-
-// src/pages/Dashboard.tsx
-const { data: usage } = useQuery('usage-summary', getUsageSummary);
-```
-
-### UI Components
-
-#### Usage Widget
-```tsx
-
-
- Usage This Month
- {usage.days_until_reset} days until reset
-
-
- {Object.entries(usage.monthly_limits).map(([key, data]) => (
-
-
{data.display_name}
-
= 80 ? 'warning' : 'primary'}
- />
- {data.current.toLocaleString()} / {data.limit.toLocaleString()}
-