closing final plans

2025-12-27 11:14:51 +00:00
parent c227d9ee03
commit 9d54bbff48
1 changed files with 772 additions and 0 deletions
--- a/COMPREHENSIVE-AUDIT-REPORT.md
+++ b/COMPREHENSIVE-AUDIT-REPORT.md
@@ -0,0 +1,772 @@
+# IGNY8 Comprehensive UX Audit & Recommendations
+
+**Date:** December 27, 2025  
+**Scope:** Complete application audit for optimal user experience
+
+---
+
+## Table of Contents
+
+1. [Site & Sector Selector Placement](#1-site--sector-selector-placement)
+2. [Metrics System Recommendations](#2-metrics-system-recommendations)
+3. [Progress Modal Steps Audit](#3-progress-modal-steps-audit)
+4. [Dashboard Redesign Plan](#4-dashboard-redesign-plan)
+5. [Site Setup Checklist Implementation](#5-site-setup-checklist-implementation)
+6. [To-Do-s Completion Audit](#6-to-do-s-completion-audit)
+7. [Notification System Plan](#7-notification-system-plan)
+
+---
+
+## 1. Site & Sector Selector Placement
+
+### Rationale
+- **Site Selector**: Required when data is scoped to a specific site
+- **Sector Selector**: Required when data can be further filtered by content category/niche
+- **Both**: When user needs precise data filtering at granular level
+- **None**: When page is not site-specific or shows account-level data
+
+### Recommendations by Page
+
+| Page | Site Selector | Sector Selector | Reason |
+|------|:-------------:|:---------------:|--------|
+| **DASHBOARD** |
+| Home | ✅ All Sites option | ❌ | Overview across sites - sector too granular for dashboard |
+| **SETUP** |
+| Add Keywords | ✅ | ✅ | Keywords are site+sector specific |
+| Content Settings | ✅ | ❌ | Settings are site-level, not sector-level |
+| Sites List | ❌ | ❌ | Managing sites themselves |
+| Site Dashboard | ❌ (context) | ❌ | Already in specific site context |
+| Site Settings tabs | ❌ (context) | ❌ | Already in specific site context |
+| **PLANNER** |
+| Keywords | ✅ | ✅ | Keywords organized by site+sector |
+| Clusters | ✅ | ✅ | Clusters organized by site+sector |
+| Cluster Detail | ❌ (context) | ❌ (context) | Already in cluster context |
+| Ideas | ✅ | ✅ | Ideas organized by site+sector |
+| **WRITER** |
+| Tasks/Queue | ✅ | ✅ | Tasks organized by site+sector |
+| Content/Drafts | ✅ | ✅ | Content organized by site+sector |
+| Content View | ❌ (context) | ❌ (context) | Viewing specific content |
+| Images | ✅ | ✅ | Images tied to content by site+sector |
+| Review | ✅ | ✅ | Review queue by site+sector |
+| Published | ✅ | ✅ | Published content by site+sector |
+| **AUTOMATION** |
+| Automation | ✅ | ❌ | Automation runs at site level |
+| **LINKER** (if enabled) |
+| Content List | ✅ | ✅ | Linking is content-specific |
+| **OPTIMIZER** (if enabled) |
+| Content Selector | ✅ | ✅ | Optimization is content-specific |
+| Analysis Preview | ❌ (context) | ❌ (context) | Already in analysis context |
+| **THINKER** (Admin) |
+| All Thinker pages | ❌ | ❌ | System-wide prompts/profiles |
+| **BILLING** |
+| All Billing pages | ❌ | ❌ | Account-level billing data |
+| **ACCOUNT** |
+| Account Settings | ❌ | ❌ | Account-level settings |
+| Profile | ❌ | ❌ | User profile |
+| Team | ❌ | ❌ | Account-wide team |
+| Plans | ❌ | ❌ | Account-level plans |
+| Usage | ❌ | ❌ | Account-level usage |
+| **HELP** |
+| Help Page | ❌ | ❌ | Documentation |
+
+### Implementation Priority
+1. **High**: Ensure Planner & Writer pages show both selectors
+2. **Medium**: Automation shows site only
+3. **Low**: Account/Billing/Thinker show none
+
+---
+
+## 2. Metrics System Recommendations
+
+### A. Header Metrics Bar (Table Action Row)
+
+**Current**: Shows Credits + optional page metrics  
+**Problem**: Limited space, unclear what metrics mean, no actionable insights
+
+#### Recommended Header Metrics by Page
+
+##### Keywords Page
+| Metric | Value Example | Tooltip |
+|--------|---------------|---------|
+| Keywords | `46` | Total keywords in current view. Add more to expand your content pipeline. |
+| Clustered | `10` | Keywords organized into clusters. Unclustered keywords need grouping before idea generation. |
+| Unmapped | `0` | Keywords not assigned to clusters. Select unmapped keywords and click "Auto Cluster" to organize them. |
+| Volume | `13.6K` | Combined monthly search volume of your keywords. Higher volume = more potential traffic. |
+
+##### Clusters Page
+| Metric | Value Example | Tooltip |
+|--------|---------------|---------|
+| Clusters | `12` | Total keyword clusters. Each cluster can generate multiple content ideas. |
+| With Ideas | `8` | Clusters that have generated content ideas. Click a cluster without ideas to "Generate Ideas". |
+| Avg Size | `4.2` | Average keywords per cluster. 3-7 keywords per cluster is optimal for focused content. |
+| Ready | `4` | Clusters ready for idea generation (have keywords, no ideas yet). |
+
+##### Ideas Page
+| Metric | Value Example | Tooltip |
+|--------|---------------|---------|
+| Ideas | `34` | Content ideas ready to become articles. Select ideas and click "Create Tasks". |
+| Pending | `12` | Ideas not yet converted to tasks. Convert ideas to tasks to begin content creation. |
+| In Tasks | `22` | Ideas already converted to writing tasks. View in Writer → Tasks. |
+
+##### Tasks Page
+| Metric | Value Example | Tooltip |
+|--------|---------------|---------|
+| Queue | `15` | Tasks waiting for content generation. Select tasks and click "Generate Content". |
+| Processing | `2` | Tasks currently being written by AI. Content will appear in Drafts when complete. |
+| Complete | `28` | Tasks with generated content. View and edit in Writer → Content. |
+
+##### Content/Drafts Page
+| Metric | Value Example | Tooltip |
+|--------|---------------|---------|
+| Drafts | `25` | Content pieces in draft status. Review and approve to move to publishing. |
+| Pending Images | `8` | Drafts missing images. Select and click "Generate Images" to create visuals. |
+| Ready to Review | `17` | Drafts with complete content and images. Click "Send to Review" when ready. |
+
+##### Review Page
+| Metric | Value Example | Tooltip |
+|--------|---------------|---------|
+| In Review | `5` | Content awaiting your review. Approve to move to publishing queue. |
+| This Week | `12` | Content reviewed this week. Stay on top of reviews to maintain workflow. |
+
+##### Published Page
+| Metric | Value Example | Tooltip |
+|--------|---------------|---------|
+| Published | `45` | Content successfully published to WordPress. |
+| This Month | `12` | Content published this billing cycle. |
+| Total Words | `52.3K` | Total words published. Great for tracking content velocity! |
+
+### B. Module Metrics Footer (Below Tables)
+
+**Current Problem**: Cards too large, not enough actionable info, unclear relationship to user's workflow
+
+#### Recommended Footer Design: Compact Information Cards
+
+**New Size**: Reduce card padding from `p-5 md:p-6` to `p-3 md:p-4`  
+**Layout**: 4-column grid on desktop, 2-column on tablet, 1-column on mobile
+
+#### Keywords Page Footer
+
+| Card | Title | Value | Subtitle | Color | Action |
+|------|-------|-------|----------|-------|--------|
+| 1 | Total Keywords | `46` | `10 clusters` | blue | → Keywords |
+| 2 | Clustered | `42` | `91% organized` | green | → Clusters |
+| 3 | Easy Wins | `8` | `Low difficulty, high volume` | orange | Filter low diff |
+| 4 | Unmapped | `4` | `Need clustering` | purple | Select unmapped |
+
+**Progress Bar**: `Keyword Pipeline: 91% clustered`
+
+#### Clusters Page Footer
+
+| Card | Title | Value | Subtitle | Color | Action |
+|------|-------|-------|----------|-------|--------|
+| 1 | Clusters | `12` | `46 keywords` | blue | - |
+| 2 | With Ideas | `8` | `67% have ideas` | green | → Ideas |
+| 3 | Ready | `4` | `Can generate ideas` | orange | Select ready |
+| 4 | Empty | `0` | `No keywords` | purple | - |
+
+**Progress Bar**: `Idea Pipeline: 67% clusters have ideas`
+
+#### Tasks Page Footer
+
+| Card | Title | Value | Subtitle | Color | Action |
+|------|-------|-------|----------|-------|--------|
+| 1 | Ideas | `34` | `From 12 clusters` | blue | → Planner/Ideas |
+| 2 | In Queue | `15` | `Awaiting AI` | orange | - |
+| 3 | Processing | `2` | `Writing now` | purple | - |
+| 4 | Complete | `28` | `Ready for review` | green | → Content |
+
+**Progress Bar**: `Content Pipeline: 62% tasks complete`
+
+#### Content Page Footer
+
+| Card | Title | Value | Subtitle | Color | Action |
+|------|-------|-------|----------|-------|--------|
+| 1 | Drafts | `25` | `12.5K words` | blue | - |
+| 2 | Has Images | `17` | `68% visual` | green | - |
+| 3 | Needs Images | `8` | `Generate images` | orange | Select no images |
+| 4 | Ready | `17` | `Complete & ready` | success | Send to review |
+
+**Progress Bar**: `Image Pipeline: 68% have images`
+
+### C. Additional Explainer Text
+
+Add a subtle helper line below metrics footer (optional, can be toggled off):
+
+```
+💡 Next step: 8 drafts need images. Select them and click "Generate Images" to complete.
+```
+
+This contextual guidance appears based on current data state.
+
+---
+
+## 3. Progress Modal Steps Audit
+
+### Current Issues
+- Generic messages lacking context
+- Missing counts where data is available
+- Inconsistent terminology
+- Not professional/polished
+
+### Recommended Progress Step Text
+
+#### Auto Cluster Keywords
+
+| Phase | Current | Recommended |
+|-------|---------|-------------|
+| INIT | Validating keywords | Validating {count} keywords for clustering |
+| PREP | Loading keyword data | Analyzing keyword relationships |
+| AI_CALL | Generating clusters with Igny8 Semantic SEO Model | Grouping keywords by search intent ({count} keywords) |
+| PARSE | Organizing clusters | Organizing {cluster_count} semantic clusters |
+| SAVE | Saving clusters | Saving {cluster_count} clusters with {keyword_count} keywords |
+| DONE | Clustering complete! | ✓ Created {cluster_count} clusters from {keyword_count} keywords |
+
+#### Generate Ideas
+
+| Phase | Current | Recommended |
+|-------|---------|-------------|
+| INIT | Verifying cluster integrity | Analyzing {count} clusters for content opportunities |
+| PREP | Loading cluster keywords | Mapping {keyword_count} keywords to topic briefs |
+| AI_CALL | Generating ideas with Igny8 Semantic AI | Generating content ideas for {cluster_count} clusters |
+| PARSE | High-opportunity ideas generated | Structuring {idea_count} article outlines |
+| SAVE | Content Outline for Ideas generated | Saving {idea_count} content ideas with outlines |
+| DONE | Ideas generated! | ✓ Generated {idea_count} content ideas from {cluster_count} clusters |
+
+#### Generate Content
+
+| Phase | Current | Recommended |
+|-------|---------|-------------|
+| INIT | Validating task | Preparing {count} article{s} for generation |
+| PREP | Preparing content idea | Building content brief with {keyword_count} target keywords |
+| AI_CALL | Writing article with Igny8 Semantic AI | Writing {count} article{s} (~{word_target} words each) |
+| PARSE | Formatting content | Formatting HTML content and metadata |
+| SAVE | Saving article | Saving {count} article{s} ({total_words} words) |
+| DONE | Content generated! | ✓ {count} article{s} generated ({total_words} words total) |
+
+#### Generate Image Prompts
+
+| Phase | Current | Recommended |
+|-------|---------|-------------|
+| INIT | Checking content and image slots | Analyzing content for {count} image opportunities |
+| PREP | Mapping content for image prompts | Identifying featured image and {in_article_count} in-article image slots |
+| AI_CALL | Writing Featured Image Prompts | Creating optimized prompts for {count} images |
+| PARSE | Writing In‑article Image Prompts | Refining {in_article_count} contextual image descriptions |
+| SAVE | Assigning Prompts to Dedicated Slots | Assigning {count} prompts to image slots |
+| DONE | Prompts generated! | ✓ {count} image prompts ready (1 featured + {in_article_count} in-article) |
+
+#### Generate Images from Prompts
+
+| Phase | Current | Recommended |
+|-------|---------|-------------|
+| INIT | Validating image prompts | Queuing {count} images for generation |
+| PREP | Preparing image generation queue | Preparing AI image generation ({count} images) |
+| AI_CALL | Generating images with AI | Generating image {current}/{count}... |
+| PARSE | Processing image URLs | Processing {count} generated images |
+| SAVE | Saving image URLs | Uploading {count} images to media library |
+| DONE | Images generated! | ✓ {count} images generated and saved |
+
+### Success Message Templates (with counts)
+
+```typescript
+// Clustering
+`✓ Organized ${keywordCount} keywords into ${clusterCount} semantic clusters`
+
+// Ideas
+`✓ Created ${ideaCount} content ideas with detailed outlines`
+
+// Content
+`✓ Generated ${articleCount} articles (${totalWords.toLocaleString()} words)`
+
+// Image Prompts
+`✓ Created prompts for ${imageCount} images (1 featured + ${inArticleCount} in-article)`
+
+// Image Generation
+`✓ Generated and saved ${imageCount} AI images`
+```
+
+---
+
+## 4. Dashboard Redesign Plan
+
+### Current Issues
+- Too much whitespace
+- Large headings with little content
+- Workflow guide takes too much space
+- Not actionable at a glance
+- Missing "needs attention" items
+- Missing recent activity
+
+### New Dashboard Layout (Compact, Information-Dense)
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ ⚠ NEEDS ATTENTION (collapsible, only if items exist)                        │
+│ ┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────┐ │
+│ │ 3 content pending review│ │ WP sync failed (Site A) │ │ Credits at 82%  │ │
+│ │ [Review →]              │ │ [Retry] [Settings →]    │ │ [Upgrade →]     │ │
+│ └─────────────────────────┘ └─────────────────────────┘ └─────────────────┘ │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ QUICK STATS (compact 4-6 column row)                                        │
+│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐                       │
+│ │Sites │ │ KWs  │ │Clust │ │Ideas │ │Draft │ │Pub'd │ [Site: ▼ All Sites]  │
+│ │  2   │ │ 156  │ │  23  │ │  67  │ │  12  │ │  45  │                       │
+│ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘                       │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ WORKFLOW PIPELINE (compact horizontal)         │ CREDITS                    │
+│ Sites → Keywords → Clusters → Ideas            │ ████████░░░░░ 826/30K     │
+│   ✓        156        23        67             │ ~82% remaining             │
+│ → Content → Published                          │ Est. 340 articles left     │
+│      12        45                              │ [View Usage →]             │
+├────────────────────────────────────────────────┼────────────────────────────┤
+│ QUICK ACTIONS (2 column grid)                  │ WORKFLOW GUIDE             │
+│ ┌────────────────┐ ┌────────────────┐          │ 1. Add Keywords → Planner  │
+│ │ + Add Keywords │ │ ⚡ Auto Cluster │          │ 2. Cluster → Auto Cluster  │
+│ └────────────────┘ └────────────────┘          │ 3. Ideas → Generate Ideas  │
+│ ┌────────────────┐ ┌────────────────┐          │ 4. Tasks → Create Tasks    │
+│ │ 📝 Write Content│ │ 🖼 Gen Images  │          │ 5. Content → Generate      │
+│ └────────────────┘ └────────────────┘          │ 6. Images → Generate       │
+│ ┌────────────────┐ ┌────────────────┐          │ 7. Review → Approve        │
+│ │ ✓ Review Queue │ │ 🚀 Publish     │          │ 8. Publish → WordPress     │
+│ └────────────────┘ └────────────────┘          │ [Full Help →]              │
+├────────────────────────────────────────────────┴────────────────────────────┤
+│ RECENT ACTIVITY (compact list, max 5 items)                                 │
+│ • Generated 5 articles from "Product Reviews" cluster        2 hours ago   │
+│ • Created 12 image prompts for fitness content               4 hours ago   │
+│ • Clustered 45 keywords into 8 groups                        Yesterday     │
+│ • Published "10 Best Running Shoes" to WordPress             Yesterday     │
+│ • Added 23 keywords from seed database                       2 days ago    │
+│                                                              [View All →]  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ AUTOMATION STATUS (if enabled)                                              │
+│ ● Active  Last run: 2h ago  Next: Tomorrow 9:00 AM  [Configure →] [Run →]  │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Component Specifications
+
+#### 1. NeedsAttention Widget
+```typescript
+interface NeedsAttentionItem {
+  type: 'pending_review' | 'sync_failed' | 'low_credits' | 'setup_incomplete' | 'automation_failed';
+  title: string;
+  count?: number;
+  actions: Array<{ label: string; href?: string; onClick?: () => void }>;
+  severity: 'warning' | 'error' | 'info';
+}
+```
+
+**Triggers:**
+- `pending_review`: content.review.count > 0
+- `sync_failed`: site.wordpress_sync.last_error exists
+- `low_credits`: usage > 80%
+- `setup_incomplete`: site.setup_checklist.complete < 100%
+- `automation_failed`: automation.last_run.status === 'failed'
+
+#### 2. Quick Stats Row
+- Ultra-compact metric chips
+- Clickable to navigate to relevant page
+- Shows current site filter or "All Sites"
+
+#### 3. Workflow Pipeline (Compact)
+- Single-line visual with numbers under each stage
+- Checkmarks for completed stages
+- Arrows showing flow direction
+- Subtle progress indication
+
+#### 4. Credits Widget (Compact)
+- Progress bar with percentage
+- Remaining estimate ("~340 articles left" based on avg cost)
+- Link to usage page
+
+#### 5. Quick Actions Grid
+- 2x3 grid of action buttons
+- Icons + short labels
+- Direct actions (opens relevant page/modal)
+
+#### 6. Workflow Guide (Compact)
+- Numbered list (1-8 steps)
+- Each step is a link
+- Collapsible on mobile
+- "Full Help" link to help page
+
+#### 7. Recent Activity
+- Compact list format
+- Icon + description + timestamp
+- Max 5 items with "View All" link
+- Real data from AI task logs
+
+#### 8. Automation Status (Conditional)
+- Only shows if automation configured
+- Status indicator (green dot = active)
+- Last run / next run times
+- Quick configure/run buttons
+
+### Dashboard API Endpoint
+
+Create aggregated endpoint to reduce API calls:
+
+```typescript
+// GET /api/v1/dashboard/summary/
+interface DashboardSummary {
+  pipeline: {
+    sites: number;
+    keywords: number;
+    clusters: number;
+    ideas: number;
+    tasks_pending: number;
+    content_draft: number;
+    content_review: number;
+    content_published: number;
+  };
+  credits: {
+    used: number;
+    limit: number;
+    percentage: number;
+    estimated_remaining_articles: number;
+  };
+  needs_attention: NeedsAttentionItem[];
+  recent_activity: ActivityItem[];
+  automation: {
+    enabled: boolean;
+    status: 'active' | 'paused' | 'failed';
+    last_run: string | null;
+    next_run: string | null;
+  };
+  sites_setup: Array<{
+    site_id: number;
+    site_name: string;
+    checklist_complete: number; // percentage
+  }>;
+}
+```
+
+---
+
+## 5. Site Setup Checklist Implementation
+
+### Current Status
+- ✅ `SiteSetupChecklist.tsx` component EXISTS
+- ✅ Integrated in `Site Dashboard` page (full mode)
+- ❌ **NOT integrated in `SiteCard.tsx`** (compact mode not used)
+
+### Missing Implementation
+
+The component has a `compact` prop but is not used in the site cards list.
+
+### Recommended Fix
+
+**File:** `frontend/src/components/sites/SiteCard.tsx`
+
+Add compact checklist to each site card:
+
+```tsx
+// In SiteCard component, add after the status badges:
+<SiteSetupChecklist
+  siteId={site.id}
+  siteName={site.name}
+  hasIndustry={!!site.industry}
+  hasSectors={site.sectors_count > 0}
+  hasWordPressIntegration={!!site.wordpress_site_url}
+  hasKeywords={site.keywords_count > 0}
+  compact={true}
+/>
+```
+
+**Visual Result:**
+```
+┌─────────────────────────────────────────┐
+│ My Website                    [Active]  │
+│ example.com                             │
+│ Industry: Tech  │  3 Sectors            │
+│ ●●●○  3/4 Setup Steps Complete          │  ← NEW compact checklist
+│                              [Manage →] │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 6. To-Do-s Completion Audit
+
+### Summary by Section
+
+| Section | File | Status | Remaining Items |
+|---------|------|--------|-----------------|
+| Section 1 | `dashboard_mods.md` | 📋 Planned (do LAST) | Dashboard revamp, aggregated API |
+| Section 2 | `SECTION_2_FINAL_MODS.md` | ✅ Done | - |
+| Section 3 | `SECTION_3_FINAL_MODS.md` | ✅ Done | - |
+| Section 4 | `SECTION_4_FINAL_MODS.md` | ✅ Done | Usage alerts, API activity data |
+| Section 5 | `SECTION_5_FINAL_MODS.md` | ✅ Done | - |
+| Section 6 | `SECTION_6_FINAL_MODS.md` | ✅ Done | - |
+| Pricing | `pricing_simplification.md` | 📋 Planned | Credit simplification |
+
+### Remaining Items Detail
+
+#### Dashboard (Section 1) - Major Work
+- [ ] Aggregated API endpoint `/v1/dashboard/summary/`
+- [ ] NeedsAttention widget
+- [ ] Real Recent Activity log (replace hardcoded)
+- [ ] Automation Status display
+- [ ] Real-time polling/updates
+- [ ] Contextual Quick Actions
+
+#### Usage (Section 4) - Minor Work
+- [ ] Real API Activity data (currently hardcoded)
+- [ ] Real success rate calculation
+- [ ] Usage alerts at 80%, 90%, 100%
+- [ ] Per-site usage breakdown
+- [ ] Usage forecasting
+
+#### Pricing Simplification
+- [ ] Remove monthly limit fields (keep credits/keywords/sites only)
+- [ ] Update CreditCostConfig values
+- [ ] Add `target_word_count` to ContentSettings
+- [ ] Update Usage page (credits only)
+
+#### Cross-Module
+- [ ] Notification bell dropdown with AI run logging
+- [ ] Single source of truth for credit balance
+
+---
+
+## 7. Notification System Plan
+
+### Current State
+- Bell icon exists with placeholder/mock notifications
+- No real notification system or API
+- No notification persistence
+
+### Comprehensive Notification System Design
+
+#### A. Notification Data Model
+
+```python
+# backend/igny8_core/business/notifications/models.py
+
+class Notification(BaseModel):
+    account = models.ForeignKey('Account', on_delete=models.CASCADE)
+    user = models.ForeignKey('User', on_delete=models.CASCADE, null=True)  # null = all users
+    
+    # Notification content
+    type = models.CharField(max_length=50, choices=NOTIFICATION_TYPES)
+    title = models.CharField(max_length=200)
+    message = models.TextField()
+    severity = models.CharField(max_length=20, choices=SEVERITY_CHOICES)
+    
+    # Related objects
+    site = models.ForeignKey('Site', null=True, on_delete=models.CASCADE)
+    content_type = models.ForeignKey(ContentType, null=True)
+    object_id = models.PositiveIntegerField(null=True)
+    content_object = GenericForeignKey()
+    
+    # Action
+    action_url = models.CharField(max_length=500, null=True)
+    action_label = models.CharField(max_length=50, null=True)
+    
+    # Status
+    is_read = models.BooleanField(default=False)
+    read_at = models.DateTimeField(null=True)
+    
+    created_at = models.DateTimeField(auto_now_add=True)
+
+NOTIFICATION_TYPES = [
+    # AI Operations
+    ('ai_cluster_complete', 'Clustering Complete'),
+    ('ai_cluster_failed', 'Clustering Failed'),
+    ('ai_ideas_complete', 'Ideas Generated'),
+    ('ai_ideas_failed', 'Idea Generation Failed'),
+    ('ai_content_complete', 'Content Generated'),
+    ('ai_content_failed', 'Content Generation Failed'),
+    ('ai_images_complete', 'Images Generated'),
+    ('ai_images_failed', 'Image Generation Failed'),
+    
+    # Workflow
+    ('content_ready_review', 'Content Ready for Review'),
+    ('content_published', 'Content Published'),
+    ('content_publish_failed', 'Publishing Failed'),
+    
+    # WordPress Sync
+    ('wordpress_sync_success', 'WordPress Sync Complete'),
+    ('wordpress_sync_failed', 'WordPress Sync Failed'),
+    
+    # Credits/Billing
+    ('credits_low', 'Credits Running Low'),
+    ('credits_depleted', 'Credits Depleted'),
+    ('plan_upgraded', 'Plan Upgraded'),
+    
+    # Setup
+    ('site_setup_complete', 'Site Setup Complete'),
+    ('keywords_imported', 'Keywords Imported'),
+]
+
+SEVERITY_CHOICES = [
+    ('info', 'Info'),
+    ('success', 'Success'),
+    ('warning', 'Warning'),
+    ('error', 'Error'),
+]
+```
+
+#### B. Notification Creation Points
+
+| Trigger Event | Notification Type | Severity | Title | Message Template |
+|---------------|-------------------|----------|-------|------------------|
+| Clustering completes | `ai_cluster_complete` | success | Clustering Complete | Created {count} clusters from {keyword_count} keywords |
+| Clustering fails | `ai_cluster_failed` | error | Clustering Failed | Failed to cluster keywords: {error} |
+| Ideas generated | `ai_ideas_complete` | success | Ideas Generated | Generated {count} content ideas from {cluster_count} clusters |
+| Ideas failed | `ai_ideas_failed` | error | Idea Generation Failed | Failed to generate ideas: {error} |
+| Content generated | `ai_content_complete` | success | Content Generated | Generated {count} articles ({word_count} words) |
+| Content failed | `ai_content_failed` | error | Content Generation Failed | Failed to generate content: {error} |
+| Images generated | `ai_images_complete` | success | Images Generated | Generated {count} images for your content |
+| Images failed | `ai_images_failed` | error | Image Generation Failed | Failed to generate {count} images: {error} |
+| Content published | `content_published` | success | Content Published | "{title}" published to {site_name} |
+| Publish failed | `content_publish_failed` | error | Publishing Failed | Failed to publish "{title}": {error} |
+| WP sync success | `wordpress_sync_success` | success | WordPress Synced | Synced {count} items with {site_name} |
+| WP sync failed | `wordpress_sync_failed` | error | Sync Failed | WordPress sync failed for {site_name}: {error} |
+| Credits at 80% | `credits_low` | warning | Credits Running Low | You've used 80% of your credits. Consider upgrading. |
+| Credits at 90% | `credits_low` | warning | Credits Almost Depleted | Only 10% of credits remaining. Upgrade to continue. |
+| Credits depleted | `credits_depleted` | error | Credits Depleted | Your credits are exhausted. Upgrade to continue. |
+| Site setup done | `site_setup_complete` | success | Site Ready | {site_name} is fully configured and ready! |
+| Keywords imported | `keywords_imported` | info | Keywords Imported | Added {count} keywords to {site_name} |
+
+#### C. API Endpoints
+
+```python
+# GET /api/v1/notifications/
+# Returns paginated list, most recent first
+{
+    "count": 45,
+    "unread_count": 3,
+    "results": [
+        {
+            "id": 123,
+            "type": "ai_content_complete",
+            "title": "Content Generated",
+            "message": "Generated 5 articles (4,500 words)",
+            "severity": "success",
+            "site": {"id": 1, "name": "My Blog"},
+            "action_url": "/writer/content",
+            "action_label": "View Content",
+            "is_read": false,
+            "created_at": "2025-12-27T10:30:00Z"
+        }
+    ]
+}
+
+# POST /api/v1/notifications/{id}/read/
+# Mark single notification as read
+
+# POST /api/v1/notifications/read-all/
+# Mark all notifications as read
+
+# DELETE /api/v1/notifications/{id}/
+# Delete notification
+```
+
+#### D. Frontend Integration
+
+##### NotificationDropdown Component Updates
+
+```tsx
+// frontend/src/components/header/NotificationDropdown.tsx
+
+interface Notification {
+  id: number;
+  type: string;
+  title: string;
+  message: string;
+  severity: 'info' | 'success' | 'warning' | 'error';
+  site?: { id: number; name: string };
+  action_url?: string;
+  action_label?: string;
+  is_read: boolean;
+  created_at: string;
+}
+
+// Features:
+// - Fetch real notifications on mount
+// - Poll every 30 seconds for new notifications
+// - Show unread count badge on bell icon
+// - Mark as read on click
+// - Navigate to action_url on click
+// - "Mark all read" button
+// - "View all" link to full notifications page
+```
+
+##### Full Notifications Page
+
+Create `/account/notifications` page with:
+- Full list of all notifications (paginated)
+- Filter by type, severity, site
+- Bulk actions (mark read, delete)
+- Date range filtering
+
+#### E. Implementation Priority
+
+**Phase 1 (Core):**
+1. Create Notification model
+2. Create API endpoints
+3. Hook AI functions to create notifications on complete/fail
+4. Update NotificationDropdown to fetch real data
+
+**Phase 2 (Enhanced):**
+1. Credit threshold notifications
+2. WordPress sync notifications
+3. Full notifications page
+4. Email notifications (optional)
+
+**Phase 3 (Polish):**
+1. Notification preferences
+2. Push notifications
+3. Real-time updates (WebSocket)
+
+---
+
+## Implementation Roadmap
+
+### Priority Order
+
+1. **Site Setup Checklist on Cards** - Quick win, already built
+2. **Notification System** - High user value
+3. **Metrics Improvements** - Better user understanding
+4. **Progress Modal Text** - Polish
+5. **Dashboard Redesign** - Major effort, do last
+
+### Estimated Effort
+
+| Item | Backend | Frontend | Total |
+|------|---------|----------|-------|
+| Site checklist on cards | 0h | 2h | 2h |
+| Notification system | 8h | 8h | 16h |
+| Metrics improvements | 2h | 8h | 10h |
+| Progress modal text | 4h | 4h | 8h |
+| Dashboard redesign | 8h | 16h | 24h |
+| **Total** | **22h** | **38h** | **60h** |
+
+---
+
+## Appendix: Current vs Recommended Comparison
+
+### Header Metrics Example (Keywords Page)
+
+**Current:**
+```
+| Credits 826/30K |
+```
+
+**Recommended:**
+```
+| Credits 826/30K | Keywords 46 ⓘ | Clustered 10 ⓘ | Unmapped 0 ⓘ | Volume 13.6K ⓘ |
+```
+
+### Footer Metrics Example (Keywords Page)
+
+**Current:** Large cards with minimal info
+
+**Recommended:** Compact cards with actionable data + progress bar + next step hint
+
+### Dashboard Example
+
+**Current:** Hero banner + large sections + much whitespace
+
+**Recommended:** Compact info-dense layout with needs-attention, stats, pipeline, actions, activity all visible without scrolling
+