chore: bulk commit of local changes across blog writer, SEO dashboard, scheduler, docs-site, and frontend

docs-site/docs/about.md

@@ -1,3 +1,7 @@
+---
+description: About ALwrity - AI-powered digital marketing platform for solopreneurs and content creators. Learn about our vision, mission, and features.
+---
+
 # About ALwrity
 
 <div class="grid cards" markdown>

docs-site/docs/api/authentication.md

@@ -75,7 +75,7 @@ Content-Type: application/json
 ### Key Rotation
 
 ```bash
-# Create new key
+## Create new key
 curl -X POST "https://your-domain.com/api/keys" \
   -H "Authorization: Bearer YOUR_API_KEY" \
   -H "Content-Type: application/json" \
@@ -84,7 +84,7 @@ curl -X POST "https://your-domain.com/api/keys" \
     "permissions": ["read", "write"]
   }'
 
-# Revoke old key
+## Revoke old key
 curl -X DELETE "https://your-domain.com/api/keys/old_key_id" \
   -H "Authorization: Bearer YOUR_API_KEY"
 ```
@@ -234,10 +234,10 @@ def make_request_with_retry(url, headers, data):
 ```python
 from alwrity import AlwrityClient
 
-# Initialize client with API key
+## Initialize client with API key
 client = AlwrityClient(api_key="your_api_key_here")
 
-# Or use environment variable
+## Or use environment variable
 import os
 client = AlwrityClient(api_key=os.getenv('ALWRITY_API_KEY'))
 ```
