todos docs

2025-12-26 00:12:25 +00:00
parent 444d53dc7b
commit 33b4454f96
3 changed files with 308 additions and 0 deletions
--- a/to-do-s/PRE-LAUNCH-AUDIT.md
+++ b/to-do-s/PRE-LAUNCH-AUDIT.md
@@ -0,0 +1,867 @@
+# Pre-Launch System Audit
+
+**Date:** December 25, 2025  
+**Purpose:** Identify functional workflow gaps and improvements for pre-launch QA  
+**Scope:** Non-cosmetic, professional, workflow-based issues only
+
+---
+
+## Table of Contents
+1. [Dashboard](#1-dashboard)
+2. [SETUP Modules](#2-setup-modules)
+3. [WORKFLOW Modules](#3-workflow-modules)
+4. [ACCOUNT Modules](#4-account-modules)
+5. [HELP Module](#5-help-module)
+6. [Sidebar & Navigation](#6-sidebar--navigation)
+7. [Summary & Prioritization](#7-summary--prioritization)
+
+---
+
+## 1. Dashboard
+
+**Route:** `/`  
+**Files:** `pages/Dashboard/Home.tsx`, `components/dashboard/*`
+
+### Current Functionality
+- Workflow Progress: 6-step pipeline visualization (Sites → Keywords → Clusters → Ideas → Content → Published)
+- Quick Actions: 5 navigation shortcuts
+- Key Metrics: 4 cards (Keywords, Articles, Images, Completion %)
+- Credit Usage: Monthly allowance and usage bar
+- Workflow Modules Guide: 8 info cards explaining modules
+- Onboarding: Site creation wizard for new users
+
+### Critical Gaps
+
+| Issue | Impact | Details |
+|-------|--------|---------|
+| **No aggregated API endpoint** | Performance | Makes 6+ sequential API calls with 120ms delays to avoid rate limiting |
+| **Published content count incorrect** | Data accuracy | Cannot distinguish published vs draft content |
+| **Usage Summary is hardcoded** | Misleading | Shows fake "547 credits / $0.34" data |
+| **Recent Activity is hardcoded** | Misleading | Static mock activity that never updates |
+| **No real-time updates** | Stale data | Only refreshes on manual action |
+
+### Missing Professional Features
+
+| Feature | Why Important |
+|---------|---------------|
+| **Needs Attention section** | Users don't know what requires action |
+| **Recent content activity** | No real list of recently created/published content |
+| **Error/warning alerts** | No indication of failed syncs, low credits, config issues |
+| **Pipeline queue depth** | No visibility into items waiting at each stage |
+| **Automation status** | No run status, last run time, or items processed |
+| **Site health/sync status** | No WordPress sync health indicator |
+
+### Workflow Issues
+
+1. **Quick Actions don't adapt to user state** - Shows same 5 actions regardless of workflow stage
+2. **Workflow Completion % is misleading** - Formula doesn't reflect real content-from-keywords ratio
+3. **Modules Guide not dismissible** - 8 large cards always shown, no way to hide
+4. **Chart widget code exists but unused** - Dead code, no trend visualization
+
+### Recommendations
+
+**Priority 1 - Must Fix:**
+- [ ] Create `/v1/dashboard/summary/` aggregated endpoint
+- [ ] Fix published content count (separate published vs draft)
+- [ ] Replace hardcoded usage data with real billing data
+- [ ] Remove or implement real recent activity
+
+**Priority 2 - High Value:**
+- [ ] Add "Needs Attention" section (pending reviews, failed syncs, low credits)
+- [ ] Add actionable pending task count per pipeline stage
+- [ ] Add automation run status display
+- [ ] Add WordPress sync health indicator
+
+**Priority 3 - UX Polish:**
+- [ ] Make Quick Actions contextual based on workflow state
+- [ ] Add loading skeleton
+- [ ] Make Workflow Modules Guide dismissible
+- [ ] Fix or remove trend chart code
+
+---
+
+## 2. SETUP Modules
+
+### 2.1 Add Keywords
+
+**Route:** `/setup/add-keywords`  
+**Files:** `pages/Setup/AddKeywords.tsx`  
+**Tabs:** None (single page)
+
+#### Current Functionality
+- Displays global seed keywords filtered by active site's industry/sector
+- Browse pre-populated keyword database (admin-imported CSV)
+- Add selected keywords to Planner workflow
+- Tracks already-added keywords
+- Bulk selection and bulk add
+- Filters: Search, Country, Difficulty
+- Admin CSV upload capability
+
+#### Functional Gaps
+
+| Issue | Impact |
+|-------|--------|
+| **Sector requirement unclear** | Buttons disabled with no tooltip explaining why |
+| **No keyword research integration** | Can only browse pre-imported seeds, no external discovery |
+| **No manual keyword entry** | Cannot add custom keywords not in seed database |
+| **No keyword details/preview** | No SERP features, trends, or related keywords visible |
+| **No "already added" filter** | Cannot filter to show only not-yet-added keywords |
+
+#### Workflow Issues
+- No "Next Step" CTA after adding keywords → users don't know to go to Planner
+- No keyword count summary (X in workflow, Y available)
+
+#### Recommendations
+- [ ] Add "Next: Plan Your Content →" button after keywords added
+- [ ] Add "Show not-yet-added only" filter
+- [ ] Add manual keyword entry form
+- [ ] Add tooltip explaining disabled state when no sector selected
+- [ ] Add keyword count summary
+
+---
+
+### 2.2 Content Settings
+
+**Route:** `/account/content-settings`  
+**Files:** `pages/account/ContentSettingsPage.tsx`  
+**Tabs:** Content Generation, Publishing, Image Settings
+
+#### Current Functionality
+- **Content Generation:** Append to prompt, default tone, default length
+- **Publishing:** Auto-publish toggle, keep updated toggle
+- **Image Settings:** Quality, style, sizes, format (DALL-E 2/3/Runware)
+
+#### Critical Gaps
+
+| Issue | Impact | Severity |
+|-------|--------|----------|
+| **Content Generation NOT PERSISTED** | Settings appear to save but don't - TODO comments in code | 🔴 Critical |
+| **Publishing NOT PERSISTED** | Same issue - no backend API implemented | 🔴 Critical |
+| **Only Image Settings work** | Only tab with actual API integration | 🔴 Critical |
+| **No per-site settings** | Global only, but multi-site users need site-specific | 🟠 High |
+
+#### Workflow Issues
+- **False confidence**: Users see "Settings saved successfully" but nothing is saved
+- No indication that Content Generation/Publishing tabs are non-functional
+- Disconnected from Thinker prompts (which also affect content generation)
+
+#### Recommendations
+- [ ] 🔴 **CRITICAL:** Implement backend endpoints for Content Generation settings
+- [ ] 🔴 **CRITICAL:** Implement backend endpoints for Publishing settings
+- [ ] Either hide non-functional tabs or mark as "Coming Soon"
+- [ ] Add relationship explanation to Thinker prompts
+- [ ] Consider per-site overrides
+
+---
+
+### 2.3 Sites
+
+**Route:** `/sites`  
+**Files:** `pages/Sites/List.tsx`, `pages/Sites/SiteSettings.tsx`, `pages/Sites/SiteDashboard.tsx`  
+**Tabs:** Site Settings has 3 tabs (General, Integrations, Content Types)
+
+#### Current Functionality
+- List all sites with filtering (search, type, hosting, status)
+- Create sites via WorkflowGuide (requires industry + sectors)
+- Activate/deactivate sites
+- Navigate to site dashboard, content, settings
+- Settings: Name, URL, SEO, WordPress integration, content type mapping
+
+#### Functional Gaps
+
+| Issue | Impact |
+|-------|--------|
+| **Dashboard stats are mock data** | `getSiteDashboardStats` returns hardcoded zeros |
+| **No inline editing** | Must navigate to settings to change site name |
+| **No site cloning** | Cannot duplicate site configuration |
+| **Duplicate pages** | List.tsx and Manage.tsx overlap functionality |
+| **No bulk operations** | Cannot bulk activate/delete sites |
+
+#### Workflow Issues
+- Complex site creation requires industry/sector upfront (users may not know yet)
+- Integration tab default after creation confuses non-technical users
+- No setup progress indicator showing what's configured vs pending
+
+#### Recommendations
+- [ ] Add site setup checklist/progress indicator on cards
+- [ ] Allow site creation without immediate WordPress setup
+- [ ] Add inline editing for site name from list
+- [ ] Remove or merge Manage.tsx if redundant
+- [ ] Implement real site statistics endpoint
+- [ ] Add "Skip integration for now" option
+
+---
+
+### 2.4 Thinker (Admin Only)
+
+**Route:** `/thinker/prompts`  
+**Files:** `pages/Thinker/Prompts.tsx`, `pages/Thinker/AuthorProfiles.tsx`, `pages/Thinker/Strategies.tsx`, `pages/Thinker/ImageTesting.tsx`  
+**Tabs:** Prompts, Author Profiles, Strategies (Coming Soon), Image Testing (Coming Soon)
+
+#### Current Functionality
+- **Prompts:** View/edit AI prompt templates (Clustering, Ideas, Content, Images, etc.)
+- **Author Profiles:** CRUD for author profiles (name, description, tone, language)
+- **Strategies:** Coming Soon placeholder
+- **Image Testing:** Coming Soon placeholder
+
+#### Functional Gaps
+
+| Issue | Impact |
+|-------|--------|
+| **50% Coming Soon** | Strategies + Image Testing are placeholders | 🟠 High |
+| **No prompt testing** | Cannot preview prompt output before saving |
+| **No prompt versioning** | No history or rollback capability |
+| **No per-site prompts** | All prompts global, no site-specific variations |
+| **Author Profiles not connected** | Unclear how/where they're used in workflow |
+| **No variable reference** | Placeholders like `[IGNY8_KEYWORDS]` undocumented |
+
+#### Workflow Issues
+- Admin-only with no explanation of relationship to Content Settings (user-accessible)
+- No prompt categories in UI (hardcoded grouping)
+- Strategies/Image Testing pages offer no value
+
+#### Recommendations
+- [ ] Either complete or hide Strategies and Image Testing
+- [ ] Add prompt testing capability (preview with sample data)
+- [ ] Add prompt version history
+- [ ] Document relationship between Content Settings and Thinker Prompts
+- [ ] Show where Author Profiles are used
+- [ ] Add prompt variable reference documentation
+
+---
+
+### SETUP Cross-Module Issues
+
+| Issue | Impact |
+|-------|--------|
+| **No guided flow** | After setup tasks, no clear path to start content workflow |
+| **Scattered settings** | Content settings split across 3 locations |
+| **No onboarding checklist** | No unified "Setup Complete" indicator |
+
+#### Setup Completion Checklist Needed:
+- [ ] Site created
+- [ ] Industry/Sectors selected
+- [ ] Integration configured (or skipped)
+- [ ] Keywords added
+- [ ] Content settings configured
+
+---
+
+## 3. WORKFLOW Modules
+
+### 3.1 Planner
+
+**Route:** `/planner/keywords`  
+**Files:** `pages/Planner/Keywords.tsx`, `pages/Planner/Clusters.tsx`, `pages/Planner/ClusterView.tsx`, `pages/Planner/Ideas.tsx`, `pages/Planner/KeywordOpportunities.tsx`  
+**Tabs:** Keywords, Clusters, Ideas (in-page navigation)
+
+#### Current Functionality
+- **Keywords:** CRUD, bulk status updates, auto-cluster AI, filters
+- **Clusters:** CRUD, bulk operations, auto-generate ideas AI
+- **Ideas:** CRUD, bulk queue to writer, filters
+- **Flow:** Keywords → Auto-Cluster → Clusters → Auto-Generate Ideas → Ideas → Queue to Writer
+
+#### Functional Gaps
+
+| Issue | Impact | Severity |
+|-------|--------|----------|
+| **KeywordOpportunities hidden** | Page exists at `/planner/keyword-opportunities` but NOT in navigation tabs | 🟠 High |
+| **No "Add to Existing Cluster"** | Auto-cluster creates new clusters only, can't add to existing | 🟡 Medium |
+| **No cluster merge/split** | Cannot combine or split clusters | 🟡 Medium |
+| **No cluster progress indicator** | Can't see which clusters already have ideas generated | 🟠 High |
+| **Ideas missing queued count** | No indicator of how many are pending vs processed | 🟡 Medium |
+
+#### Workflow Issues
+- Seed keyword system (KeywordOpportunities) is orphaned from main workflow
+- Cluster → Ideas transition unclear (which clusters need ideas?)
+- No return path from Ideas to source cluster
+
+#### Recommendations
+- [ ] **Add KeywordOpportunities to Planner tabs** (Critical for onboarding)
+- [ ] Add "Assign to Cluster" bulk action for existing clusters
+- [ ] Add Ideas Count badge on Clusters table
+- [ ] Make cluster name clickable on Ideas page
+
+---
+
+### 3.2 Writer
+
+**Route:** `/writer/tasks`  
+**Files:** `pages/Writer/Tasks.tsx`, `pages/Writer/Drafts.tsx`, `pages/Writer/ContentView.tsx`, `pages/Writer/Images.tsx`, `pages/Writer/Review.tsx`, `pages/Writer/Published.tsx`  
+**Tabs:** Queue, Drafts, Images, Review, Published
+
+#### Current Functionality
+- **Tasks:** CRUD, generate content (row action only), generate images bulk
+- **Drafts:** List drafts, view details, status updates
+- **Images:** Grouped by content, image generation
+- **Review:** Status=review filter, publish to WordPress
+- **Published:** Status=published, WordPress sync status
+
+#### Functional Gaps
+
+| Issue | Impact | Severity |
+|-------|--------|----------|
+| **No bulk content generation** | Must click each row individually, `generate_content` removed from bulk | 🔴 Critical |
+| **No content editing** | ContentView is read-only, no inline editing | 🔴 Critical |
+| **No manual task creation** | Must go through Ideas, can't create task directly | 🟠 High |
+| **No content regeneration** | Can't regenerate with different params, must delete & re-queue | 🟠 High |
+| **Review → Published manual only** | No simple "Mark as Published" for non-WordPress | 🟡 Medium |
+
+#### Workflow Issues
+- Status progression confusion (Draft → Review → Published requires different pages)
+- ContentView missing actions bar (must return to list for actions)
+- Images detached from content workflow
+- No `send_to_linker` action (only `send_to_optimizer`)
+
+#### Recommendations
+- [ ] 🔴 **CRITICAL:** Add bulk content generation with rate limiting
+- [ ] 🔴 **CRITICAL:** Implement inline content editing in ContentView
+- [ ] Add content action bar (Edit, Regenerate, Add Images, Optimize, Link, Publish)
+- [ ] Add `send_to_linker` row action
+- [ ] Add manual task creation capability
+
+---
+
+### 3.3 Automation
+
+**Route:** `/automation`  
+**Files:** `pages/Automation/Dashboard.tsx`  
+**Tabs:** None (single page)
+
+#### Current Functionality
+- Pipeline overview (7 stages: Keywords→Clusters→Ideas→Tasks→Content→Image Prompts→Images)
+- Schedule configuration (frequency, time, enable/disable)
+- Run controls (Run Now, Pause, Resume)
+- Real-time progress polling
+- Metrics display and activity log
+
+#### Functional Gaps
+
+| Issue | Impact |
+|-------|--------|
+| **No stage-by-stage control** | All-or-nothing, can't run individual stages |
+| **No review gate config** | Stage 7 "Review Gate" has no UI to configure rules |
+| **No error recovery** | If stage fails, must rerun entire pipeline |
+| **No batch size config** | Can't throttle items per run |
+| **No dry run/preview** | Can't see what WOULD process before running |
+| **Activity log not filterable** | Can't filter by stage, status, or date |
+
+#### Workflow Issues
+- Credit estimation unclear (labeled "content pieces" but shows credits?)
+- Run history depth unknown, no pagination
+- No indication of manual vs automated items
+
+#### Recommendations
+- [ ] Add stage toggles (enable/disable individual stages)
+- [ ] Add preview mode (show items that will process)
+- [ ] Add retry for failed items (per-item or per-stage)
+- [ ] Add activity log filters
+- [ ] Clarify credit vs content labeling
+
+---
+
+### 3.4 Linker
+
+**Route:** `/linker/content`  
+**Files:** `pages/Linker/Content.tsx`, `pages/Linker/Dashboard.tsx` (not routed)  
+**Tabs:** Content only (Dashboard exists but hidden)
+
+#### Current Functionality
+- Content list with link count and version
+- Single-item "Add Links" button
+- Batch linking capability (code exists, UI unclear)
+- Recent results display (last 3)
+
+#### Functional Gaps
+
+| Issue | Impact |
+|-------|--------|
+| **Dashboard not exposed** | Dashboard.tsx exists but not in navigation |
+| **No content filtering** | Can't filter by status, cluster, or link count |
+| **No bulk selection UI** | `handleBatchLink` exists but no checkboxes |
+| **No link preview/management** | Shows count but can't view/edit actual links |
+| **No "Needs Linking" filter** | Can't find content with 0 links easily |
+
+#### Workflow Issues
+- Completely separate from Writer, requires manual navigation
+- Link results only show "last 3" in session, no persistent history
+- No cluster-based linking
+
+#### Recommendations
+- [ ] Add content filters (status, cluster, "needs linking")
+- [ ] Add bulk selection checkboxes
+- [ ] Add link details modal (show/manage individual links)
+- [ ] Add "Link All New Content" action
+- [ ] Integrate into Writer ContentView
+
+---
+
+### 3.5 Optimizer
+
+**Route:** `/optimizer/content`  
+**Files:** `pages/Optimizer/Content.tsx`, `pages/Optimizer/AnalysisPreview.tsx` (orphaned), `pages/Optimizer/Dashboard.tsx` (not routed)  
+**Tabs:** Content only (Dashboard exists but hidden)
+
+#### Current Functionality
+- Content list with optimization scores
+- Entry point selection (auto, writer, wordpress, external, manual)
+- Single-item and batch optimize
+- Score display (overall, SEO, readability, engagement)
+
+#### Functional Gaps
+
+| Issue | Impact |
+|-------|--------|
+| **Dashboard not exposed** | Dashboard.tsx exists but not in navigation |
+| **AnalysisPreview orphaned** | Route exists but no UI link to it |
+| **Limited filtering** | Only source/search, no score range filter |
+| **No optimization history** | No before/after comparison |
+| **No optimization settings** | Can't configure what aspects to optimize |
+| **No suggested actions** | Scores show but no recommendations |
+
+#### Workflow Issues
+- Must navigate to Optimizer separately (disconnected from Writer)
+- Analysis vs Optimize confusion (analyze never used)
+- No re-optimization control
+
+#### Recommendations
+- [ ] Add Analysis Preview link ("Preview Scores" action)
+- [ ] Add score-based filters ("Score < 70", "Needs SEO")
+- [ ] Add optimization recommendations
+- [ ] Add "Optimize All Below Threshold" bulk action
+- [ ] Integrate into Writer (auto-analyze during draft)
+
+---
+
+### WORKFLOW Cross-Module Issues
+
+| Issue | Impact |
+|-------|--------|
+| **No Planner → Writer visibility** | After queuing, must manually switch modules |
+| **No Writer → Linker integration** | No "Add Links" button in content view |
+| **No Writer → Optimizer integration** | Optimize exists but no score preview |
+| **No cross-module notifications** | User doesn't know when AI tasks complete |
+| **No breadcrumb navigation** | Can't see full workflow path (Cluster → Idea → Task → Content) |
+
+#### Cross-Module Recommendations
+- [ ] Add global notification system for completed tasks
+- [ ] Add breadcrumb navigation showing workflow path
+- [ ] Add "Next Step" suggestions after each action
+- [ ] Unify content detail view with ALL actions available
+- [ ] Add workflow progress indicator
+
+---
+
+## 4. ACCOUNT Modules
+
+### 4.1 Account Settings
+
+**Route:** `/account/settings`  
+**Files:** `pages/account/AccountSettingsPage.tsx`  
+**Tabs:** Account, Profile, Team
+
+#### Current Functionality
+- **Account Tab:** Organization name, billing email, full billing address, tax ID/VAT
+- **Profile Tab:** First/last name, email, phone, timezone, language, notifications, security
+- **Team Tab:** List team members, invite via email, remove members, role display
+
+#### Functional Gaps
+
+| Issue | Impact | Severity |
+|-------|--------|----------|
+| **Profile NOT connected to API** | Form saves nowhere - fake save with timeout | 🔴 Critical |
+| **No role assignment on invite** | Only email/name collected, no role dropdown | 🟠 High |
+| **No role editing for members** | Cannot change Member to Admin or vice versa | 🟠 High |
+| **Change Password does nothing** | Static button with no functionality | 🔴 Critical |
+| **No email verification** | Can change email without verification | 🟠 High |
+| **No 2FA option** | Security section minimal | 🟡 Medium |
+| **No account deletion** | Cannot close account | 🟡 Medium |
+| **No session management** | Cannot view/revoke active sessions | 🟡 Medium |
+
+#### Workflow Issues
+- Orphaned `TeamManagement.tsx` file exists (395 lines, not routed)
+- Inconsistent role system (shows Admin/Member but backend returns `is_admin` boolean)
+- No pending invitation status or resend capability
+- No team member limit enforcement display
+
+#### Recommendations
+- [ ] 🔴 **CRITICAL:** Implement profile API and connect Profile tab
+- [ ] 🔴 **CRITICAL:** Implement password change functionality
+- [ ] Add role selection to team invitation
+- [ ] Add invitation management (resend, cancel pending)
+- [ ] Show team member count vs plan limit
+- [ ] Delete orphaned `TeamManagement.tsx`
+
+---
+
+### 4.2 Plans & Billing
+
+**Route:** `/account/plans`  
+**Files:** `pages/account/PlansAndBillingPage.tsx`, `pages/Billing/CreditPurchase.tsx`  
+**Tabs:** Current Plan, Upgrade Plan, History
+
+#### Current Functionality
+- **Current Plan:** Plan name, status, credits, balance, renewal date, features
+- **Upgrade:** Pricing table, plan comparison, change policy
+- **History:** Invoices with PDF download, payments, payment methods
+
+#### Functional Gaps
+
+| Issue | Impact |
+|-------|--------|
+| **No proration preview** | Doesn't show prorated amount before upgrade |
+| **Credit purchase not linked** | `/billing/credits` exists separately but not linked |
+| **Cancellation is immediate** | No reason collection, no retention offers |
+| **No payment failure retry** | If payment fails, no retry UI |
+| **No downgrade proration display** | Policy exists but no calculation shown |
+
+#### Workflow Issues
+- Throttling errors surface directly to users ("Request was throttled. Retrying...")
+- Cancel flow has no confirmation dialog
+- Payment method supports bank_transfer, manual, stripe, paypal but UI only shows some
+- No billing cycle visualization (renewal date not prominent)
+
+#### Recommendations
+- [ ] Add proration preview before plan changes
+- [ ] Add confirmation dialog for cancellation
+- [ ] Link credit purchase from this page
+- [ ] Add cancellation reason collection
+- [ ] Clean up throttling messages (use spinner)
+
+---
+
+### 4.3 Usage
+
+**Route:** `/account/usage`  
+**Files:** `pages/account/UsageAnalyticsPage.tsx`, `pages/account/UsageLimits.tsx`, `pages/account/CreditActivity.tsx`  
+**Tabs:** Your Limits & Usage, Credit History, API Activity
+
+#### Current Functionality
+- **Quick Stats:** Credits left, used this month, monthly limit, usage %
+- **Limits:** Hard limits (sites, users, keywords, clusters) + Monthly limits
+- **Credit History:** Transaction log with type, amount, description
+- **API Activity:** Call statistics, endpoint breakdown
+
+#### Critical Gaps
+
+| Issue | Impact | Severity |
+|-------|--------|----------|
+| **API Activity is HARDCODED** | Shows fake static values (1,234, 567, 342) not real data | 🔴 Critical |
+| **Success rate is fake** | Hardcoded 98.5% | 🔴 Critical |
+| **No usage alerts** | No notification when approaching limits | 🟠 High |
+| **No per-site usage** | Can't see which site consumed what | 🟠 High |
+| **No per-user usage** | Can't see team member individual usage | 🟠 High |
+| **No usage export** | Cannot download usage report | 🟡 Medium |
+| **No usage forecasting** | No "you'll run out in X days" | 🟡 Medium |
+
+#### Workflow Issues
+- No actionable insights (doesn't suggest upgrade when hitting limits)
+- Credit history lacks context (no link to what was generated)
+- Disconnected from billing (separate page to upgrade)
+
+#### Recommendations
+- [ ] 🔴 **CRITICAL:** Implement actual API activity tracking or hide tab
+- [ ] Add usage alerts configuration (email at 80%, 90%, 100%)
+- [ ] Add per-site/per-user usage breakdown
+- [ ] Add "Upgrade" CTA when limits approaching
+- [ ] Add usage export functionality
+
+---
+
+### 4.4 AI Models (Admin Only)
+
+**Route:** `/settings/integration`  
+**Files:** `pages/Settings/IntegrationPage.tsx`  
+**Sections:** OpenAI Integration, Runware Integration, Image Generation, Site Integrations
+
+#### Current Functionality
+- **OpenAI:** Enable/disable, model selection, connection testing, validation
+- **Runware:** Enable/disable, model selection, connection testing
+- **Image Generation:** Service selection, model selection, image settings
+- **Testing:** Generate test images with preview
+- **Site Integrations:** Connected site management
+
+#### Functional Gaps
+
+| Issue | Impact | Severity |
+|-------|--------|----------|
+| **Fictional GPT model names** | Shows GPT-5.1, GPT-5.2 which don't exist | 🔴 Critical |
+| **No fallback configuration** | If OpenAI fails, no automatic Runware fallback | 🟠 High |
+| **No cost tracking** | Can't see integration costs | 🟡 Medium |
+| **No integration health history** | Only current status, no uptime history | 🟡 Medium |
+| **No API key rotation** | Can't rotate keys without disabling | 🟡 Medium |
+| **No audit log** | No record of when settings changed | 🟠 High |
+
+#### Workflow Issues
+- Admin-only but affects all users (no scope clarification)
+- Page mixes LLM models, image generation, AND site integrations
+- Complex modal nesting (settings, details, form all separate)
+- No preview of cost impact when changing models
+
+#### Recommendations
+- [ ] 🔴 **CRITICAL:** Fix GPT model names to actual models (gpt-4-turbo, gpt-4, gpt-3.5-turbo)
+- [ ] Add integration change audit logging
+- [ ] Add cost estimation when changing models
+- [ ] Consider separating site integrations to own page
+- [ ] Add fallback configuration
+
+---
+
+### ACCOUNT Cross-Module Issues
+
+| Issue | Impact |
+|-------|--------|
+| **Multiple credit balance sources** | Plans, Usage, billingStore all fetch independently |
+| **Fragmented billing pages** | PlansAndBillingPage, CreditPurchase, legacy routes |
+| **Legacy routes still exist** | `/billing/overview`, `/team`, `/profile` all redirect |
+| **No audit log across modules** | No record of who changed what when |
+| **No notification preferences** | Cannot configure billing/usage email alerts |
+
+---
+
+## 5. HELP Module
+
+### 5.1 Help & Docs
+
+**Route:** `/help`  
+**Files:** `pages/Help/HelpCenter.tsx`, `pages/Help/Documentation.tsx` (placeholder), `pages/Help/SystemTesting.tsx` (placeholder), `pages/Help/FunctionTesting.tsx` (placeholder)  
+**Routes:** `/help`, `/help/docs`, `/help/system-testing`, `/help/function-testing`
+
+#### Current Functionality
+- Table of Contents with jump-to-section navigation
+- Getting Started: Quick Start Guide, Workflow Overview
+- Planner Module: Keywords, Clusters, Ideas documentation
+- Writer Module: Tasks, Content, Images documentation
+- Automation Setup overview
+- FAQ section (~20 questions)
+- Support CTA buttons (non-functional)
+
+#### Critical Gaps
+
+| Issue | Impact | Severity |
+|-------|--------|----------|
+| **Support dropdown link broken** | Goes to `/profile` which has NO route - 404 | 🔴 Critical |
+| **Contact Support button does nothing** | `<button>` with no onClick handler | 🔴 Critical |
+| **Feature Request button does nothing** | Same - no functionality | 🔴 Critical |
+| **3 of 4 help pages empty** | `/help/docs`, `/help/system-testing`, `/help/function-testing` are placeholders | 🟠 High |
+| **No actual support channel** | No email, chat, or ticket system | 🔴 Critical |
+
+#### Missing Documentation
+
+| Module | Status | Coverage |
+|--------|--------|----------|
+| Thinker | Active | 1 FAQ only - no section |
+| Linker | Optional | Not mentioned |
+| Optimizer | Optional | Not mentioned |
+| Publisher | Active | Not documented |
+| Sites/Site Builder | Active | Not documented |
+| Billing/Credits | Active | 1 FAQ only |
+| Account Settings | Active | Not documented |
+
+#### Workflow Issues
+- **No search functionality** - Must scroll or use TOC
+- **No contextual help** - No in-app tooltips or "?" icons
+- **No help sub-navigation** - Routes exist but no tabs visible
+- **Stale content risk** - Hardcoded in TSX, requires deployment to update
+
+#### Recommendations
+- [ ] 🔴 **CRITICAL:** Fix Support dropdown link (`/profile` → `/help` or support page)
+- [ ] 🔴 **CRITICAL:** Implement Contact Support (mailto: or external support URL)
+- [ ] 🔴 **CRITICAL:** Add WordPress setup guide
+- [ ] Document missing modules (Sites, Publisher, Thinker)
+- [ ] Create Troubleshooting guide
+- [ ] Add search functionality
+- [ ] Add credit cost documentation
+- [ ] Remove or implement placeholder pages
+
+---
+
+## 6. Sidebar & Navigation
+
+**File:** `layout/AppSidebar.tsx`
+
+### Current Structure
+
+```
+Dashboard (standalone)
+├─ SETUP
+│   ├─ Add Keywords → /setup/add-keywords
+│   ├─ Content Settings → /account/content-settings
+│   ├─ Sites (if site_builder enabled) → /sites
+│   └─ Thinker (admin only, if thinker enabled) → /thinker/prompts
+├─ WORKFLOW
+│   ├─ Planner (if planner enabled) → /planner/keywords
+│   ├─ Writer (if writer enabled) → /writer/tasks
+│   ├─ Automation (if automation enabled) → /automation
+│   ├─ Linker (if linker enabled) → /linker/content
+│   └─ Optimizer (if optimizer enabled) → /optimizer/content
+├─ ACCOUNT
+│   ├─ Account Settings → /account/settings
+│   ├─ Plans & Billing → /account/plans
+│   ├─ Usage → /account/usage
+│   └─ AI Models (admin only) → /settings/integration
+└─ HELP
+    └─ Help & Docs → /help
+```
+
+### Navigation Gaps
+
+| Issue | Impact |
+|-------|--------|
+| **KeywordOpportunities not in navigation** | `/planner/keyword-opportunities` exists but not accessible |
+| **Linker Dashboard not exposed** | `/linker/dashboard` exists but only `/linker/content` in sidebar |
+| **Optimizer Dashboard not exposed** | `/optimizer/dashboard` exists but only `/optimizer/content` in sidebar |
+| **Help sub-pages hidden** | `/help/docs`, `/help/system-testing`, `/help/function-testing` not navigable |
+| **Credit purchase not in sidebar** | `/billing/credits` exists but not accessible from sidebar |
+
+### Menu Order Issues
+
+| Current Order | Recommended Order | Reason |
+|---------------|-------------------|--------|
+| Add Keywords first in SETUP | Sites first | User should create site before adding keywords |
+| Content Settings before Sites | Content Settings last | Configure after site is set up |
+| Planner before Writer | Planner before Writer ✓ | Correct - follows workflow |
+
+### Missing Navigation Features
+
+| Feature | Impact |
+|---------|--------|
+| **No breadcrumb navigation** | User can't see full path (Cluster → Idea → Task → Content) |
+| **No "Next Step" guidance** | After completing action, user doesn't know where to go |
+| **No active section highlighting** | Sidebar doesn't show which section is active |
+| **No keyboard navigation** | Can't navigate sidebar with keyboard |
+| **No recent pages** | Can't quickly return to recently visited pages |
+
+### Recommendations
+- [ ] Add KeywordOpportunities to Planner sub-navigation
+- [ ] Consider reordering SETUP: Sites → Add Keywords → Content Settings → Thinker
+- [ ] Add breadcrumb navigation component
+- [ ] Add "What's Next?" suggestions after key actions
+- [ ] Consider exposing Dashboard pages for Linker/Optimizer
+
+---
+
+## 7. Summary & Prioritization
+
+### 🔴 CRITICAL - Must Fix Before Launch
+
+| # | Issue | Module | Type |
+|---|-------|--------|------|
+| 1 | **Content Generation/Publishing settings NOT SAVED** | Content Settings | Data Loss |
+| 2 | **Profile tab NOT connected to API** | Account Settings | Data Loss |
+| 3 | **Password change does nothing** | Account Settings | Security |
+| 4 | **API Activity data is HARDCODED fake** | Usage | Misleading Data |
+| 5 | **Support buttons do nothing** | Help | No Support Channel |
+| 6 | **Support dropdown goes to 404** | Help | Broken Link |
+| 7 | **Fictional GPT model names (GPT-5.1, 5.2)** | AI Models | Data Integrity |
+| 8 | **No bulk content generation** | Writer | Core Workflow Blocked |
+| 9 | **No content editing capability** | Writer | Core Workflow Blocked |
+| 10 | **Dashboard has hardcoded usage/activity data** | Dashboard | Misleading Data |
+
+### 🟠 HIGH - Significant Impact on User Experience
+
+| # | Issue | Module |
+|---|-------|--------|
+| 11 | No role assignment/editing for team members | Account Settings |
+| 12 | No proration preview for plan changes | Plans & Billing |
+| 13 | No cancellation confirmation dialog | Plans & Billing |
+| 14 | KeywordOpportunities hidden from navigation | Planner |
+| 15 | No cluster progress indicator (which have ideas) | Planner |
+| 16 | No content regeneration capability | Writer |
+| 17 | 3 of 4 help pages are empty placeholders | Help |
+| 18 | No dashboard API endpoint (6+ sequential calls) | Dashboard |
+| 19 | Published content count incorrect | Dashboard |
+| 20 | No "Needs Attention" section | Dashboard |
+| 21 | No usage alerts when approaching limits | Usage |
+| 22 | Sites Dashboard shows mock/zero data | Sites |
+| 23 | Thinker has 50% "Coming Soon" pages | Thinker |
+| 24 | No integration audit logging | AI Models |
+
+### 🟡 MEDIUM - Professional Polish Needed
+
+| # | Issue | Module |
+|---|-------|--------|
+| 25 | No manual keyword entry | Add Keywords |
+| 26 | No "Next Step" CTA after actions | Add Keywords, Planner |
+| 27 | No pending invitation management | Account Settings |
+| 28 | No 2FA option | Account Settings |
+| 29 | No per-site/per-user usage breakdown | Usage |
+| 30 | No search in Help | Help |
+| 31 | Missing module documentation (Sites, Thinker, etc.) | Help |
+| 32 | Automation has no stage-by-stage control | Automation |
+| 33 | Linker has no content filtering | Linker |
+| 34 | Optimizer has no score-based filtering | Optimizer |
+| 35 | No cross-module notifications | All |
+| 36 | No breadcrumb navigation | All |
+| 37 | Quick Actions don't adapt to user state | Dashboard |
+
+---
+
+### Implementation Phases
+
+#### Phase 1: Critical Fixes (Must Complete)
+Focus: Data integrity, security, core functionality
+- Fix Content Settings API (Content Gen + Publishing tabs)
+- Fix Profile API connection
+- Implement password change
+- Remove/fix hardcoded API Activity data
+- Implement support channel (mailto or external URL)
+- Fix Support dropdown link
+- Fix GPT model names
+- Add bulk content generation
+- Add inline content editing
+
+#### Phase 2: Core Workflow Improvements
+Focus: User workflow efficiency
+- Add dashboard aggregated API endpoint
+- Add "Needs Attention" widget
+- Add KeywordOpportunities to navigation
+- Add cluster progress indicators
+- Add content regeneration
+- Add team role management
+- Add plan change proration preview
+- Add cancellation confirmation
+
+#### Phase 3: Professional Polish
+Focus: Edge cases and advanced features
+- Complete Help documentation
+- Add usage alerts
+- Add per-site usage breakdown
+- Add stage controls to Automation
+- Add filtering to Linker/Optimizer
+- Add breadcrumb navigation
+- Add cross-module notifications
+
+---
+
+### Quick Wins (< 1 hour each)
+
+1. Fix Support dropdown link (`/profile` → `/help`)
+2. Add mailto: to Contact Support button
+3. Fix GPT model names (rename to actual models)
+4. Add cancellation confirmation dialog
+5. Remove/hide API Activity tab until implemented
+6. Add KeywordOpportunities to Planner tabs
+7. Fix profile save to show "Coming Soon" instead of fake save
+
+---
+
+### Files to Delete (Orphaned/Duplicate)
+
+| File | Reason |
+|------|--------|
+| `pages/account/TeamManagement.tsx` | Orphaned, functionality in AccountSettingsPage |
+| `pages/Sites/Manage.tsx` | Duplicate of List.tsx |
+| `pages/Help/Documentation.tsx` | Empty placeholder |
+| `pages/Help/SystemTesting.tsx` | Empty placeholder |
+| `pages/Help/FunctionTesting.tsx` | Empty placeholder |
+| `pages/Thinker/Strategies.tsx` | Empty "Coming Soon" |
+| `pages/Thinker/ImageTesting.tsx` | Empty "Coming Soon" |
+
+---
+
+**Total Issues Identified:** 37  
+**Critical:** 10  
+**High:** 14  
+**Medium:** 13
+
--- a/to-do-s/PRICING-SIMPLIFICATION-ANALYSIS.md
+++ b/to-do-s/PRICING-SIMPLIFICATION-ANALYSIS.md
@@ -0,0 +1,308 @@
+# IGNY8 Pricing System - Final Simplified Plan
+
+**Date:** December 26, 2025  
+**Status:** APPROVED DIRECTION
+
+---
+
+## 1. Current System Assessment ✅
+
+The existing token-based credit system is **correct and safe**:
+- ✅ `CreditCostConfig` with `tokens_per_credit` ratio per operation
+- ✅ `min_credits` per operation (floor protection)
+- ✅ Actual tokens calculated after AI call (accurate margin)
+- ✅ Model-aware pricing (different models = different costs)
+
+**Keep this system. Just simplify the limits and UI.**
+
+---
+
+## 2. Actual Cost Analysis (From Production Data)
+
+### Per-Article Cost Breakdown (GPT-4.1 pricing)
+
+| Stage | Input Tokens | Output Tokens | Actual Cost |
+|-------|--------------|---------------|-------------|
+| Clustering (per article share*) | ~400 | ~400 | **$0.005** |
+| Idea Generation (per article share*) | ~900 | ~1000 | **$0.012** |
+| Content Writing | 2500 | 3500 | **$0.041** |
+| Image Prompt Extraction | 500 | 1100 | **$0.012** |
+| **Text Subtotal** | | | **$0.07** |
+| Images (3 avg @ $0.04) | | | **$0.12** |
+| **TOTAL PER ARTICLE** | | | **$0.19** |
+
+*With 6 images (max): **$0.31 per article**
+
+### Target Markup: 10-15x
+
+| Scenario | Our Cost | 10x Price | 15x Price |
+|----------|----------|-----------|-----------|
+| Article (3 images) | $0.19 | $1.90 | $2.85 |
+| Article (6 images) | $0.31 | $3.10 | $4.65 |
+
+---
+
+## 3. Simplified Credit Pricing (10x Markup)
+
+### 3.1 Credit Cost per Operation
+
+Using **1 credit = $0.01** and **10x markup**:
+
+| Operation | Actual Cost | Target Price | Credits |
+|-----------|-------------|--------------|---------|
+| Clustering | $0.005 | $0.05 | **5** |
+| Idea Generation | $0.012 | $0.12 | **10** |
+| Content Writing | $0.041 | $0.41 | **40** |
+| Image Prompts | $0.012 | $0.12 | **10** |
+| Image (per image) | $0.04 | $0.40 | **40** |
+| Linking | $0.003 | $0.03 | **3** |
+| Optimization | $0.005 | $0.05 | **5** |
+
+### 3.2 Full Article Workflow Cost
+
+| Workflow | Calculation | Total Credits |
+|----------|-------------|---------------|
+| Text only | 5 + 10 + 40 + 10 = 65 | **65 credits** |
+| + 3 images | 65 + (3 × 40) = 185 | **185 credits** |
+| + 6 images | 65 + (6 × 40) = 305 | **305 credits** |
+| + linking + optimization | +3 +5 = +8 | **+8 credits** |
+
+**Typical article: ~200 credits = $2.00** (at 10x margin)
+
+---
+
+## 4. Simplified Plan Structure
+
+### 4.1 Remove All Limits Except Keywords
+
+**DELETE:**
+- ❌ max_content_ideas
+- ❌ max_content_words
+- ❌ max_images_basic
+- ❌ max_images_premium
+- ❌ max_image_prompts
+- ❌ max_clusters (soft limit via credits)
+- ❌ All usage tracking fields
+
+**KEEP:**
+- ✅ Credits (token-based, monthly allocation)
+- ✅ max_keywords (storage limit, defines plan tier)
+- ✅ max_sites, max_users (account management)
+
+### 4.2 New Plan Tiers
+
+| Plan | Price | Credits/Month | Keywords | Sites | Users | ~Articles |
+|------|-------|---------------|----------|-------|-------|-----------|
+| **Free** | $0 | 200 | 100 | 1 | 1 | ~1 |
+| **Starter** | $29 | 3,000 | 1,000 | 3 | 3 | ~15 |
+| **Growth** | $79 | 10,000 | 5,000 | 10 | 10 | ~50 |
+| **Scale** | $199 | 30,000 | Unlimited | ∞ | ∞ | ~150 |
+
+**Simple value proposition:**
+- Starter: ~15 full articles/month for $29 (~$2/article)
+- Growth: ~50 full articles/month for $79 (~$1.60/article)
+- Scale: ~150 full articles/month for $199 (~$1.33/article)
+
+### 4.3 Credit Top-Up Pricing
+
+| Package | Credits | Price | Per Credit |
+|---------|---------|-------|------------|
+| Small | 500 | $7 | $0.014 |
+| Medium | 2,000 | $25 | $0.0125 |
+| Large | 5,000 | $55 | $0.011 |
+| Bulk | 15,000 | $150 | $0.01 |
+
+---
+
+## 5. Content Length Feature (New)
+
+### 5.1 Add Word Count Selection
+
+**Content Settings (Site-level default):**
+```
+Target Article Length: [Short ~800] [Medium ~1500] [Long ~2500] [Custom: ___]
+```
+
+**Idea Generation (per-idea):**
+- Include target word count in idea brief
+- AI considers length when generating outline
+
+**Content Generation (per-content):**
+- Pass word count to prompt
+- Affects token usage (longer = more credits)
+
+### 5.2 Credit Adjustment for Length
+
+| Length | Words | Token Estimate | Credits |
+|--------|-------|----------------|---------|
+| Short | ~800 | 2000 | 25 |
+| Medium | ~1500 | 3500 | 40 |
+| Long | ~2500 | 5500 | 60 |
+| Extra Long | ~4000 | 8000 | 90 |
+
+**User sees:** "Short article: ~150 credits, Long article: ~250 credits"
+
+---
+
+## 6. Implementation Plan
+
+### Phase 1: Backend Updates (Day 1-2)
+
+**6.1 Update CreditCostConfig values:**
+
+```python
+# New fixed credit costs (min_credits = display value)
+CREDIT_CONFIGS = {
+    'clustering': {'tokens_per_credit': 160, 'min_credits': 5},
+    'idea_generation': {'tokens_per_credit': 190, 'min_credits': 10},
+    'content_generation': {'tokens_per_credit': 150, 'min_credits': 25},  # Base for short
+    'image_prompt_extraction': {'tokens_per_credit': 160, 'min_credits': 10},
+    'image_generation': {'tokens_per_credit': 1, 'min_credits': 40},  # Fixed per image
+    'linking': {'tokens_per_credit': 300, 'min_credits': 3},
+    'optimization': {'tokens_per_credit': 200, 'min_credits': 5},
+}
+```
+
+**6.2 Remove monthly limit fields:**
+
+```python
+# Plan model - DELETE these fields
+- max_content_ideas
+- max_content_words
+- max_images_basic
+- max_images_premium
+- max_image_prompts
+
+# Account model - DELETE these fields
+- usage_content_ideas
+- usage_content_words
+- usage_images_basic
+- usage_images_premium
+- usage_image_prompts
+- usage_period_start
+- usage_period_end
+```
+
+**6.3 Remove LimitService monthly methods:**
+- Delete `check_monthly_limit()`
+- Delete `increment_usage()`
+- Delete monthly reset task
+- Keep `check_hard_limit()` for sites/users/keywords
+
+### Phase 2: Content Length Feature (Day 2-3)
+
+**6.4 Add ContentSettings.target_word_count:**
+
+```python
+class ContentSettings(models.Model):
+    # ... existing fields ...
+    target_word_count = models.IntegerField(
+        default=1500,
+        choices=[(800, 'Short'), (1500, 'Medium'), (2500, 'Long'), (4000, 'Extra Long')],
+        help_text="Default target word count for articles"
+    )
+```
+
+**6.5 Update AI prompts:**
+- `generate_ideas.py` - Include word count in idea brief
+- `generate_content.py` - Pass word count target
+
+### Phase 3: Frontend Updates (Day 3-4)
+
+**6.6 Update Content Settings page:**
+- Add word count selector
+
+**6.7 Update Usage page:**
+- Show credits only (remove monthly limit bars)
+- Show keywords used vs limit
+- Show simple cost reference
+
+**6.8 Fix/Replace CreditCostsPanel.tsx:**
+- Show fixed credit costs (not token-based confusion)
+- Simple table: "Content: 40 credits, Image: 40 credits"
+
+**6.9 Update Pricing page:**
+- New plan structure
+- "~X articles/month" messaging
+
+### Phase 4: Migration & Cleanup (Day 4-5)
+
+**6.10 Database migration:**
+- Remove deprecated fields
+- Update existing plans to new structure
+
+**6.11 Clean up dead code:**
+- Remove LimitService monthly tracking
+- Remove usage increment calls in services
+
+---
+
+## 7. User Experience (After Simplification)
+
+### What User Sees:
+
+**Dashboard:**
+```
+Credits: 2,847 / 3,000 remaining
+Keywords: 234 / 1,000
+```
+
+**Before generating content:**
+```
+Estimated cost: ~185 credits
+- Content (medium): 40 credits
+- Image prompts: 10 credits  
+- 3 images: 120 credits
+- Clustering share: ~5 credits
+- Ideas share: ~10 credits
+```
+
+**Content Settings:**
+```
+Article Length: [Short] [Medium ✓] [Long] [Extra Long]
+Images per Article: [3 ▼]
+```
+
+### What Admin Sees:
+
+**Plans admin:**
+- Credits/month
+- Keywords limit
+- Sites/Users limits
+- Price
+
+**No more:**
+- 5 different monthly limit fields
+- Usage tracking complexity
+- Monthly reset management
+
+---
+
+## 8. Summary
+
+| Before | After |
+|--------|-------|
+| Credits + 5 monthly limits | Credits only |
+| 9 limit fields per plan | 3 limit fields (credits, keywords, sites) |
+| 5 usage tracking fields | 1 field (credits balance) |
+| Complex monthly resets | Simple credit allocation |
+| Unpredictable costs | Clear cost estimates |
+| No length control | Word count selection |
+
+**Result:**
+- ✅ Safe margins (token-based calculation preserved)
+- ✅ Simple for user (one number to track)
+- ✅ Simple for admin (fewer fields to manage)
+- ✅ Predictable (show estimated costs upfront)
+- ✅ Flexible (manual or automation workflows work same way)
+
+---
+
+## 9. Immediate Actions
+
+1. **Update CreditCostConfig** in database with new values
+2. **Add target_word_count** to ContentSettings model
+3. **Update prompts** to include word count
+4. **Remove monthly limit checks** from services
+5. **Update frontend** Usage page and CreditCostsPanel
+6. **Migration** to remove deprecated fields
--- a/to-do-s/PRODUCTION-READINESS-PLAN.md
+++ b/to-do-s/PRODUCTION-READINESS-PLAN.md
@@ -0,0 +1,341 @@
+# Production Readiness Plan
+
+**Created:** December 25, 2025  
+**Last Updated:** December 25, 2025  
+**Goal:** Ship to production with simplified UI while keeping backend unchanged  
+**Status:** ✅ CORE CHANGES COMPLETE
+
+---
+
+## Implementation Status
+
+### ✅ Completed Changes
+
+| File | Change | Status |
+|------|--------|--------|
+| `layout/AppLayout.tsx` | Header shows "Content: X/Y" | ✅ Done |
+| `pages/Dashboard/Home.tsx` | Credit widget → "Content This Month" | ✅ Done |
+| `pages/Help/Help.tsx` | FAQ updated | ✅ Done |
+| `pages/Automation/AutomationPage.tsx` | Error messages updated | ✅ Done |
+| `components/auth/SignUpForm*.tsx` | 3 files - removed credit text | ✅ Done |
+| `pages/Settings/Plans.tsx` | Shows "Pages/Articles per month" | ✅ Done |
+| `pages/account/PlansAndBillingPage.tsx` | Tabs simplified, Purchase Credits hidden | ✅ Done |
+| `pages/Payment.tsx` | Updated pricing display | ✅ Done |
+| `pages/Optimizer/Dashboard.tsx` | Removed credits card | ✅ Done |
+| `pages/Settings/CreditsAndBilling.tsx` | Renamed to "Usage & Billing" | ✅ Done |
+| `pages/Billing/Credits.tsx` | Renamed to "Content Usage" | ✅ Done |
+| `components/billing/BillingBalancePanel.tsx` | "Usage Overview" | ✅ Done |
+| `components/dashboard/CreditBalanceWidget.tsx` | "Content Usage" | ✅ Done |
+| `components/dashboard/UsageChartWidget.tsx` | "Content Created" | ✅ Done |
+| `components/ui/pricing-table/index.tsx` | "Content pieces/month" | ✅ Done |
+| `marketing/pages/Pricing.tsx` | "Usage Dashboard" | ✅ Done |
+| `docs/40-WORKFLOWS/CREDIT-SYSTEM.md` | Updated docs | ✅ Done |
+
+### Hidden from Regular Users
+
+| Feature | Status |
+|---------|--------|
+| Purchase Credits page | Hidden (commented out) |
+| Credit Cost Breakdown | Hidden |
+| Credit Packages grid | Hidden |
+| Detailed credit analytics | Hidden |
+
+---
+
+## The Strategy: Abstraction Layer
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     WHAT CHANGES                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  BACKEND (NO CHANGES)          FRONTEND (CHANGES)               │
+│  ──────────────────────        ──────────────────               │
+│  • Credit deduction ✓          • Hide credit numbers ✅         │
+│  • Usage tracking ✓            • Show "Content Pieces" ✅       │
+│  • Plan limits ✓               • Simplify terminology ✅        │
+│  • API responses ✓             • Remove purchase credits ✅     │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Key Insight:** Backend tracks `content_credits`. User sees this as "Content Pieces".  
+No conversion needed - just rename the display.
+
+---
+
+## Phase 1: Core Abstraction (billingStore)
+
+### File: `frontend/src/store/billingStore.ts`
+
+Add computed properties that translate credits → content pieces:
+
+```typescript
+// Add to BillingState interface
+interface BillingState {
+  // ... existing ...
+  
+  // Computed for simple UI
+  getContentPiecesRemaining: () => number;
+  getContentPiecesUsed: () => number;
+  getContentPiecesTotal: () => number;
+}
+
+// In the store
+getContentPiecesRemaining: () => {
+  const balance = get().balance;
+  // content_credits = content pieces (1:1 mapping)
+  return balance?.credits_remaining ?? 0;
+},
+
+getContentPiecesUsed: () => {
+  const balance = get().balance;
+  return balance?.credits_used_this_month ?? 0;
+},
+
+getContentPiecesTotal: () => {
+  const balance = get().balance;
+  return balance?.plan_credits_per_month ?? 0;
+},
+```
+
+---
+
+## Phase 2: Header Metrics Update
+
+### File: `frontend/src/layout/AppLayout.tsx`
+
+**Current (line ~138):**
+```typescript
+{
+  label: 'Credits',
+  value: balance.credits.toLocaleString(),
+  // ...
+}
+```
+
+**Change to:**
+```typescript
+{
+  label: 'Content',
+  value: `${balance.credits_remaining}/${balance.plan_credits_per_month}`,
+  tooltip: 'Content pieces remaining this month'
+}
+```
+
+---
+
+## Phase 3: Pages to Update
+
+### Priority 1: Remove/Hide These Pages
+
+| Page | File | Action |
+|------|------|--------|
+| Purchase Credits | `pages/account/PurchaseCreditsPage.tsx` | Hide from nav, keep for admin |
+| Credits Tab | `pages/Billing/Credits.tsx` | Remove tab from billing |
+| Credits & Billing | `pages/Settings/CreditsAndBilling.tsx` | Rename to "Usage" |
+
+### Priority 2: Update Text/Labels
+
+| Page | File | Changes |
+|------|------|---------|
+| Dashboard | `pages/Dashboard/Home.tsx` | "Credits" → "Content Pieces" |
+| Plans & Billing | `pages/account/PlansAndBillingPage.tsx` | Remove Credits tab, simplify |
+| Usage Analytics | `pages/account/UsageAnalyticsPage.tsx` | "Credits" → "Content" |
+| Automation | `pages/Automation/AutomationPage.tsx` | "credits" → "content pieces" |
+| Help | `pages/Help/Help.tsx` | Update FAQ text |
+
+### Priority 3: Marketing Pages
+
+| Page | File | Changes |
+|------|------|---------|
+| Pricing | `marketing/pages/Pricing.tsx` | Already updated per session |
+| Waitlist | `marketing/pages/Waitlist.tsx` | Update copy |
+
+---
+
+## Phase 4: Components to Update
+
+### High Priority
+
+| Component | File | Changes |
+|-----------|------|---------|
+| CreditBalanceWidget | `components/dashboard/CreditBalanceWidget.tsx` | Rename to ContentBalanceWidget |
+| BillingBalancePanel | `components/billing/BillingBalancePanel.tsx` | Remove "Purchase Credits" link |
+| BillingUsagePanel | `components/billing/BillingUsagePanel.tsx` | Simplify display |
+| CurrentProcessingCard | `components/Automation/CurrentProcessingCard.tsx` | "Credits Used" → "Content Generated" |
+| RunHistory | `components/Automation/RunHistory.tsx` | Same |
+
+### Medium Priority (Can ship with these unchanged)
+
+| Component | File | Notes |
+|-----------|------|-------|
+| CreditCostBreakdownPanel | `components/billing/CreditCostBreakdownPanel.tsx` | Admin only, keep |
+| CreditCostsPanel | `components/billing/CreditCostsPanel.tsx` | Admin only, keep |
+| UsageChartWidget | `components/dashboard/UsageChartWidget.tsx` | Keep for analytics |
+
+---
+
+## Phase 5: Routes to Update
+
+### File: `frontend/src/App.tsx`
+
+**Remove from user routes:**
+```typescript
+// Remove or hide:
+<Route path="/account/purchase-credits" element={<PurchaseCreditsPage />} />
+<Route path="/billing/credits" element={<Credits />} />
+```
+
+**Keep for admin access only** (add admin check)
+
+---
+
+## Phase 6: Terminology Mapping
+
+Use this mapping consistently:
+
+| OLD (Backend/Internal) | NEW (User-Facing) |
+|------------------------|-------------------|
+| credits | content pieces |
+| credit balance | content remaining |
+| credits used | content generated |
+| plan_credits_per_month | monthly content limit |
+| credits_remaining | content pieces left |
+| insufficient credits | content limit reached |
+| purchase credits | upgrade plan |
+
+---
+
+## Phase 7: Error Messages
+
+### File: Create `frontend/src/utils/userFriendlyMessages.ts`
+
+```typescript
+export const USER_MESSAGES = {
+  INSUFFICIENT_CREDITS: "You've reached your content limit for this month. Upgrade your plan for more.",
+  CREDIT_DEDUCTED: "Content piece generated successfully",
+  LOW_BALANCE: "You're running low on content pieces this month",
+  
+  // Operation-specific
+  CLUSTERING_SUCCESS: "Keywords organized into topics",
+  IDEAS_SUCCESS: "Content ideas generated",
+  CONTENT_SUCCESS: "Article draft created",
+  IMAGES_SUCCESS: "Images generated",
+};
+```
+
+---
+
+## Implementation Order
+
+### Day 1: Core Changes (Ship Blocker)
+
+1. [ ] Update `billingStore.ts` with computed properties
+2. [ ] Update `AppLayout.tsx` header metric
+3. [ ] Update `PlansAndBillingPage.tsx` - remove Credits tab
+4. [ ] Hide Purchase Credits route (don't delete)
+
+### Day 2: Dashboard & Key Pages
+
+5. [ ] Update `Dashboard/Home.tsx` labels
+6. [ ] Update `UsageAnalyticsPage.tsx` labels  
+7. [ ] Update `AutomationPage.tsx` labels
+8. [ ] Update `Help.tsx` FAQ content
+
+### Day 3: Components & Polish
+
+9. [ ] Rename CreditBalanceWidget → ContentBalanceWidget
+10. [ ] Update BillingBalancePanel
+11. [ ] Update CurrentProcessingCard
+12. [ ] Update RunHistory
+
+### Day 4: Marketing & Final
+
+13. [ ] Verify Pricing page is correct
+14. [ ] Update Waitlist/Tour pages
+15. [ ] Update SignUp form text
+16. [ ] Final QA pass
+
+---
+
+## What NOT to Change
+
+Keep these exactly as-is:
+
+1. **Backend API endpoints** - All `/v1/billing/*` endpoints
+2. **Database models** - CreditBalance, CreditUsage, etc.
+3. **Credit deduction logic** - In business services
+4. **Admin pages** - Keep full credit visibility for admins
+5. **API responses** - Backend still returns `credits`, frontend translates
+
+---
+
+## Backend Soft Limits (Already Implemented)
+
+Per the pricing session, backend should enforce:
+
+| Limit | Starter | Growth | Scale |
+|-------|---------|--------|-------|
+| Content pieces/mo | 50 | 200 | 500 |
+| Keyword imports/mo | 500 | 2,000 | 5,000 |
+| Clustering ops/mo | 100 | 400 | 1,000 |
+| Idea generations/mo | 150 | 600 | 1,500 |
+
+**If not implemented:** These are hidden from user but prevent abuse. Add backend validation in:
+- `backend/igny8_core/business/billing/services.py`
+
+---
+
+## Quick Wins (Can Do Now)
+
+### 1. Header Metric (5 min)
+
+In `AppLayout.tsx`, change:
+```typescript
+label: 'Credits',
+```
+to:
+```typescript
+label: 'Content',
+```
+
+### 2. Help FAQ (5 min)
+
+In `Help.tsx`, update the credits question to:
+```
+question: "How does content usage work?"
+answer: "Each plan includes a monthly content allowance. Creating articles, generating ideas, and producing images all count toward your monthly limit. View your usage in Settings > Usage."
+```
+
+### 3. Hide Purchase Credits Link (5 min)
+
+In `BillingBalancePanel.tsx`, remove or conditionally hide:
+```typescript
+<Link to="/account/purchase-credits">Purchase Credits</Link>
+```
+
+---
+
+## Testing Checklist
+
+Before production:
+
+- [ ] User can see "47/50 Content" in header (not "835 Credits")
+- [ ] Plans page shows content pieces, not credits
+- [ ] No "Purchase Credits" visible to regular users
+- [ ] Automation shows "Content Generated: 5" not "Credits Used: 5"
+- [ ] Error on limit shows "Content limit reached" not "Insufficient credits"
+- [ ] Dashboard shows simple progress bar with content count
+- [ ] Help/FAQ explains content pieces, not credits
+
+---
+
+## Summary
+
+**Total effort:** ~2-3 days of frontend work  
+**Backend changes:** Zero  
+**Risk:** Low (display-only changes)  
+**Rollback:** Easy (revert frontend only)
+
+The system still tracks everything internally with credits. Users just see a simpler "content pieces" model that maps 1:1 to content credits.