@@ -257,10 +257,10 @@ const client = new AlwrityClient(process.env.ALWRITY_API_KEY);
 ### cURL Examples
 
 ```bash
-# Set API key as environment variable
+## Set API key as environment variable
 export ALWRITY_API_KEY="your_api_key_here"
 
-# Use in requests
+## Use in requests
 curl -H "Authorization: Bearer $ALWRITY_API_KEY" \
      -H "Content-Type: application/json" \
      https://your-domain.com/api/blog-writer

docs-site/docs/api/overview.md

@@ -1,3 +1,7 @@
+---
+description: ALwrity API Reference - Complete API documentation for authentication, endpoints, rate limiting, and error handling.
+---
+
 # API Reference Overview
 
 ALwrity provides a comprehensive RESTful API that allows you to integrate AI-powered content creation capabilities into your applications. This API enables you to generate blog posts, optimize SEO, create social media content, and manage your content strategy programmatically.

docs-site/docs/features/backlink-outreach/api-reference.md

@@ -75,12 +75,16 @@ flowchart TD
 **Request Body:**
 
 | Field | Type | Required | Description |
-|---|---|---|---|
+|---|---|---|---|---|
 | `name` | string | Yes | Campaign name. |
 | `description` | string | No | Campaign description. |
 | `keywords` | string[] | No | Target keywords for discovery. |
 
-**Response:** `201 Created` — Campaign object.
+**Error responses:**
+
+| Code | Meaning |
+|---|---|
+| `422` | Validation error (e.g., empty name). |
 
 ### List Campaigns
 
@@ -92,7 +96,7 @@ flowchart TD
 |---|---|---|---|
 | `workspace_id` | string | user_id | Workspace to filter by. Defaults to authenticated user. |
 
-**Response:** `200 OK` — Array of campaign objects.
+**Response:** `200 OK` — Array of campaign objects scoped to the authenticated user.
 
 ### Get Campaign
 
@@ -100,12 +104,24 @@ flowchart TD
 
 **Response:** `200 OK` — Campaign object with included leads.
 
+**Error responses:**
+
+| Code | Meaning |
+|---|---|
+| `404` | Campaign not found or does not belong to authenticated user (`BacklinkCampaignNotFoundError`). |
+
 ### Delete Campaign
 
 `DELETE /api/v1/backlink-outreach/campaigns/{campaign_id}`
 
 **Response:** `204 No Content`
 
+**Error responses:**
+
+| Code | Meaning |
+|---|---|
+| `404` | Campaign not found or does not belong to authenticated user. |
+
 ---
 
 ## Leads
@@ -117,7 +133,7 @@ flowchart TD
 **Request Body:**
 
 | Field | Type | Required | Description |
-|---|---|---|---|
+|---|---|---|---|---|
 | `website_url` | string | Yes | Target website URL. |
 | `website_title` | string | No | Website title. |
 | `contact_email` | string | No | Contact email address. |
@@ -126,7 +142,14 @@ flowchart TD
 | `guest_post_likelihood` | float | No | Guest post likelihood (0-1). |
 | `source` | string | No | Source of the lead. |
 
-**Response:** `201 Created` — Lead object.
+!!! tip "Duplicate handling"
+    If a lead with the same `website_url` already exists in the campaign, the existing lead record is returned (HTTP 200) instead of creating a duplicate.
+
+**Error responses:**
+
+| Code | Meaning |
+|---|---|
+| `404` | Campaign not found or not owned by user. |
 
 ### Bulk Add Leads
 
@@ -138,8 +161,8 @@ flowchart TD
 
 | Field | Type | Description |
 |---|---|---|
-| `added` | int | Number of leads successfully added. |
-| `skipped` | int | Number of duplicates skipped. |
+| `added` | int | Number of leads successfully added (duplicates excluded). |
+| `skipped` | int | Number of existing leads skipped (matched by `(campaign_id, website_url)`). |
 | `failed` | string[] | List of failed entries with reasons. |
 
 ### Update Lead Status
@@ -149,10 +172,15 @@ flowchart TD
 **Request Body:**
 
 | Field | Type | Required | Description |
-|---|---|---|---|
-| `status` | string | Yes | New status: discovered, contacted, replied, placed, bounced, lost. |
+|---|---|---|---|---|
+| `status` | string | Yes | New status: `discovered`, `contacted`, `replied`, `placed`, `bounced`, `unsubscribed`. |
 
-**Response:** `200 OK` — Updated lead object.
+**Error responses:**
+
+| Code | Meaning |
+|---|---|
+| `422` | Invalid status value (must be one of the valid statuses). |
+| `404` | Lead not found. |
 
 ### Bulk Update Status
 
@@ -163,7 +191,7 @@ flowchart TD
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `lead_ids` | string[] | Yes | Lead IDs to update. |
-| `status` | string | Yes | New status for all leads. |
+| `status` | string | Yes | New status: `discovered`, `contacted`, `replied`, `placed`, `bounced`, `unsubscribed`. |
 
 **Response:** `200 OK`
 
@@ -441,9 +469,10 @@ flowchart TD
 ## Common Error Responses
 
 | Status | Meaning | Body |
-|---|---|---|
+|---|---|---|---|
 | `401` | Not authenticated | `{"detail": "Not authenticated"}` |
 | `403` | Policy blocked | `{"detail": "Policy validation failed", "reason": "..."}` |
-| `404` | Not found | `{"detail": "Resource not found"}` |
+| `404` | Campaign or lead not found | `{"detail": "BacklinkCampaignNotFoundError: Campaign not found or access denied"}` |
+| `409` | Duplicate lead (idempotency key collision) | `{"detail": "Duplicate attempt detected"}` |
 | `422` | Validation error | `{"detail": [...validation errors]}` |
 | `500` | Server error | `{"detail": "An internal error occurred"}` (generic, no stack trace) |

docs-site/docs/features/backlink-outreach/campaign-management.md

@@ -21,6 +21,9 @@ A campaign requires only a name. Add a description and keywords to make discover
 !!! tip "Naming conventions"
     Use a consistent naming scheme like `[Vertical] [Content Type] [Period]` — e.g., "Fitness Guest Posts June" or "AI Startups Roundup Q3".
 
+!!! warning "Ownership validation"
+    Campaigns are scoped to the authenticated user. API calls with a `campaign_id` that does not exist or belongs to another user return `404 BacklinkCampaignNotFoundError`. This applies to all campaign operations (get, delete, add leads, send emails, etc.).
+
 ## Campaign List View
 
 The campaign list shows:

docs-site/docs/features/backlink-outreach/configuration.md

@@ -68,6 +68,20 @@ The Backlink Outreach feature uses SQLite with automatic table creation:
 
 Tables are created automatically on first use via `_ensure_tables()`. No manual migration is required.
 
+## Feature Flag Configuration
+
+The Backlink Outreach feature can be enabled in isolation via the `ALWRITY_ENABLED_FEATURES` environment variable:
+
+| Variable | Value | Description |
+|---|---|---|
+| `ALWRITY_ENABLED_FEATURES` | `all` (default) | Enable all platform features. |
+| `ALWRITY_ENABLED_FEATURES` | `backlinking` | Enable only Backlink Outreach + core services. |
+
+When set to `backlinking`, only the backlink outreach router and its core dependencies are loaded. Other features (blog writer, podcast, SEO dashboard, etc.) are skipped — reducing startup time and memory usage.
+
+!!! note "Multiple features"
+    You can also enable a combination: `ALWRITY_ENABLED_FEATURES=core,backlinking` or `ALWRITY_ENABLED_FEATURES=podcast,backlinking`.
+
 ## Deployment Checklist
 
 ### Minimal Setup

docs-site/docs/features/backlink-outreach/implementation-overview.md

@@ -54,13 +54,15 @@ backend/
 ├── routers/
 │   └── backlink_outreach.py          # 18+ API endpoints
 ├── services/
-│   ├── backlink_outreach_service.py  # Business logic, policy, analytics
-│   ├── backlink_outreach_storage.py  # SQLite CRUD operations
-│   ├── backlink_outreach_sender.py   # SMTP email delivery
-│   ├── backlink_outreach_reply_monitor.py  # IMAP reply polling
-│   └── backlink_outreach_models.py   # Pydantic request/response models
+│   ├── backlink_outreach_service.py       # Business logic, policy, analytics
+│   ├── backlink_outreach_storage.py       # SQLite CRUD operations
+│   ├── backlink_outreach_sender.py        # SMTP email delivery with Message-ID
+│   ├── backlink_outreach_reply_monitor.py # IMAP reply polling with Message-ID matching
+│   ├── backlink_outreach_scraper.py       # Deep website scraper (Exa + DuckDuckGo)
+│   ├── backlink_outreach_template_generator.py  # LLM-based email copy generation
+│   └── backlink_outreach_models.py        # Pydantic request/response models
 ├── models/
-│   └── backlink_outreach_models.py   # SQLAlchemy models + indexes
+│   └── backlink_outreach_models.py        # SQLAlchemy models + indexes
 
 frontend/src/
 ├── components/
@@ -109,6 +111,7 @@ erDiagram
         string body
         string status
         string legal_basis
+        string message_id
         datetime sent_at
     }
     OutreachReply {
@@ -217,10 +220,10 @@ SQLite CRUD operations with 20+ methods:
 - Campaign CRUD: `create_campaign`, `list_backlink_campaigns`, `get_campaign`, `delete_campaign`.
 - Lead management: `add_campaign_lead`, `add_campaign_leads_bulk`, `update_lead_status`, `bulk_update_lead_status`.
 - Outreach: `create_outreach_attempt`, `list_outreach_attempts`, `get_lead_attempts`.
-- Replies: `store_reply`, `find_attempt_by_from_email`, `reply_exists`, `list_replies`, `count_replies`.
+- Replies: `store_reply`, `find_attempt_by_from_email`, `find_attempt_by_message_id`, `reply_exists`, `list_replies`, `count_replies`.
 - Follow-ups: `create_follow_up`, `list_follow_ups`.
 - Suppression: `add_suppression`, `list_suppression`, `is_suppressed`.
-- Counters: `increment_user_counter`, `increment_domain_counter` (atomic ON CONFLICT).
+- Counters: `try_increment_user_send_counter`, `try_increment_domain_send_counter` (atomic ON CONFLICT — reserves cap slot before send).
 - Idempotency: `check_idempotency`, `mark_idempotency`.
 - Audit: `log_audit_entry`.
 - Templates: `create_email_template`, `list_email_templates`, `get_email_template`, `delete_email_template`.
@@ -249,7 +252,7 @@ Handles IMAP reply processing:
 3. Searches for messages matching the outreach sender.
 4. Fetches up to `IMAP_FETCH_LIMIT` messages.
 5. Checks for duplicates via `reply_exists()`.
-6. Matches replies to attempts via `find_attempt_by_from_email()`.
+6. Matches replies to attempts via `find_attempt_by_message_id()` (primary, using `In-Reply-To`/`References` headers), falls back to `find_attempt_by_from_email()`.
 7. Classifies replies based on content analysis.
 8. Stores reply records.
 

docs-site/docs/features/backlink-outreach/outreach-operations.md

@@ -12,15 +12,16 @@ flowchart TD
     B --> C[Resolve Lead Email from DB]
     C --> D[Policy Validation]
     D -->|Approved| E[Create Outreach Attempt Record]
-    D -->|Blocked| F[Record Audit Log + Return 403]
-    E --> G[Send via SMTP with TLS]
-    G -->|Success| H[Increment Counters]
-    G -->|Success| I[Mark Idempotency Key]
-    G -->|Success| J[Update Lead Status to Contacted]
-    G -->|Failure| K[Return 500 with Generic Error]
-    H --> L[Return 200 with Attempt Details]
-    I --> L
-    J --> L
+    D -->|Blocked|     F[Record Audit Log + Return 403]
+    E --> G[Reserve Daily Cap Slots Atomically]
+    G --> H[Send via SMTP with TLS + Message-ID]
+    H -->|Success| I[Store Message-ID on Attempt Record]
+    H -->|Success| J[Mark Idempotency Key]
+    H -->|Success| K[Update Lead Status to Contacted]
+    H -->|Failure| L[Return 500 with Generic Error]
+    I --> M[Return 200 with Attempt Details]
+    J --> M
+    K --> M
     
     style D fill:#fff3e0
     style G fill:#e3f2fd
@@ -28,7 +29,7 @@ flowchart TD
 ```
 
 !!! warning "Counter timing"
-    Counters and idempotency keys are marked **only after successful SMTP delivery**, never before. This prevents false cap consumption on failed sends.
+    Daily cap slots are **reserved atomically before sending** via `try_increment_user_send_counter` and `try_increment_domain_send_counter`. If SMTP delivery fails, one slot is consumed (the cap check and increment happen in the same transaction). Idempotency keys are marked only after successful delivery.
 
 ## Policy Validation
 
@@ -40,6 +41,7 @@ Before every send, the system validates:
 | **Daily domain cap** | Max 20 emails/domain/day | Block + audit |
 | **Suppression list** | Recipient not suppressed | Block + audit |
 | **Idempotency** | No duplicate `(sender, recipient, subject)` in 24h | Block + audit |
+| **Sender alias** | `sender_email` must match `SMTP_ALLOWED_FROM_EMAILS` pattern | Block + fallback to `SMTP_FROM_EMAIL` |
 | **Legal basis** | EU domains → "consent", others → "legitimate_interest" | Auto-assign |
 
 **API:** `POST /api/v1/backlink-outreach/policy/validate`

docs-site/docs/features/backlink-outreach/overview.md

@@ -1,3 +1,7 @@
+---
+description: ALwrity Backlink Outreach - AI-powered backlink discovery, outreach automation, and campaign management.
+---
+
 # Backlink Outreach Overview
 
 Backlink Outreach is an AI-powered guest post outreach platform that takes you from opportunity discovery to published backlink — with smart email composition, policy-safe sending, IMAP reply monitoring, and full campaign analytics.

docs-site/docs/features/backlink-outreach/reply-inbox.md

@@ -44,15 +44,18 @@ The reply monitor:
 3. Searches for messages sent to your outreach address.
 4. Fetches up to `IMAP_FETCH_LIMIT` recent messages.
 5. For each message, checks if it's already been processed (deduplication).
-6. Matches the reply to an existing outreach attempt by sender email.
+6. Matches the reply to an existing outreach attempt (Message-ID first, sender email fallback).
 7. Classifies the reply and stores it.
 
 ### Reply Matching
 
-Replies are matched to outreach attempts using the `from_email` field:
+Replies are matched to outreach attempts using a two-stage strategy:
 
-- The system looks up `find_attempt_by_from_email(from_email)` to find the most recent outreach attempt sent to that email address.
-- If no match is found, the reply is still stored but not linked to an attempt.
+1. **Message-ID matching (primary)**: Each sent email includes a unique `Message-ID` header. When the recipient replies, their email client includes the original `Message-ID` in `In-Reply-To` and `References` headers. The system extracts these and looks up `find_attempt_by_message_id(in_reply_to)` to find the exact outreach attempt.
+
+2. **Sender email fallback**: If no Message-ID match is found (e.g., the reply client stripped headers), the system falls back to `find_attempt_by_from_email(from_email)` to find the most recent attempt sent to that address.
+
+3. **Unmatched replies**: If neither strategy produces a match, the reply is still stored but not linked to an attempt.
 
 ### Deduplication
 

docs-site/docs/features/blog-writer/overview.md

@@ -1,3 +1,7 @@
+---
+description: ALwrity Blog Writer - AI-powered blog post creation with SEO optimization, research integration, and multi-platform publishing.
+---
+
 # Blog Writer Overview
 
 The ALwrity Blog Writer is a powerful AI-driven content creation tool that helps you generate high-quality, SEO-optimized blog posts with minimal effort. It's designed for users with medium to low technical knowledge, making professional content creation accessible to everyone.

docs-site/docs/features/content-strategy/overview.md

@@ -1,3 +1,7 @@
+---
+description: ALwrity Content Strategy - AI-powered strategic planning, persona development, and content calendar generation.
+---
+
 # Content Strategy Overview
 
 ALwrity's Content Strategy module is the brain of your content marketing efforts, providing AI-powered strategic planning, persona development, and content calendar generation to help you create a comprehensive, data-driven content marketing strategy.
@@ -323,6 +327,13 @@ ALwrity generates comprehensive content calendars that align with your strategy:
 - **Strategy Updates**: Automatic strategy refinement
 - **Report Generation**: Automated performance reports
 
+## Related Features
+
+- **[Persona System](../persona/overview.md)** — Build audience personas for targeted content
+- **[Blog Writer](../blog-writer/overview.md)** — Create content aligned with your strategy
+- **[SEO Dashboard](../seo-dashboard/overview.md)** — Discover content gaps and opportunities
+- **[Backlink Outreach](../backlink-outreach/overview.md)** — Support strategy with link-building
+
 ---
 
 *Ready to develop your content strategy? [Start with our First Steps Guide](../../getting-started/first-steps.md) or [Explore Persona Development](personas.md) to begin building your strategic content plan!*

docs-site/docs/features/image-studio/api-reference.md

@@ -14,7 +14,7 @@ All endpoints require authentication via Bearer token:
 Authorization: Bearer YOUR_ACCESS_TOKEN
 ```
 
-The token is obtained through the standard ALwrity authentication flow. See [Authentication Guide](../api/authentication.md) for details.
+The token is obtained through the standard ALwrity authentication flow. See [Authentication Guide](../../api/authentication.md) for details.
 
 ## API Architecture
 
@@ -827,7 +827,7 @@ Image Studio API follows standard ALwrity rate limiting:
 - **Headers**: Rate limit information in response headers
 - **Retry**: Use exponential backoff for rate limit errors
 
-See [Rate Limiting Guide](../api/rate-limiting.md) for details.
+See [Rate Limiting Guide](../../api/rate-limiting.md) for details.
 
 ---
 
@@ -936,5 +936,5 @@ curl -X POST https://api.alwrity.com/api/image-studio/create \
 
 ---
 
-*For authentication details, see the [API Authentication Guide](../api/authentication.md). For rate limiting, see the [Rate Limiting Guide](../api/rate-limiting.md).*
+*For authentication details, see the [API Authentication Guide](../../api/authentication.md). For rate limiting, see the [Rate Limiting Guide](../../api/rate-limiting.md).*
 

docs-site/docs/features/image-studio/modules.md

@@ -1,3 +1,7 @@
+---
+description: ALwrity Image Studio modules - Create, Edit, Upscale, Optimize, and manage image assets.
+---
+
 # Image Studio Modules
 
 Image Studio consists of 7 core modules that provide a complete image workflow from creation to optimization. This guide provides detailed information about each module, their features, and current implementation status.

docs-site/docs/features/image-studio/overview.md

@@ -1,3 +1,7 @@
+---
+description: ALwrity Image Studio - AI-powered image creation, editing, and optimization for digital marketers and content creators.
+---
+
 # Image Studio Overview
 
 The ALwrity Image Studio is a comprehensive AI-powered image creation, editing, and optimization platform designed specifically for digital marketers and content creators. It provides a unified hub for all image-related operations, from generation to social media optimization, making professional visual content creation accessible to everyone.

docs-site/docs/features/linkedin-writer/overview.md

@@ -1,3 +1,7 @@
+---
+description: ALwrity LinkedIn Writer - AI-powered professional LinkedIn content creation for brand building.
+---
+
 # LinkedIn Writer: Overview
 
 The ALwrity LinkedIn Writer is a specialized AI-powered tool designed to help you create professional, engaging LinkedIn content that builds your personal brand, drives engagement, and establishes thought leadership in your industry.

docs-site/docs/features/persona/overview.md

@@ -1,3 +1,7 @@
+---
+description: ALwrity Persona System - AI-powered personalized writing assistants tailored to your brand voice.
+---
+
 # Persona System Overview
 
 The ALwrity Persona System is a revolutionary AI-powered feature that creates personalized writing assistants tailored specifically to your voice, style, and communication preferences. It analyzes your writing patterns and creates platform-specific optimizations for LinkedIn, Facebook, and other social media platforms.
@@ -267,6 +271,13 @@ The ALwrity Persona System transforms your content creation experience by provid
 
 Remember: Your persona is a powerful tool that learns and improves over time. The more you use it, the better it becomes at understanding your style and helping you create exceptional content.
 
+## Related Features
+
+- **[Content Strategy](../content-strategy/overview.md)** — Align personas with content strategy
+- **[Blog Writer](../blog-writer/overview.md)** — Write blog posts in your persona's voice
+- **[LinkedIn Writer](../linkedin-writer/overview.md)** — Create LinkedIn content with brand voice
+- **[SIF & AI Agents](../sif-agents/overview.md)** — AI agents that adapt to your persona
+
 ---
 
 *Ready to create your personalized writing persona? [Start with our First Steps Guide](../../getting-started/first-steps.md) and [Explore Platform-Specific Features](platform-integration.md) to begin your personalized content creation journey!*

docs-site/docs/features/podcast-maker/overview.md

@@ -1,3 +1,7 @@
+---
+description: ALwrity Podcast Maker - AI-powered podcast creation, editing, and publishing platform.
+---
+
 # Podcast Maker Overview
 
 Podcast Maker helps you turn a topic idea into a polished episode draft with research, script generation, AI voice narration, and optional video scenes.
@@ -47,6 +51,13 @@ Most users can ignore this section.
 - The frontend normalizes snake_case API responses into camelCase for UI components where needed.
 - Long-running video operations are task-based and polled from the client.
 
+## Related Features
+
+- **[Workflow Guide](workflow-guide.md)** — Step-by-step podcast creation
+- **[YouTube Publishing](youtube-publishing.md)** — Upload podcasts to YouTube
+- **[Blog Writer](../blog-writer/overview.md)** — Repurpose podcast scripts into blog posts
+- **[Image Studio](../image-studio/overview.md)** — Create podcast cover art
+
 ## Engineering references
 
 These are internal planning/reference docs retained as source material:

docs-site/docs/features/seo-dashboard/competitive-analysis.md

@@ -424,4 +424,4 @@ Score opportunities by:
 
 ---
 
-**Ready to analyze your competition? Start with [Competitive Analysis Tool](../tools-reference.md) or ask the [AI Copilot](ai-copilot.md) for guidance!**
+**Ready to analyze your competition? Start with the [SEO Dashboard Tools Reference](tools-reference.md) or ask the [AI Copilot](ai-copilot.md) for guidance!**

docs-site/docs/features/seo-dashboard/index.md

@@ -129,9 +129,9 @@ Deep technical reference:
 
 **Recommended Reading Order**:
 1. [Quick Start Guide](quick-start.md) - 10 min
-2. [Meta Description Generator](individual-tools-guide.md#1--meta-description-generator) - 5 min
-3. [On-Page SEO Analyzer](individual-tools-guide.md#6--on-page-seo-analyzer) - 10 min
-4. [Content Strategy Analyzer](individual-tools-guide.md#9--content-strategy-analyzer) - 10 min
+2. [Meta Description Generator](individual-tools-guide.md#1-meta-description-generator) - 5 min
+3. [On-Page SEO Analyzer](individual-tools-guide.md#6-on-page-seo-analyzer) - 10 min
+4. [Content Strategy Analyzer](individual-tools-guide.md#9-content-strategy-analyzer) - 10 min
 5. [LLM Insights Generation](phase2a-llm-insights.md) - Get AI content strategy - 10 min
 6. [Content Creation Workflow](workflows-guide.md#workflow-1-content-creation-pipeline) - 5 min
 
@@ -210,8 +210,8 @@ Deep technical reference:
 
 **Recommended Reading Order**:
 1. [Quick Start Guide](quick-start.md) - 10 min
-2. [Technical SEO Analyzer](individual-tools-guide.md#7--technical-seo-analyzer) - 15 min
-3. [PageSpeed Analyzer](individual-tools-guide.md#2--pagespeed-analyzer) - 15 min
+2. [Technical SEO Analyzer](individual-tools-guide.md#7-technical-seo-analyzer) - 15 min
+3. [PageSpeed Analyzer](individual-tools-guide.md#2-pagespeed-analyzer) - 15 min
 4. [Design Document](design-document.md) - 20 min
 
 **Total Learning Time**: 1 hour
@@ -267,15 +267,15 @@ Deep technical reference:
 
 | Goal | Tool | Guide |
 |------|------|-------|
-| Quick content optimization | On-Page SEO Analyzer | [Link](individual-tools-guide.md#6--on-page-seo-analyzer) |
-| Improve search appearance | Meta Description Generator | [Link](individual-tools-guide.md#1--meta-description-generator) |
-| Social media optimization | OpenGraph Generator | [Link](individual-tools-guide.md#5--opengraph-generator) |
-| Find new content ideas | Content Strategy Analyzer | [Link](individual-tools-guide.md#9--content-strategy-analyzer) |
-| Fix website speed | PageSpeed Analyzer | [Link](individual-tools-guide.md#2--pagespeed-analyzer) |
-| Find technical issues | Technical SEO Analyzer | [Link](individual-tools-guide.md#7--technical-seo-analyzer) |
-| Understand your site | Sitemap Analyzer | [Link](individual-tools-guide.md#3--sitemap-analyzer) |
-| Optimize images | Image Alt Text Generator | [Link](individual-tools-guide.md#4--image-alt-text-generator) |
-| Complete audit | Enterprise SEO Suite | [Link](individual-tools-guide.md#8--enterprise-seo-suite) |
+| Quick content optimization | On-Page SEO Analyzer | [Link](individual-tools-guide.md#6-on-page-seo-analyzer) |
+| Improve search appearance | Meta Description Generator | [Link](individual-tools-guide.md#1-meta-description-generator) |
+| Social media optimization | OpenGraph Generator | [Link](individual-tools-guide.md#5-opengraph-generator) |
+| Find new content ideas | Content Strategy Analyzer | [Link](individual-tools-guide.md#9-content-strategy-analyzer) |
+| Fix website speed | PageSpeed Analyzer | [Link](individual-tools-guide.md#2-pagespeed-analyzer) |
+| Find technical issues | Technical SEO Analyzer | [Link](individual-tools-guide.md#7-technical-seo-analyzer) |
+| Understand your site | Sitemap Analyzer | [Link](individual-tools-guide.md#3-sitemap-analyzer) |
+| Optimize images | Image Alt Text Generator | [Link](individual-tools-guide.md#4-image-alt-text-generator) |
+| Complete audit | Enterprise SEO Suite | [Link](individual-tools-guide.md#8-enterprise-seo-suite) |
 | Beat competitors | Competitive Analysis | [Link](competitive-analysis.md) |
 | Plan strategy | Content Strategy Guide | [Link](content-strategy-guide.md) |
 | AI recommendations | AI Copilot | [Link](ai-copilot.md) |

docs-site/docs/features/seo-dashboard/overview.md

@@ -1,3 +1,7 @@
+---
+description: ALwrity SEO Dashboard - 21+ production-ready SEO tools for content optimization, competitive analysis, and performance tracking.
+---
+
 # SEO Dashboard Overview
 
 The ALwrity SEO Dashboard is a comprehensive, AI-powered platform providing **21+ production-ready SEO tools** for content creators, digital marketers, and SEO professionals. Designed for users of all technical levels, it combines advanced AI analysis with real-time platform integrations for actionable SEO insights.
@@ -311,9 +315,9 @@ For detailed information about each tool, see [Tools Reference](tools-reference.
 
 - **[Blog Writer](../blog-writer/overview.md)** - Content creation with integrated SEO
 - **[Content Strategy](../content-strategy/overview.md)** - Strategic planning and gaps
-- **[AI Features](../ai/overview.md)** - Advanced AI capabilities
+- **[AI Features](../ai/assistive-writing.md)** - Advanced AI capabilities
 - **[Persona System](../persona/overview.md)** - Personalized writing assistants
-- **[API Reference](../../api/seo-tools.md)** - Technical integration details
+- **[API Reference](../../api/overview.md)** - Technical integration details
 
 ---
 

docs-site/docs/features/seo-dashboard/phase2a-complete-guide.md

@@ -266,14 +266,14 @@ User: Insights, Roadmap, Recommendations
 4. [LLM Insights Generation](phase2a-llm-insights.md)
 
 ### For Integrators
-1. [API Reference](../api.md)
-2. [Integration Guide](../guides/integration-guide.md)
-3. [Code Examples](#)
+1. [API Reference](../../api/overview.md)
+2. [Authentication Guide](../../api/authentication.md)
+3. [Best Practices](../../guides/best-practices.md)
 
 ### For Operators
-1. [Deployment Guide](../guides/deployment.md)
-2. [Health Monitoring](../guides/monitoring.md)
-3. [Troubleshooting](../guides/troubleshooting.md)
+1. [Deployment Guide](../../getting-started/installation.md)
+2. [Troubleshooting](../../guides/troubleshooting.md)
+3. [Performance Guide](../../guides/performance.md)
 
 ---
 
@@ -364,9 +364,8 @@ A: All Phase 2A features are available to Premium and Enterprise subscribers.
 
 ## 📞 Support
 
-- **Documentation**: [Full docs](./index.md)
-- **API Reference**: [Complete reference](../api.md)
-- **Examples**: [Code samples](../examples.md)
+- **Documentation**: [SEO Dashboard Overview](./overview.md)
+- **API Reference**: [Complete API Reference](../../api/overview.md)
 - **Help**: Contact support@alwrity.com
 
 ---

docs-site/docs/features/seo-dashboard/tools-reference.md

@@ -202,17 +202,17 @@ See next section...
 - [Metadata Generation Guide](metadata.md)
 
 ### Tool-Specific Guides
-- [Meta Description Generator](meta-description-tool.md)
-- [PageSpeed Analyzer Guide](pagespeed-analyzer.md)
-- [Sitemap Analysis](sitemap-analyzer.md)
-- [Content Strategy Tool](content-strategy-tool.md)
-- [Technical SEO Analyzer](technical-seo-tool.md)
-- [Competitive Analysis](competitive-analysis.md)
+- Meta Description Generator — see [Workflows & Automation Guide](workflows-guide.md)
+- PageSpeed Analyzer — see [Workflows & Automation Guide](workflows-guide.md)
+- Sitemap Analysis — see [Workflows & Automation Guide](workflows-guide.md)
+- Content Strategy Tool — see [Content Strategy Guide](content-strategy-guide.md)
+- Technical SEO Analyzer — see [Workflows & Automation Guide](workflows-guide.md)
+- [Competitive Analysis Guide](competitive-analysis.md)
 
 ### Advanced Guides
 - [AI Copilot Assistant](ai-copilot.md)
-- [API Reference](../../api/seo-tools.md)
-- [Advanced Configuration](advanced-configuration.md)
+- [API Reference](../../api/overview.md)
+- Advanced Configuration — see [SEO Dashboard Setup](overview.md)
 
 ---
 
@@ -343,10 +343,10 @@ See next section...
 ## 🔗 Related Resources
 
 - [SEO Dashboard Main Guide](overview.md)
-- [Complete API Reference](../../api/seo-tools.md)
+- [Complete API Reference](../../api/overview.md)
 - [Blog Writer SEO Integration](../blog-writer/overview.md)
 - [Content Strategy Guide](../content-strategy/overview.md)
-- [AI Features](../ai/overview.md)
+- [AI Features](../ai/assistive-writing.md)
 
 ---
 

docs-site/docs/features/subscription/pricing.md

@@ -124,7 +124,7 @@ Models covered: `openai/gpt-oss-120b:groq`, `gpt-oss-120b`, and `default` (fallb
 
 ## Additional Resources
 
-- [Billing Dashboard](billing-dashboard.md)
+- Billing Dashboard (see [Subscription Overview](overview.md))
 - [API Reference](api-reference.md)
 - [Setup Guide](setup.md)
 - [Gemini Pricing](https://ai.google.dev/gemini-api/docs/pricing)

docs-site/docs/index.md

@@ -1,38 +1,194 @@
+---
+description: ALwrity AI-powered digital marketing platform documentation. Learn content creation, SEO optimization, and AI-driven marketing tools.
+---
+
 # Welcome to ALwrity Documentation
 
+ALwrity is an AI-powered digital marketing platform that revolutionizes content creation and SEO optimization. This documentation covers everything from quick start guides to detailed API references.
+
+## Platform Architecture
+
+```mermaid
+flowchart TB
+    subgraph User["User Layer"]
+        UI[Web Dashboard]
+        API[API Clients]
+    end
+
+    subgraph Core["Core Platform"]
+        Auth[Clerk Authentication]
+        Router[FastAPI Router]
+        FeatureReg[Feature Registry]
+        ProfileMgr[Profile Manager]
+    end
+
+    subgraph AI["AI & Intelligence Layer"]
+        LLM[OpenAI / LLM Providers]
+        Persona[Persona System]
+        SIF[SIF Agent System]
+        ContentGuard[Content Guardian]
+    end
+
+    subgraph Content["Content Creation"]
+        Blog[Blog Writer]
+        LinkedIn[LinkedIn Writer]
+        FB[Facebook Writer]
+        Podcast[Podcast Maker]
+        Story[Story Writer]
+        Video[Video Studio]
+        YouTube[YouTube Studio]
+        Image[Image Studio]
+    end
+
+    subgraph Marketing["Marketing & SEO"]
+        SEO[SEO Dashboard]
+        GSC[Google Search Console]
+        Strategy[Content Strategy]
+        Backlink[Backlink Outreach]
+    end
+
+    subgraph Platform["Platform Services"]
+        Workflow[Today's Workflow]
+        Team[Team Activity]
+        Onboard[Onboarding System]
+        Sub[Subscription]
+        Wix[Wix Integration]
+    end
+
+    User --> Auth
+    User --> API
+    Auth --> Router
+    Router --> FeatureReg
+    FeatureReg --> ProfileMgr
+    ProfileMgr --> Content
+    ProfileMgr --> Marketing
+    ProfileMgr --> Platform
+    Router --> AI
+    AI --> Content
+    Content --> Marketing
+    SEO --> GSC
+    SIF --> ContentGuard
+    SIF --> Content
+```
+
+## Content Workflow
+
+```mermaid
+flowchart LR
+    A[Idea & Research] --> B[Content Planning]
+    B --> C[Content Creation]
+    C --> D[SEO Optimization]
+    D --> E[Review & Approve]
+    E --> F[Publish & Distribute]
+    F --> G[Track & Analyze]
+    G --> A
+
+    style A fill:#e3f2fd
+    style B fill:#e8f5e8
+    style C fill:#fff3e0
+    style D fill:#fce4ec
+    style E fill:#f3e5f5
+    style F fill:#e0f2f1
+    style G fill:#fbe9e7
+```
+
+## Feature Overview
+
 <div class="grid cards" markdown>
 
--   :material-rocket-launch:{ .lg .middle } **Quick Start**
+-   :material-rocket-launch:{ .lg .middle } **Getting Started**
 
     ---
 
-    Get up and running with ALwrity in minutes
+    Set up ALwrity and create your first content
 
     [:octicons-arrow-right-24: Quick Start](getting-started/quick-start.md)
+    [:octicons-arrow-right-24: Installation](getting-started/installation.md)
+    [:octicons-arrow-right-24: Configuration](getting-started/configuration.md)
 
--   :material-robot:{ .lg .middle } **AI Features**
+-   :material-pencil:{ .lg .middle } **Blog Writer**
 
     ---
 
-    Explore our AI-powered content generation capabilities
+    AI-powered blog post creation with SEO analysis
 
-    [:octicons-arrow-right-24: AI Features](features/ai/assistive-writing.md)
+    [:octicons-arrow-right-24: Overview](features/blog-writer/overview.md)
+    [:octicons-arrow-right-24: Workflow Guide](features/blog-writer/workflow-guide.md)
+
+-   :material-linkedin:{ .lg .middle } **LinkedIn Writer**
+
+    ---
+
+    Professional LinkedIn content creation
+
+    [:octicons-arrow-right-24: Overview](features/linkedin-writer/overview.md)
+
+-   :material-facebook:{ .lg .middle } **Facebook Writer**
+
+    ---
+
+    Engaging Facebook post generation
+
+    [:octicons-arrow-right-24: Overview](features/blog-writer/overview.md)
+
+-   :material-microphone:{ .lg .middle } **Podcast Maker**
+
+    ---
+
+    AI-powered podcast creation and publishing
+
+    [:octicons-arrow-right-24: Overview](features/podcast-maker/workflow-guide.md)
+
+-   :material-book-open-variant:{ .lg .middle } **Story Writer**
+
+    ---
+
+    Brand storytelling and case study builder
+
+    [:octicons-arrow-right-24: Overview](features/story-writer/overview.md)
+
+-   :material-video:{ .lg .middle } **Video Studio**
+
+    ---
+
+    AI video creation and editing platform
+
+    [:octicons-arrow-right-24: Overview](features/video-studio/overview.md)
+
+-   :material-youtube:{ .lg .middle } **YouTube Studio**
+
+    ---
+
+    YouTube content optimization and channel management
+
+    [:octicons-arrow-right-24: Overview](features/youtube-studio/overview.md)
+
+-   :material-image:{ .lg .middle } **Image Studio**
+
+    ---
+
+    AI image creation, editing, and optimization
+
+    [:octicons-arrow-right-24: Overview](features/image-studio/overview.md)
+    [:octicons-arrow-right-24: Modules](features/image-studio/modules.md)
 
 -   :material-chart-line:{ .lg .middle } **SEO Dashboard**
 
     ---
 
-    Comprehensive SEO analysis and optimization tools
+    Comprehensive SEO analysis and optimization
 
-    [:octicons-arrow-right-24: SEO Dashboard](features/seo-dashboard/overview.md)
+    [:octicons-arrow-right-24: Overview](features/seo-dashboard/overview.md)
+    [:octicons-arrow-right-24: Quick Start](features/seo-dashboard/quick-start.md)
 
--   :material-pencil:{ .lg .middle } **Content Writers**
+-   :material-link:{ .lg .middle } **Backlink Outreach**
 
     ---
 
-    Blog, LinkedIn, and Facebook content generation
+    AI-powered backlink discovery and outreach
 
-    [:octicons-arrow-right-24: Content Writers](features/blog-writer/overview.md)
+    [:octicons-arrow-right-24: Overview](features/backlink-outreach/overview.md)
+    [:octicons-arrow-right-24: Workflow Guide](features/backlink-outreach/workflow-guide.md)
 
 -   :material-account:{ .lg .middle } **Persona System**
 
@@ -40,52 +196,77 @@
 
     AI-powered personalized writing assistants
 
-    [:octicons-arrow-right-24: Persona System](features/persona/overview.md)
+    [:octicons-arrow-right-24: Overview](features/persona/overview.md)
+
+-   :material-target:{ .lg .middle } **Content Strategy**
+
+    ---
+
+    AI-driven persona development and planning
+
+    [:octicons-arrow-right-24: Overview](features/content-strategy/overview.md)
+
+-   :material-robot:{ .lg .middle } **SIF & AI Agents**
+
+    ---
+
+    Intelligent agent system for content quality
+
+    [:octicons-arrow-right-24: Overview](features/sif-agents/overview.md)
+
+-   :material-calendar:{ .lg .middle } **Today's Workflow**
+
+    ---
+
+    Daily content operations and task management
+
+    [:octicons-arrow-right-24: Overview](features/todays-workflow/overview.md)
 
 -   :material-account-group:{ .lg .middle } **User Journeys**
 
     ---
 
-    Personalized paths for different user types
+    Role-based guides for different user types
 
     [:octicons-arrow-right-24: Choose Your Journey](user-journeys/overview.md)
 
+-   :material-api:{ .lg .middle } **API Reference**
+
+    ---
+
+    Complete API documentation and authentication
+
+    [:octicons-arrow-right-24: API Overview](api/overview.md)
+
+-   :material-widgets:{ .lg .middle } **Integrations**
+
+    ---
+
+    Platform integrations including Wix
+
+    [:octicons-arrow-right-24: Wix Integration](features/integrations/wix/overview.md)
+
+-   :material-currency-usd:{ .lg .middle } **Subscription**
+
+    ---
+
+    Plans, pricing, and billing
+
+    [:octicons-arrow-right-24: Overview](features/subscription/overview.md)
+
 </div>
 
-## What is ALwrity?
+## Quick Links
 
-ALwrity is an AI-powered digital marketing platform that revolutionizes content creation and SEO optimization. Our platform combines advanced AI technology with comprehensive marketing tools to help businesses create high-quality, SEO-optimized content at scale.
-
-### Key Features
-
-- **🤖 AI-Powered Content Generation**: Create blog posts, LinkedIn content, and Facebook posts with advanced AI
-- **👤 Personalized Writing Personas**: AI-powered writing assistants tailored to your unique voice and style
-- **📊 SEO Dashboard**: Comprehensive SEO analysis with Google Search Console integration
-- **🎯 Content Strategy**: AI-driven persona generation and content planning
-- **🔍 Research Integration**: Automated research and fact-checking capabilities
-- **📈 Performance Analytics**: Track content performance and optimize strategies
-- **🔒 Enterprise Security**: Secure, scalable platform for teams of all sizes
-
-### Getting Started
-
-1. **[Installation](getting-started/installation.md)** - Set up ALwrity on your system
-2. **[Configuration](getting-started/configuration.md)** - Configure API keys and settings
-3. **[First Steps](getting-started/first-steps.md)** - Create your first content piece
-4. **[Best Practices](guides/best-practices.md)** - Learn optimization techniques
-
-### Popular Guides
-
-- [Troubleshooting Common Issues](guides/troubleshooting.md)
-- [API Integration Guide](api/overview.md)
-- [Content Strategy Best Practices](features/content-strategy/overview.md)
-- [SEO Optimization Tips](features/seo-dashboard/overview.md)
-
-### Community & Support
-
-- **GitHub**: [Report issues and contribute](https://github.com/AJaySi/ALwrity)
-- **Documentation**: Comprehensive guides and API reference
-- **Community**: Join our developer community
+| Category | Links |
+|---|---|
+| **Getting Started** | [Installation](getting-started/installation.md) · [Configuration](getting-started/configuration.md) · [First Steps](getting-started/first-steps.md) |
+| **Content Creation** | [Blog Writer](features/blog-writer/overview.md) · [LinkedIn Writer](features/linkedin-writer/overview.md) · [Podcast Maker](features/podcast-maker/workflow-guide.md) · [Story Writer](features/story-writer/overview.md) |
+| **Media Production** | [Image Studio](features/image-studio/overview.md) · [Video Studio](features/video-studio/overview.md) · [YouTube Studio](features/youtube-studio/overview.md) |
+| **SEO & Marketing** | [SEO Dashboard](features/seo-dashboard/overview.md) · [Backlink Outreach](features/backlink-outreach/overview.md) · [Content Strategy](features/content-strategy/overview.md) |
+| **Platform** | [Today's Workflow](features/todays-workflow/overview.md) · [AI Agents](features/sif-agents/overview.md) · [Persona System](features/persona/overview.md) |
+| **Reference** | [API](api/overview.md) · [Troubleshooting](guides/troubleshooting.md) · [Best Practices](guides/best-practices.md) |
 
 ---
 
-*Ready to transform your content creation workflow? Start with our [Quick Start Guide](getting-started/quick-start.md) or explore our [AI Features](features/ai/assistive-writing.md).*
+*Ready to transform your content creation workflow? Start with our [Quick Start Guide](getting-started/quick-start.md) or [learn more about ALwrity](about.md).*