📚 Comprehensive Documentation Suite (Mil-Spec/IBM Redbook Style)

INVESTOR DOCUMENTATION:
- INVESTOR_BRIEF.md: Executive summary, capacity metrics, architecture overview
- PLATFORM_CAPABILITIES.md: 5 modules, 27 subcomponents catalog
- TECHNICAL_ARCHITECTURE.md: Mermaid diagrams, data flows, extension points

CTO/SENIOR DEV ONBOARDING:
- CTO_ONBOARDING.md: System overview, security model, operational runbook
- DEVELOPER_GUIDE.md: Clone→Run→Deploy workflow, debugging
- API_REFERENCE.md: 30+ endpoints with request/response specs
- DATABASE_SCHEMA.md: 30+ tables in Harris Matrix order
- COMPONENT_LIBRARY.md: 182 React components catalog

REFERENCE:
- GLOSSARY.md: 70+ platform terms defined
- ADMIN_PAGES_GUIDE.md: 66 admin pages by module

Style: BLUF format, zero marketing fluff, high-density tables

docs/ADMIN_PAGES_GUIDE.md

@@ -0,0 +1,304 @@
+# ADMIN PAGES GUIDE: Spark Platform
+
+> **BLUF**: 25+ admin page directories, 66 admin page files. All routes prefixed with `/admin/`.
+
+---
+
+## 1. Command Station
+
+### Main Dashboard
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin` | `pages/admin/index.astro` | Mission Control overview |
+
+Components: `SystemMonitor.tsx`, `SystemStatusBar.tsx`
+
+Features:
+- Sub-station status indicators
+- API health monitoring
+- Content integrity checks
+- Quick actions
+
+---
+
+## 2. Launchpad (Sites Module)
+
+### Site Management
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/sites` | `pages/admin/sites/index.astro` | Site list |
+| `/admin/sites/[id]` | `pages/admin/sites/[id]/index.astro` | Site dashboard |
+| `/admin/sites/edit` | `pages/admin/sites/edit.astro` | Site settings editor |
+| `/admin/sites/jumpstart` | `pages/admin/sites/jumpstart.astro` | Quick setup wizard |
+| `/admin/sites/import` | `pages/admin/sites/import.astro` | WordPress importer |
+| `/admin/sites/editor/[id]` | `pages/admin/sites/editor/[id].astro` | Page block editor |
+
+Components: `SitesManager.tsx`, `SiteEditor.tsx`, `SiteDashboard.tsx`, `JumpstartWizard.tsx`, `WPImporter.tsx`
+
+---
+
+## 3. Content Factory
+
+### Factory Dashboard
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/factory` | `pages/admin/factory/index.astro` | Kanban board |
+| `/admin/factory/articles` | `pages/admin/factory/articles.astro` | Article workbench |
+| `/admin/content-factory` | `pages/admin/content-factory.astro` | Simple generator |
+
+Components: `KanbanBoard.tsx`, `ArticleWorkbench.tsx`, `ContentFactoryDashboard.tsx`
+
+---
+
+## 4. Intelligence Library
+
+### Intelligence Hub
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/intelligence` | `pages/admin/intelligence/index.astro` | Module overview |
+| `/admin/intelligence/avatars` | `pages/admin/intelligence/avatars.astro` | Avatar manager |
+| `/admin/intelligence/variants` | `pages/admin/intelligence/variants.astro` | Avatar variants |
+| `/admin/intelligence/geo` | `pages/admin/intelligence/geo.astro` | Geo intelligence map |
+| `/admin/intelligence/spintax` | `pages/admin/intelligence/spintax.astro` | Spintax dictionaries |
+| `/admin/intelligence/patterns` | `pages/admin/intelligence/patterns.astro` | Cartesian patterns |
+
+Components: `AvatarIntelligenceManager.tsx`, `GeoIntelligenceManager.tsx`, `SpintaxManager.tsx`, `CartesianManager.tsx`
+
+---
+
+## 5. SEO Engine
+
+### Campaign & Article Management
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/seo/campaigns` | `pages/admin/seo/campaigns.astro` | Campaign list |
+| `/admin/seo/articles` | `pages/admin/seo/articles.astro` | Article management |
+| `/admin/seo/headlines` | `pages/admin/seo/headlines.astro` | Headline inventory |
+| `/admin/seo/fragments` | `pages/admin/seo/fragments.astro` | Content fragments |
+| `/admin/seo/wizard` | `pages/admin/seo/wizard.astro` | Campaign wizard |
+
+Components: `CampaignWizard.tsx`, `ArticleList.tsx`, `HeadlineGenerator.tsx`, `FragmentsManager.tsx`
+
+---
+
+## 6. Content Management
+
+### Pages & Posts
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/pages` | `pages/admin/pages/index.astro` | Pages list |
+| `/admin/pages/edit/[id]` | `pages/admin/pages/edit/[id].astro` | Page editor |
+| `/admin/posts` | `pages/admin/posts/index.astro` | Posts list |
+| `/admin/posts/edit/[id]` | `pages/admin/posts/edit/[id].astro` | Post editor |
+| `/admin/content/avatars` | `pages/admin/content/avatars.astro` | Legacy avatar content |
+| `/admin/content/geo_clusters` | `pages/admin/content/geo_clusters.astro` | Legacy geo content |
+
+Components: `PageEditor.tsx`, `PostEditor.tsx`, `PageList.tsx`, `PostList.tsx`
+
+---
+
+## 7. Collections (Generic CRUD)
+
+### Collection Manager
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/collections` | `pages/admin/collections/index.astro` | Collection browser |
+| `/admin/collections/page-blocks` | `pages/admin/collections/page-blocks.astro` | Page blocks |
+| `/admin/collections/offer-blocks` | `pages/admin/collections/offer-blocks.astro` | Offer templates |
+| `/admin/collections/headline-inventory` | `pages/admin/collections/headline-inventory.astro` | Headlines |
+| `/admin/collections/content-fragments` | `pages/admin/collections/content-fragments.astro` | Fragments |
+
+Components: `GenericCollectionManager.tsx`
+
+---
+
+## 8. Analytics
+
+### Analytics Dashboard
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/analytics` | `pages/admin/analytics/index.astro` | Metrics overview |
+| `/admin/analytics/events` | `pages/admin/analytics/events.astro` | Event log |
+| `/admin/analytics/conversions` | `pages/admin/analytics/conversions.astro` | Conversion tracking |
+| `/admin/analytics/pageviews` | `pages/admin/analytics/pageviews.astro` | Pageview data |
+
+Components: `MetricsDashboard.tsx`, `StatCard.tsx`, `ChartWidget.tsx`
+
+---
+
+## 9. Leads
+
+### Lead Management
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/leads` | `pages/admin/leads/index.astro` | Leads list |
+| `/admin/leads/[id]` | `pages/admin/leads/[id].astro` | Lead detail |
+
+Components: `LeadManager.tsx`, `LeadTable.tsx`
+
+---
+
+## 10. Media
+
+### Asset Management
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/media` | `pages/admin/media/index.astro` | Media browser |
+| `/admin/media/templates` | `pages/admin/media/templates.astro` | Image templates |
+
+Components: `ImageTemplateEditor.tsx`
+
+---
+
+## 11. Locations
+
+### Geographic Data
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/locations` | `pages/admin/locations.astro` | Location browser |
+
+Components: `LocationBrowser.tsx`
+
+---
+
+## 12. Scheduler
+
+### Content Scheduling
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/scheduler` | `pages/admin/scheduler/index.astro` | Calendar view |
+
+Components: `SchedulerCalendar.tsx`
+
+---
+
+## 13. Assembler
+
+### Article Assembly
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/assembler` | `pages/admin/assembler/index.astro` | Assembly dashboard |
+| `/admin/assembler/templates` | `pages/admin/assembler/templates.astro` | Template list |
+| `/admin/assembler/preview` | `pages/admin/assembler/preview.astro` | Preview tool |
+
+Components: `AssemblerDashboard.tsx`, `TemplateList.tsx`
+
+---
+
+## 14. Automations
+
+### Workflow Automation
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/automations` | `pages/admin/automations/index.astro` | Automation list |
+
+Components: `AutomationBuilder.tsx`
+
+---
+
+## 15. System
+
+### System Administration
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/system` | `pages/admin/system/index.astro` | System overview |
+| `/admin/system/work-log` | `pages/admin/system/work-log.astro` | Activity log |
+
+Components: `LogViewer.tsx`, `WorkLogViewer.tsx`
+
+---
+
+## 16. Settings
+
+### Platform Configuration
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/settings` | `pages/admin/settings.astro` | Settings manager |
+
+Components: `SettingsManager.tsx`
+
+---
+
+## 17. Testing
+
+### Diagnostics
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/admin/testing` | `pages/admin/testing/index.astro` | Test suite |
+| `/admin/testing/connection` | `pages/admin/testing/connection.astro` | API tests |
+| `/admin/testing/schema` | `pages/admin/testing/schema.astro` | Schema validation |
+| `/admin/testing/render` | `pages/admin/testing/render.astro` | Block render tests |
+| `/admin/testing/results` | `pages/admin/testing/results.astro` | Test results |
+
+Components: `TestRunner.tsx`, `ConnectionTester.tsx`, `TestResults.tsx`
+
+---
+
+## 18. Preview Routes
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/preview/site/[id]` | `pages/preview/site/[id].astro` | Site preview |
+| `/preview/page/[id]` | `pages/preview/page/[id].astro` | Page preview |
+| `/preview/post/[id]` | `pages/preview/post/[id].astro` | Post preview |
+| `/preview/article/[id]` | `pages/preview/article/[id].astro` | Article preview |
+
+---
+
+## 19. Quick Reference Table
+
+| Module | Root Path | Page Count |
+|--------|-----------|------------|
+| Command Station | `/admin` | 1 |
+| Launchpad | `/admin/sites/*` | 6 |
+| Factory | `/admin/factory/*` | 4 |
+| Intelligence | `/admin/intelligence/*` | 6 |
+| SEO Engine | `/admin/seo/*` | 5 |
+| Content | `/admin/pages/*`, `/admin/posts/*` | 6 |
+| Collections | `/admin/collections/*` | 10 |
+| Analytics | `/admin/analytics/*` | 4 |
+| Leads | `/admin/leads/*` | 2 |
+| Media | `/admin/media/*` | 1 |
+| Locations | `/admin/locations` | 1 |
+| Scheduler | `/admin/scheduler/*` | 1 |
+| Assembler | `/admin/assembler/*` | 5 |
+| Automations | `/admin/automations/*` | 1 |
+| System | `/admin/system/*` | 1 |
+| Settings | `/admin/settings` | 1 |
+| Testing | `/admin/testing/*` | 5 |
+| Preview | `/preview/*` | 4 |
+| **Total** | | **66** |
+
+---
+
+## 20. Access URLs
+
+### Production
+
+```
+https://spark.jumpstartscaling.com/admin
+https://launch.jumpstartscaling.com/preview/...
+```
+
+### Local Development
+
+```
+http://localhost:4321/admin
+```

docs/API_REFERENCE.md

@@ -0,0 +1,565 @@
+# API REFERENCE: Spark Platform Endpoints
+
+> **BLUF**: 30+ API endpoints organized by module. Public endpoints require no auth. Admin endpoints require Bearer token. God-mode requires X-God-Token header.
+
+---
+
+## 1. Authentication
+
+### Header Format
+
+```
+Authorization: Bearer <DIRECTUS_ADMIN_TOKEN>
+```
+
+### God-Mode Header
+
+```
+X-God-Token: <GOD_MODE_TOKEN>
+```
+
+---
+
+## 2. Public Endpoints (No Auth Required)
+
+### 2.1 Lead Submission
+
+**POST** `/api/lead`
+
+Submit a lead form.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | Contact name |
+| email | string | Yes | Contact email |
+| site_id | string | No | Originating site UUID |
+| source | string | No | Lead source identifier |
+
+**Request:**
+```json
+{
+    "name": "John Doe",
+    "email": "john@example.com",
+    "site_id": "uuid-here",
+    "source": "landing-page"
+}
+```
+
+**Response:** `201 Created`
+```json
+{
+    "success": true,
+    "id": "lead-uuid"
+}
+```
+
+---
+
+### 2.2 Form Submission
+
+**POST** `/api/forms/submit`
+
+Submit a generic form.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| form_id | string | Yes | Form definition UUID |
+| data | object | Yes | Form field values |
+
+**Request:**
+```json
+{
+    "form_id": "form-uuid",
+    "data": {
+        "name": "Jane Doe",
+        "email": "jane@example.com",
+        "message": "Hello"
+    }
+}
+```
+
+**Response:** `201 Created`
+```json
+{
+    "success": true,
+    "submission_id": "submission-uuid"
+}
+```
+
+---
+
+### 2.3 Analytics Tracking
+
+**POST** `/api/track/pageview`
+
+Record a page view.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| site_id | string | Site UUID |
+| page_path | string | URL path |
+| session_id | string | Anonymous session |
+
+**POST** `/api/track/event`
+
+Record a custom event.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| site_id | string | Site UUID |
+| event_name | string | Event identifier |
+| page_path | string | URL path |
+
+**POST** `/api/track/conversion`
+
+Record a conversion.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| site_id | string | Site UUID |
+| lead_id | string | Lead UUID |
+| conversion_type | string | Conversion category |
+| value | number | Monetary value |
+
+---
+
+## 3. SEO Engine Endpoints (Auth Required)
+
+### 3.1 Headline Generation
+
+**POST** `/api/seo/generate-headlines`
+
+Generate headline permutations from spintax.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| campaign_id | string | Campaign UUID |
+| spintax_root | string | Spintax template |
+| limit | number | Max headlines (default: 1000) |
+
+**Request:**
+```json
+{
+    "campaign_id": "campaign-uuid",
+    "spintax_root": "{Best|Top|Leading} {Dentist|Dental Clinic} in {City}",
+    "limit": 100
+}
+```
+
+**Response:**
+```json
+{
+    "generated": 100,
+    "headlines": [
+        "Best Dentist in Austin",
+        "Top Dental Clinic in Austin",
+        ...
+    ]
+}
+```
+
+---
+
+### 3.2 Article Generation
+
+**POST** `/api/seo/generate-article`
+
+Generate a single article.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| campaign_id | string | Campaign UUID |
+| headline | string | Article headline |
+| location | object | {city, state, county} |
+| avatar_id | string | Target avatar UUID |
+
+**Request:**
+```json
+{
+    "campaign_id": "campaign-uuid",
+    "headline": "Best Dentist in Austin",
+    "location": {
+        "city": "Austin",
+        "state": "TX",
+        "county": "Travis"
+    },
+    "avatar_id": "avatar-uuid"
+}
+```
+
+**Response:**
+```json
+{
+    "article_id": "article-uuid",
+    "title": "Best Dentist in Austin",
+    "content": "<html content>",
+    "meta_title": "Best Dentist in Austin, TX | YourBrand",
+    "meta_description": "Looking for..."
+}
+```
+
+---
+
+### 3.3 Batch Operations
+
+**GET** `/api/seo/articles`
+
+List generated articles.
+
+Query Parameters:
+| Param | Type | Description |
+|-------|------|-------------|
+| site_id | string | Filter by site |
+| campaign_id | string | Filter by campaign |
+| status | string | Filter by status |
+| limit | number | Results per page |
+| offset | number | Pagination offset |
+
+**POST** `/api/seo/approve-batch`
+
+Approve multiple articles.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| article_ids | string[] | Article UUIDs to approve |
+
+**POST** `/api/seo/publish-article`
+
+Publish a single article.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| article_id | string | Article UUID |
+
+---
+
+### 3.4 Content Processing
+
+**POST** `/api/seo/insert-links`
+
+Insert internal links into article content.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| article_id | string | Article UUID |
+| max_links | number | Maximum links to insert |
+| min_distance | number | Minimum words between links |
+
+**POST** `/api/seo/scan-duplicates`
+
+Scan for duplicate content.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| site_id | string | Site to scan |
+| threshold | number | Similarity threshold (0-1) |
+
+---
+
+### 3.5 Scheduling
+
+**POST** `/api/seo/schedule-production`
+
+Schedule article production.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| campaign_id | string | Campaign UUID |
+| target_count | number | Articles to generate |
+| velocity_mode | string | RAMP_UP, STEADY, SPIKES |
+| start_date | string | ISO date |
+
+**POST** `/api/seo/sitemap-drip`
+
+Update sitemap visibility.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| site_id | string | Site UUID |
+| batch_size | number | URLs per update |
+
+---
+
+### 3.6 Queue
+
+**POST** `/api/seo/process-queue`
+
+Process pending queue items.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| limit | number | Items to process |
+| priority | string | Filter by priority |
+
+**GET** `/api/seo/stats`
+
+Get SEO statistics.
+
+Query Parameters:
+| Param | Type | Description |
+|-------|------|-------------|
+| site_id | string | Filter by site |
+| campaign_id | string | Filter by campaign |
+
+---
+
+## 4. Location Endpoints (Auth Required)
+
+### 4.1 States
+
+**GET** `/api/locations/states`
+
+List all US states.
+
+**Response:**
+```json
+[
+    { "id": "uuid", "name": "Texas", "code": "TX" },
+    { "id": "uuid", "name": "California", "code": "CA" },
+    ...
+]
+```
+
+### 4.2 Counties
+
+**GET** `/api/locations/counties`
+
+Query Parameters:
+| Param | Type | Description |
+|-------|------|-------------|
+| state | string | State UUID or code |
+
+### 4.3 Cities
+
+**GET** `/api/locations/cities`
+
+Query Parameters:
+| Param | Type | Description |
+|-------|------|-------------|
+| county | string | County UUID |
+| limit | number | Results (default: 50) |
+
+---
+
+## 5. Campaign Endpoints (Auth Required)
+
+### 5.1 Campaigns CRUD
+
+**GET** `/api/campaigns`
+
+List campaigns.
+
+Query Parameters:
+| Param | Type | Description |
+|-------|------|-------------|
+| site_id | string | Filter by site |
+| status | string | Filter by status |
+
+**POST** `/api/campaigns`
+
+Create campaign.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| site_id | string | Site UUID |
+| name | string | Campaign name |
+| headline_spintax_root | string | Spintax template |
+| target_word_count | number | Word count target |
+| location_mode | string | city, county, state |
+
+---
+
+## 6. Admin Endpoints (Auth Required)
+
+### 6.1 Import
+
+**POST** `/api/admin/import-blueprint`
+
+Import site from external source.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| source_url | string | WordPress URL |
+| site_name | string | New site name |
+| import_pages | boolean | Include pages |
+| import_posts | boolean | Include posts |
+
+### 6.2 Work Log
+
+**GET** `/api/admin/worklog`
+
+Get system activity log.
+
+Query Parameters:
+| Param | Type | Description |
+|-------|------|-------------|
+| limit | number | Results per page |
+| level | string | Filter by level |
+| entity_type | string | Filter by entity |
+
+### 6.3 Queue Status
+
+**GET** `/api/admin/queues`
+
+Get queue status.
+
+**Response:**
+```json
+{
+    "pending": 42,
+    "processing": 5,
+    "completed_today": 150,
+    "failed_today": 3
+}
+```
+
+---
+
+## 7. Analytics Endpoints (Auth Required)
+
+### 7.1 Dashboard
+
+**GET** `/api/analytics/dashboard`
+
+Get analytics summary.
+
+Query Parameters:
+| Param | Type | Description |
+|-------|------|-------------|
+| site_id | string | Site UUID |
+| start_date | string | ISO date |
+| end_date | string | ISO date |
+
+**Response:**
+```json
+{
+    "pageviews": 1234,
+    "unique_sessions": 567,
+    "events": 89,
+    "conversions": 12,
+    "top_pages": [...],
+    "trend": [...]
+}
+```
+
+---
+
+## 8. Intelligence Endpoints (Auth Required)
+
+### 8.1 Patterns
+
+**GET** `/api/intelligence/patterns`
+
+Get Cartesian patterns.
+
+Query Parameters:
+| Param | Type | Description |
+|-------|------|-------------|
+| category | string | Filter by category |
+
+---
+
+## 9. Media Endpoints (Auth Required)
+
+### 9.1 Templates
+
+**GET** `/api/media/templates`
+
+List image templates.
+
+**POST** `/api/media/templates`
+
+Create image template.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| name | string | Template name |
+| svg_content | string | SVG markup |
+| variables | object | Token definitions |
+
+---
+
+## 10. Assembler Endpoints (Auth Required)
+
+### 10.1 Preview
+
+**POST** `/api/assembler/preview`
+
+Preview assembled article.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| template_id | string | Template UUID |
+| variables | object | Token values |
+
+### 10.2 Templates
+
+**GET** `/api/assembler/templates`
+
+List assembly templates.
+
+---
+
+## 11. Factory Endpoints (Auth Required)
+
+### 11.1 Send to Factory
+
+**POST** `/api/factory/send-to-factory`
+
+Queue content for processing.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| source | string | wordpress, manual |
+| source_id | string | Source item ID |
+| target_site_id | string | Destination site |
+
+---
+
+## 12. God-Mode Endpoints (Elevated Auth)
+
+### 12.1 Schema Operations
+
+**POST** `/god/schema/collections/create`
+
+Create new collection.
+
+**POST** `/god/schema/relations/create`
+
+Create new relation.
+
+**GET** `/god/schema/snapshot`
+
+Export full schema YAML.
+
+### 12.2 Data Operations
+
+**POST** `/god/data/bulk-insert`
+
+Insert multiple records.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| collection | string | Target collection |
+| items | object[] | Records to insert |
+
+---
+
+## 13. Error Responses
+
+| Status | Meaning |
+|--------|---------|
+| 400 | Bad Request - invalid input |
+| 401 | Unauthorized - missing/invalid token |
+| 403 | Forbidden - insufficient permissions |
+| 404 | Not Found - resource doesn't exist |
+| 500 | Server Error - internal failure |
+
+**Error Format:**
+```json
+{
+    "error": true,
+    "message": "Description of error",
+    "code": "ERROR_CODE"
+}
+```

docs/COMPONENT_LIBRARY.md

@@ -0,0 +1,325 @@
+# COMPONENT LIBRARY: Spark Platform UI Catalog
+
+> **BLUF**: 182 React components in 14 directories. Admin (95 files), Blocks (25 files), UI (18 files).
+
+---
+
+## 1. Component Organization
+
+```
+frontend/src/components/
+├── admin/              # 95 files - Dashboard components
+├── analytics/          # 4 files - Analytics widgets
+├── assembler/          # 8 files - Article assembly
+├── automations/        # 1 file - Workflow automation
+├── blocks/             # 25 files - Page builder blocks
+├── collections/        # 1 file - Generic collection UI
+├── debug/              # 1 file - Debug utilities
+├── engine/             # 4 files - Rendering engine
+├── factory/            # 9 files - Content Factory
+├── intelligence/       # 7 files - Intelligence Library
+├── layout/             # 1 file - Layout components
+├── providers/          # 1 file - React providers
+├── testing/            # 7 files - Test utilities
+└── ui/                 # 18 files - Shadcn primitives
+```
+
+---
+
+## 2. Admin Components
+
+Location: `frontend/src/components/admin/`
+
+### 2.1 Intelligence Managers
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| AvatarIntelligenceManager | `intelligence/AvatarIntelligenceManager.tsx` | Avatar CRUD + stats |
+| GeoIntelligenceManager | `intelligence/GeoIntelligenceManager.tsx` | Map + location CRUD |
+| SpintaxManager | `intelligence/SpintaxManager.tsx` | Dictionary editor |
+| CartesianManager | `intelligence/CartesianManager.tsx` | Pattern builder |
+| PatternAnalyzer | `intelligence/PatternAnalyzer.tsx` | Pattern testing |
+| OfferBlocksManager | `intelligence/OfferBlocksManager.tsx` | Offer template CRUD |
+| IntelligenceDashboard | `intelligence/IntelligenceDashboard.tsx` | Module overview |
+
+### 2.2 Factory Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| KanbanBoard | `factory/KanbanBoard.tsx` | Drag-drop workflow |
+| ArticleWorkbench | `factory/ArticleWorkbench.tsx` | Article editing |
+| BulkGrid | `factory/BulkGrid.tsx` | Multi-select operations |
+| JobsMonitor | `factory/JobsMonitor.tsx` | Queue status |
+| SendToFactoryButton | `factory/SendToFactoryButton.tsx` | Factory trigger |
+
+### 2.3 SEO Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| CampaignWizard | `seo/CampaignWizard.tsx` | Campaign creation wizard |
+| ArticleList | `seo/ArticleList.tsx` | Article table |
+| HeadlineGenerator | `seo/HeadlineGenerator.tsx` | Headline permutation UI |
+| FragmentsManager | `seo/FragmentsManager.tsx` | Fragment CRUD |
+| ArticleEditor | `seo/ArticleEditor.tsx` | Single article edit |
+| ArticlePreview | `seo/ArticlePreview.tsx` | Preview renderer |
+
+### 2.4 Sites Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| SitesManager | `sites/SitesManager.tsx` | Site list + actions |
+| SiteEditor | `sites/SiteEditor.tsx` | Site settings |
+| SiteDashboard | `sites/SiteDashboard.tsx` | Site overview |
+| PagesList | `sites/PagesList.tsx` | Page management |
+| NavigationEditor | `sites/NavigationEditor.tsx` | Menu builder |
+| ThemeSettings | `sites/ThemeSettings.tsx` | Theme configuration |
+
+### 2.5 Content Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| PageEditor | `content/PageEditor.tsx` | Block-based editor |
+| PostEditor | `content/PostEditor.tsx` | Blog post editor |
+| ContentFactoryDashboard | `content/ContentFactoryDashboard.tsx` | Factory overview |
+| VisualBlockEditor | `content/VisualBlockEditor.tsx` | Visual editor |
+
+### 2.6 System Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| SystemMonitor | `system/SystemMonitor.tsx` | Health dashboard |
+| SystemStatusBar | `system/SystemStatusBar.tsx` | Status indicator |
+| SettingsManager | `SettingsManager.tsx` | Platform settings |
+| LogViewer | `system/LogViewer.tsx` | Work log viewer |
+| WPImporter | `import/WPImporter.tsx` | WordPress import |
+| JumpstartWizard | `jumpstart/JumpstartWizard.tsx` | Quick site setup |
+
+### 2.7 Testing Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| TestRunner | `testing/TestRunner.tsx` | Test executor |
+| TestResults | `testing/TestResults.tsx` | Results display |
+| ConnectionTester | `testing/ConnectionTester.tsx` | API tests |
+
+---
+
+## 3. Block Components
+
+Location: `frontend/src/components/blocks/`
+
+### Page Builder Blocks
+
+| Block | File | Description |
+|-------|------|-------------|
+| HeroBlock | `HeroBlock.tsx` | Full-width header with CTA |
+| RichTextBlock | `RichTextBlock.tsx` | SEO-optimized prose |
+| ColumnsBlock | `ColumnsBlock.tsx` | Multi-column layout |
+| MediaBlock | `MediaBlock.tsx` | Image/video with caption |
+| StepsBlock | `StepsBlock.tsx` | Numbered process |
+| QuoteBlock | `QuoteBlock.tsx` | Testimonial/blockquote |
+| GalleryBlock | `GalleryBlock.tsx` | Image grid |
+| FAQBlock | `FAQBlock.tsx` | Accordion with schema.org |
+| PostsBlock | `PostsBlock.tsx` | Blog listing |
+| FormBlock | `FormBlock.tsx` | Lead capture form |
+| CTABlock | `CTABlock.tsx` | Call-to-action |
+| MapBlock | `MapBlock.tsx` | Embedded map |
+| CardBlock | `CardBlock.tsx` | Card layout |
+| DividerBlock | `DividerBlock.tsx` | Section separator |
+| SpacerBlock | `SpacerBlock.tsx` | Vertical spacing |
+| HeaderBlock | `HeaderBlock.tsx` | Section header |
+| ListBlock | `ListBlock.tsx` | Bullet/numbered list |
+| TableBlock | `TableBlock.tsx` | Data table |
+| CodeBlock | `CodeBlock.tsx` | Code snippet |
+| EmbedBlock | `EmbedBlock.tsx` | External embed |
+
+### Block Renderer
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| BlockRenderer | `engine/BlockRenderer.tsx` | JSON → component mapper |
+| BlockWrapper | `engine/BlockWrapper.tsx` | Styling container |
+
+---
+
+## 4. UI Components (Shadcn-style)
+
+Location: `frontend/src/components/ui/`
+
+### Form Controls
+
+| Component | File | Usage |
+|-----------|------|-------|
+| Button | `button.tsx` | `<Button variant="default">` |
+| Input | `input.tsx` | `<Input type="text">` |
+| Textarea | `textarea.tsx` | `<Textarea rows={4}>` |
+| Select | `select.tsx` | `<Select><SelectItem>` |
+| Switch | `switch.tsx` | `<Switch checked={}>` |
+| Slider | `slider.tsx` | `<Slider value={}>` |
+| Label | `label.tsx` | `<Label htmlFor="">` |
+
+### Layout
+
+| Component | File | Usage |
+|-----------|------|-------|
+| Card | `card.tsx` | `<Card><CardHeader>...` |
+| Dialog | `dialog.tsx` | `<Dialog><DialogContent>` |
+| Sheet | `sheet.tsx` | `<Sheet><SheetContent>` |
+| Table | `table.tsx` | `<Table><TableRow>` |
+| Tabs | `tabs.tsx` | `<Tabs><TabsContent>` |
+| Separator | `separator.tsx` | `<Separator>` |
+
+### Feedback
+
+| Component | File | Usage |
+|-----------|------|-------|
+| Toast | `toast.tsx` | `toast({ title, description })` |
+| Tooltip | `tooltip.tsx` | `<Tooltip><TooltipContent>` |
+| DropdownMenu | `dropdown-menu.tsx` | `<DropdownMenu><DropdownMenuItem>` |
+
+---
+
+## 5. Analytics Components
+
+Location: `frontend/src/components/analytics/`
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| MetricsDashboard | `MetricsDashboard.tsx` | Analytics overview |
+| ChartWidget | `ChartWidget.tsx` | Data visualization |
+| StatCard | `StatCard.tsx` | Single metric display |
+
+---
+
+## 6. Engine Components
+
+Location: `frontend/src/components/engine/`
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| BlockRenderer | `BlockRenderer.tsx` | Renders JSON blocks |
+| PageRenderer | `PageRenderer.tsx` | Full page rendering |
+| ArticleRenderer | `ArticleRenderer.tsx` | Article display |
+| PreviewFrame | `PreviewFrame.tsx` | Preview container |
+
+---
+
+## 7. Automations Components
+
+Location: `frontend/src/components/automations/`
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| AutomationBuilder | `AutomationBuilder.tsx` | Workflow editor |
+
+---
+
+## 8. Usage Examples
+
+### Using Admin Components
+
+```tsx
+import { SitesManager } from '@/components/admin/sites/SitesManager';
+
+export default function SitesPage() {
+    return <SitesManager client:load />;
+}
+```
+
+### Using UI Components
+
+```tsx
+import { Button } from '@/components/ui/button';
+import { Card, CardHeader, CardContent } from '@/components/ui/card';
+
+function MyComponent() {
+    return (
+        <Card>
+            <CardHeader>Title</CardHeader>
+            <CardContent>
+                <Button variant="default">Click</Button>
+            </CardContent>
+        </Card>
+    );
+}
+```
+
+### Using Blocks
+
+```tsx
+import { BlockRenderer } from '@/components/engine/BlockRenderer';
+
+function PageContent({ blocks }) {
+    return <BlockRenderer blocks={blocks} />;
+}
+```
+
+---
+
+## 9. Design System
+
+### Colors (Titanium Pro)
+
+| Name | Value | Usage |
+|------|-------|-------|
+| Background | `#09090b` (zinc-950) | Page background |
+| Primary | `#eab308` (yellow-500) | Accent, buttons |
+| Success | `#22c55e` (green-500) | Positive actions |
+| Accent | `#a855f7` (purple-500) | Highlights |
+| Text | `#ffffff` / `#94a3b8` | Primary / secondary |
+
+### Typography
+
+| Element | Class |
+|---------|-------|
+| Heading 1 | `text-4xl font-bold` |
+| Heading 2 | `text-2xl font-semibold` |
+| Body | `text-base text-slate-300` |
+| Small | `text-sm text-slate-400` |
+
+### Spacing
+
+| Size | Value | Usage |
+|------|-------|-------|
+| xs | `4px` | Tight padding |
+| sm | `8px` | Compact spacing |
+| md | `16px` | Standard spacing |
+| lg | `24px` | Section spacing |
+| xl | `32px` | Large sections |
+
+---
+
+## 10. Component Creation Guidelines
+
+### File Structure
+
+```tsx
+// components/admin/MyFeature/MyComponent.tsx
+
+import { useState } from 'react';
+import { Button } from '@/components/ui/button';
+
+interface MyComponentProps {
+    data: MyType;
+    onAction?: () => void;
+}
+
+export function MyComponent({ data, onAction }: MyComponentProps) {
+    const [state, setState] = useState(false);
+    
+    return (
+        <div className="p-4 bg-zinc-900 rounded-lg">
+            {/* Component content */}
+        </div>
+    );
+}
+```
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Component | PascalCase | `MyComponent.tsx` |
+| Hook | camelCase, use-prefix | `useMyHook.ts` |
+| Utility | camelCase | `formatDate.ts` |
+| Type | PascalCase | `MyComponentProps` |

docs/CTO_ONBOARDING.md

@@ -0,0 +1,296 @@
+# CTO ONBOARDING: Spark Platform Technical Leadership Guide
+
+> **BLUF**: Spark is a multi-tenant content scaling platform. 30+ PostgreSQL tables, 30+ API endpoints, 182 React components. Self-hosted via Docker Compose on Coolify. This document provides the 30,000ft view for technical leadership.
+
+---
+
+## 1. System Overview
+
+### 1.1 What Spark Does
+1. Ingests buyer personas, location data, content templates
+2. Computes Cartesian products of variations
+3. Generates unique SEO articles at scale
+4. Manages multi-site content distribution
+
+### 1.2 Key Metrics
+| Metric | Value |
+|--------|-------|
+| Max articles per campaign config | 50,000+ |
+| Database collections | 30+ |
+| API endpoints | 30+ |
+| React components | 182 |
+| Admin pages | 25 directories |
+
+---
+
+## 2. Repository Structure
+
+```
+spark/
+├── frontend/                 # Astro SSR + React
+│   ├── src/
+│   │   ├── components/      # 182 React components
+│   │   │   ├── admin/      # Admin dashboard (95 files)
+│   │   │   ├── blocks/     # Page builder (25 files)
+│   │   │   ├── ui/         # Shadcn-style (18 files)
+│   │   │   └── ...
+│   │   ├── pages/
+│   │   │   ├── admin/      # 25 admin directories
+│   │   │   ├── api/        # 15 API directories
+│   │   │   └── preview/    # 4 preview routes
+│   │   ├── lib/
+│   │   │   ├── directus/   # SDK client, fetchers
+│   │   │   └── schemas.ts  # TypeScript types
+│   │   └── hooks/          # React hooks
+│   ├── Dockerfile
+│   └── package.json
+│
+├── directus-extensions/      # Custom Directus code
+│   ├── endpoints/           # 4 custom endpoints
+│   └── hooks/              # 2 event hooks
+│
+├── docs/                     # Documentation (this folder)
+├── scripts/                  # Utility scripts
+├── complete_schema.sql       # Golden Schema
+├── docker-compose.yaml       # Infrastructure
+└── start.sh                  # Directus startup
+```
+
+---
+
+## 3. Technology Stack
+
+| Layer | Technology | Version | Rationale |
+|-------|------------|---------|-----------|
+| Frontend | Astro | 4.7 | SSR + Islands = optimal performance |
+| UI | React | 18.3 | Component ecosystem, team familiarity |
+| Styling | Tailwind | 3.4 | Utility-first, fast iteration |
+| State | React Query | 5.x | Server state management, caching |
+| Backend | Directus | 11 | Headless CMS, auto-generated API |
+| Database | PostgreSQL | 16 | ACID, JSON support, extensible |
+| Geo | PostGIS | 3.4 | Spatial queries for location data |
+| Cache | Redis | 7 | Session + queue backing store |
+| Queue | BullMQ | - | Robust job processing |
+| Deploy | Coolify | - | Self-hosted PaaS, Docker-native |
+
+---
+
+## 4. Database Schema Summary
+
+### 4.1 Creation Order (Harris Matrix)
+
+| Batch | Description | Tables |
+|-------|-------------|--------|
+| 1: Foundation | Zero dependencies | sites, campaign_masters, avatar_intelligence, avatar_variants, cartesian_patterns, geo_intelligence, offer_blocks |
+| 2: Walls | Depend on Batch 1 | generated_articles, generation_jobs, pages, posts, leads, headline_inventory, content_fragments |
+| 3: Roof | Complex dependencies | link_targets, globals, navigation, work_log, hub_pages, forms, form_submissions, site_analytics, events, pageviews, conversions, locations_* |
+
+### 4.2 Parent Tables
+
+| Table | Purpose | Children |
+|-------|---------|----------|
+| `sites` | Multi-tenant root | 10+ tables reference via `site_id` |
+| `campaign_masters` | Campaign config | 3 tables reference via `campaign_id` |
+
+### 4.3 Key Relationships
+
+```
+sites ──┬── pages
+        ├── posts
+        ├── generated_articles
+        ├── leads
+        ├── navigation
+        ├── globals (singleton per site)
+        └── site_analytics
+
+campaign_masters ──┬── headline_inventory
+                   ├── content_fragments
+                   └── generated_articles
+```
+
+Full schema: See `docs/DATABASE_SCHEMA.md`
+
+---
+
+## 5. API Surface
+
+### 5.1 Public Endpoints (No Auth)
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/lead` | POST | Lead form submission |
+| `/api/forms/submit` | POST | Generic form handler |
+| `/api/track/*` | POST | Analytics tracking |
+
+### 5.2 Admin Endpoints (Token Required)
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/seo/generate-*` | POST | Content generation |
+| `/api/seo/approve-batch` | POST | Workflow advancement |
+| `/api/campaigns` | GET/POST | Campaign CRUD |
+| `/api/admin/*` | Various | Administrative ops |
+
+### 5.3 God-Mode Endpoints (Elevated Token)
+
+| Endpoint | Purpose |
+|----------|---------|
+| `/god/schema/collections/create` | Create new collection |
+| `/god/schema/snapshot` | Export schema YAML |
+| `/god/data/bulk-insert` | Mass data insert |
+
+Full API reference: See `docs/API_REFERENCE.md`
+
+---
+
+## 6. Extension Points
+
+### 6.1 Adding New Features
+
+| Extension Type | Location | Process |
+|---------------|----------|---------|
+| New Collection | `complete_schema.sql` | Add table, update schemas.ts, add admin page |
+| New API Endpoint | `frontend/src/pages/api/` | Export async handler |
+| New Admin Page | `frontend/src/pages/admin/` | Create .astro file, add component |
+| New Block Type | `frontend/src/components/blocks/` | Create component, register in BlockRenderer |
+| New Directus Extension | `directus-extensions/` | Add endpoint or hook, restart container |
+
+### 6.2 Schema Modification Process
+
+1. Update `complete_schema.sql` (maintain Harris Matrix order)
+2. Update `frontend/src/lib/schemas.ts` (TypeScript types)
+3. Run `npm run build` to verify types
+4. Deploy with `FORCE_FRESH_INSTALL=true` (CAUTION: wipes DB)
+
+### 6.3 API Modification Process
+
+1. Create/edit file in `frontend/src/pages/api/`
+2. Export handler: `export async function POST({ request })`
+3. Test locally: `npm run dev`
+4. Update `docs/API_REFERENCE.md`
+5. Git push triggers deploy
+
+---
+
+## 7. Security Model
+
+### 7.1 Authentication Layers
+
+| Layer | Method | Protection |
+|-------|--------|------------|
+| Directus Admin | Email/Password | Full CMS access |
+| API Tokens | Static Bearer | Scoped collection access |
+| God-Mode | X-God-Token header | Schema operations only |
+| Public | No auth | Read-only published content |
+
+### 7.2 Multi-Tenant Isolation
+
+- All content tables have `site_id` FK
+- Queries filter by `site_id` automatically
+- No cross-tenant data leakage possible via standard API
+
+### 7.3 CORS Configuration
+
+```yaml
+CORS_ORIGIN: 'https://spark.jumpstartscaling.com,https://launch.jumpstartscaling.com,http://localhost:4321'
+```
+
+Modify in `docker-compose.yaml` for additional origins.
+
+---
+
+## 8. Performance Considerations
+
+### 8.1 Current Optimizations
+
+| Area | Technique |
+|------|-----------|
+| SSR | Islands Architecture (minimal JS) |
+| Database | Indexed FKs, status fields |
+| API | Field selection, pagination |
+| Build | Brotli compression, code splitting |
+
+### 8.2 Scaling Paths
+
+| Constraint | Solution |
+|------------|----------|
+| Database load | Read replicas, connection pooling |
+| API throughput | Horizontal frontend replicas |
+| Queue depth | Additional BullMQ workers |
+| Storage | Object storage (S3-compatible) |
+
+### 8.3 Known Bottlenecks
+
+| Area | Issue | Mitigation |
+|------|-------|------------|
+| Article generation | CPU-bound spintax | Parallelized in BullMQ |
+| Large campaigns | Memory for Cartesian | Streaming/batched processing |
+| Image generation | Canvas rendering | Queue-based async |
+
+---
+
+## 9. Operational Runbook
+
+### 9.1 Deployment
+
+```bash
+git push origin main  # Coolify auto-deploys
+```
+
+### 9.2 Logs Access
+
+Via Coolify UI: Services → [container] → Logs
+
+### 9.3 Database Access
+
+```bash
+# Via Coolify terminal
+docker exec -it [postgres-container] psql -U postgres -d directus
+```
+
+### 9.4 Fresh Install (CAUTION)
+
+Set in Coolify environment:
+```
+FORCE_FRESH_INSTALL=true
+```
+Deploys, wipes DB, runs schema. **Data loss warning**.
+
+### 9.5 Health Checks
+
+| Service | Endpoint | Expected |
+|---------|----------|----------|
+| Directus | `/server/health` | 200 OK |
+| Frontend | `/` | 200 OK |
+
+---
+
+## 10. Critical Files
+
+| File | Purpose | Change Impact |
+|------|---------|---------------|
+| `complete_schema.sql` | Database schema | Requires fresh install |
+| `docker-compose.yaml` | Infrastructure | Requires redeploy |
+| `frontend/src/lib/schemas.ts` | TypeScript types | Build failure if wrong |
+| `frontend/src/lib/directus/client.ts` | API client | Connectivity issues |
+| `start.sh` | Directus boot | Startup failure |
+
+---
+
+## 11. Team Onboarding Checklist
+
+### For New Developers
+- [ ] Clone repo, run `npm install` in frontend
+- [ ] Copy `.env.example` to `.env`
+- [ ] Run `docker-compose up -d` (or connect to staging)
+- [ ] Run `npm run dev` in frontend
+- [ ] Access `http://localhost:4321/admin`
+- [ ] Read `docs/DEVELOPER_GUIDE.md`
+
+### For Technical Leadership
+- [ ] Review this document
+- [ ] Review `docs/TECHNICAL_ARCHITECTURE.md`
+- [ ] Review `docs/DATABASE_SCHEMA.md`
+- [ ] Access Coolify dashboard
+- [ ] Access Directus admin
+- [ ] Review deployment history in Coolify

docs/DATABASE_SCHEMA.md

@@ -0,0 +1,459 @@
+# DATABASE SCHEMA: Spark Platform
+
+> **BLUF**: 30+ PostgreSQL tables in Harris Matrix order. `sites` and `campaign_masters` are super parents. All content tables FK to `site_id`.
+
+---
+
+## 1. Schema Creation Order
+
+### Harris Matrix Dependency Layers
+
+| Batch | Layer | Description |
+|-------|-------|-------------|
+| 1 | Foundation | Zero dependencies. Create first. |
+| 2 | Walls | Depend only on Batch 1. |
+| 3 | Roof | Multiple dependencies or self-referential. |
+
+---
+
+## 2. Batch 1: Foundation Tables
+
+### 2.1 sites (SUPER PARENT)
+
+**Purpose**: Multi-tenant root. All content tables reference this.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK, DEFAULT gen_random_uuid() | Primary key |
+| status | VARCHAR(50) | DEFAULT 'active' | active, inactive, archived |
+| name | VARCHAR(255) | NOT NULL | Site display name |
+| url | VARCHAR(500) | | Site domain URL |
+| date_created | TIMESTAMP | DEFAULT NOW() | Creation timestamp |
+| date_updated | TIMESTAMP | DEFAULT NOW() | Last update |
+
+**Children**: 10+ tables reference via `site_id`
+
+---
+
+### 2.2 campaign_masters (SUPER PARENT)
+
+**Purpose**: SEO campaign configuration.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'active' | active, inactive, completed |
+| site_id | UUID | FK → sites(id) CASCADE | Owning site |
+| name | VARCHAR(255) | NOT NULL | Campaign name |
+| headline_spintax_root | TEXT | | Spintax template |
+| target_word_count | INTEGER | DEFAULT 1500 | Target article length |
+| location_mode | VARCHAR(50) | | city, county, state |
+| batch_count | INTEGER | | Articles per batch |
+| date_created | TIMESTAMP | DEFAULT NOW() | |
+| date_updated | TIMESTAMP | DEFAULT NOW() | |
+
+**Children**: headline_inventory, content_fragments, (ref by generated_articles)
+
+---
+
+### 2.3 avatar_intelligence
+
+**Purpose**: Buyer persona profiles.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'published' | published, draft |
+| base_name | VARCHAR(255) | | Persona name |
+| wealth_cluster | VARCHAR(100) | | Economic profile |
+| pain_points | JSONB | | Array of pain points |
+| demographics | JSONB | | Demographic data |
+
+---
+
+### 2.4 avatar_variants
+
+**Purpose**: Gender/style variations of avatars.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'published' | |
+| name | VARCHAR(255) | | Variant name |
+| prompt_modifier | TEXT | | AI prompt adjustments |
+
+---
+
+### 2.5 cartesian_patterns
+
+**Purpose**: Title/hook formula combinations.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'published' | |
+| name | VARCHAR(255) | | Pattern name |
+| pattern_logic | TEXT | | Formula definition |
+
+---
+
+### 2.6 geo_intelligence
+
+**Purpose**: Geographic targeting data.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'published' | |
+| city | VARCHAR(255) | | City name |
+| state | VARCHAR(255) | | State name |
+| population | INTEGER | | Population count |
+
+---
+
+### 2.7 offer_blocks
+
+**Purpose**: Promotional content templates.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'published' | |
+| name | VARCHAR(255) | | Block name |
+| html_content | TEXT | | Template HTML |
+
+---
+
+## 3. Batch 2: First-Level Children
+
+### 3.1 generated_articles
+
+**Purpose**: SEO articles created by Content Factory.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'draft' | draft, published, archived |
+| site_id | UUID | FK → sites(id) CASCADE | Owning site |
+| campaign_id | UUID | FK → campaign_masters(id) SET NULL | Source campaign |
+| title | VARCHAR(255) | | Article title |
+| content | TEXT | | Full HTML body |
+| slug | VARCHAR(255) | | URL slug |
+| is_published | BOOLEAN | | Publication flag |
+| schema_json | JSONB | | Schema.org data |
+| date_created | TIMESTAMP | DEFAULT NOW() | |
+| date_updated | TIMESTAMP | | |
+
+---
+
+### 3.2 generation_jobs
+
+**Purpose**: Content generation queue.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'pending' | pending, processing, completed, failed |
+| site_id | UUID | FK → sites(id) CASCADE | Owning site |
+| batch_size | INTEGER | DEFAULT 10 | Items per batch |
+| target_quantity | INTEGER | | Total target |
+| filters | JSONB | | Query filters |
+| current_offset | INTEGER | | Progress marker |
+| progress | INTEGER | DEFAULT 0 | Percentage |
+
+---
+
+### 3.3 pages
+
+**Purpose**: Site pages (blocks-based content).
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'published' | published, draft |
+| site_id | UUID | FK → sites(id) CASCADE | Owning site |
+| title | VARCHAR(255) | | Page title |
+| slug | VARCHAR(255) | | URL slug |
+| permalink | VARCHAR(255) | | Full path |
+| content | TEXT | | Legacy HTML |
+| blocks | JSONB | | Block definitions |
+| schema_json | JSONB | | Schema.org data |
+| seo_title | VARCHAR(255) | | Meta title |
+| seo_description | TEXT | | Meta description |
+| seo_image | UUID | FK → directus_files | OG image |
+| date_created | TIMESTAMP | | |
+| date_updated | TIMESTAMP | | |
+
+---
+
+### 3.4 posts
+
+**Purpose**: Blog posts.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'published' | published, draft |
+| site_id | UUID | FK → sites(id) CASCADE | Owning site |
+| title | VARCHAR(255) | | Post title |
+| slug | VARCHAR(255) | | URL slug |
+| excerpt | TEXT | | Summary text |
+| content | TEXT | | Full HTML body |
+| featured_image | UUID | FK → directus_files | Hero image |
+| published_at | TIMESTAMP | | Publication date |
+| category | VARCHAR(100) | | Post category |
+| author | UUID | FK → directus_users | Author |
+| schema_json | JSONB | | Schema.org data |
+| date_created | TIMESTAMP | | |
+| date_updated | TIMESTAMP | | |
+
+---
+
+### 3.5 leads
+
+**Purpose**: Lead capture data.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'new' | new, contacted, qualified, converted |
+| site_id | UUID | FK → sites(id) SET NULL | Source site |
+| email | VARCHAR(255) | | Contact email |
+| name | VARCHAR(255) | | Contact name |
+| source | VARCHAR(100) | | Lead source |
+
+---
+
+### 3.6 headline_inventory
+
+**Purpose**: Generated headline variations.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'active' | active, used, archived |
+| campaign_id | UUID | FK → campaign_masters(id) CASCADE | Source campaign |
+| headline_text | VARCHAR(255) | | Generated headline |
+| is_used | BOOLEAN | DEFAULT FALSE | Usage flag |
+
+---
+
+### 3.7 content_fragments
+
+**Purpose**: Modular content blocks for article assembly.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'active' | active, archived |
+| campaign_id | UUID | FK → campaign_masters(id) CASCADE | Source campaign |
+| fragment_text | TEXT | | Fragment content |
+| fragment_type | VARCHAR(50) | | Pillar: intro_hook, pillar_1, etc. |
+
+---
+
+## 4. Batch 3: Complex Children
+
+### 4.1 link_targets
+
+**Purpose**: Internal linking configuration.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| status | VARCHAR(50) | DEFAULT 'active' | active, inactive |
+| site_id | UUID | FK → sites(id) CASCADE | Owning site |
+| target_url | VARCHAR(500) | | Link destination |
+| anchor_text | VARCHAR(255) | | Link text |
+| keyword_focus | VARCHAR(255) | | Target keyword |
+
+---
+
+### 4.2 globals
+
+**Purpose**: Site-wide settings (singleton per site).
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| site_id | UUID | FK → sites(id) CASCADE | Owning site |
+| title | VARCHAR(255) | | Site title |
+| description | TEXT | | Site description |
+| logo | UUID | FK → directus_files | Logo image |
+
+---
+
+### 4.3 navigation
+
+**Purpose**: Site menu structure.
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK | Primary key |
+| site_id | UUID | FK → sites(id) CASCADE | Owning site |
+| label | VARCHAR(255) | NOT NULL | Link text |
+| url | VARCHAR(500) | NOT NULL | Link URL |
+| parent | UUID | FK → navigation(id) | Parent item |
+| target | VARCHAR(20) | | _self, _blank |
+| sort | INTEGER | | Display order |
+
+---
+
+## 5. Analytics & System Tables
+
+### 5.1 work_log
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | SERIAL | Primary key |
+| site_id | UUID | Related site |
+| action | VARCHAR | Action type |
+| entity_type | VARCHAR | Affected entity |
+| entity_id | VARCHAR | Entity UUID |
+| details | JSONB | Additional data |
+| level | VARCHAR | debug, info, warning, error |
+| status | VARCHAR | Status text |
+| timestamp | TIMESTAMP | Event time |
+| user | UUID | Acting user |
+
+---
+
+### 5.2 forms
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| site_id | UUID | Owning site |
+| name | VARCHAR | Form name |
+| fields | JSONB | Field definitions |
+| submit_action | VARCHAR | webhook, email, store |
+| success_message | TEXT | Confirmation text |
+| redirect_url | VARCHAR | Post-submit redirect |
+
+---
+
+### 5.3 form_submissions
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| form | UUID | FK → forms |
+| data | JSONB | Submitted values |
+| date_created | TIMESTAMP | Submission time |
+
+---
+
+### 5.4 Location Tables
+
+**locations_states**
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| name | VARCHAR | State name |
+| code | VARCHAR(2) | State abbreviation |
+
+**locations_counties**
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| name | VARCHAR | County name |
+| state | UUID | FK → locations_states |
+| population | INTEGER | Population count |
+
+**locations_cities**
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| name | VARCHAR | City name |
+| state | UUID | FK → locations_states |
+| county | UUID | FK → locations_counties |
+| population | INTEGER | Population count |
+
+---
+
+### 5.5 Analytics Tables
+
+**site_analytics**
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| site_id | UUID | FK → sites |
+| google_ads_id | VARCHAR | GA4 property ID |
+| fb_pixel_id | VARCHAR | Meta pixel ID |
+
+**events**
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| site_id | UUID | FK → sites |
+| event_name | VARCHAR | Event identifier |
+| page_path | VARCHAR | URL path |
+| timestamp | TIMESTAMP | Event time |
+
+**pageviews**
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| site_id | UUID | FK → sites |
+| page_path | VARCHAR | URL path |
+| session_id | VARCHAR | Anonymous session |
+| timestamp | TIMESTAMP | View time |
+
+**conversions**
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| site_id | UUID | FK → sites |
+| lead | UUID | FK → leads |
+| conversion_type | VARCHAR | Type identifier |
+| value | DECIMAL | Monetary value |
+
+---
+
+## 6. Relationship Diagram
+
+```
+sites ─────────────────────────────────────────────────────────┐
+  │                                                            │
+  ├── campaign_masters ─┬── headline_inventory                 │
+  │                     ├── content_fragments                  │
+  │                     └── (ref) generated_articles           │
+  │                                                            │
+  ├── generated_articles                                       │
+  ├── generation_jobs                                          │
+  ├── pages                                                    │
+  ├── posts                                                    │
+  ├── leads                                                    │
+  ├── link_targets                                             │
+  ├── globals (1:1)                                            │
+  │                                                            │
+  ├── navigation (self-referential via parent)                 │
+  │                                                            │
+  ├── forms ─── form_submissions                               │
+  │                                                            │
+  ├── site_analytics                                           │
+  ├── events                                                   │
+  ├── pageviews                                                │
+  ├── conversions ─── leads                                    │
+  │                                                            │
+  └── work_log                                                 │
+                                                               │
+locations_states ─── locations_counties ─── locations_cities ──┘
+```
+
+---
+
+## 7. SQL Reference
+
+Full schema: [`complete_schema.sql`](file:///Users/christopheramaya/Downloads/spark/complete_schema.sql)
+
+Extensions required:
+```sql
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+```
+
+UUID generation:
+```sql
+DEFAULT gen_random_uuid()
+```

docs/DEVELOPER_GUIDE.md

@@ -0,0 +1,427 @@
+# DEVELOPER GUIDE: Spark Platform Setup & Workflow
+
+> **BLUF**: Clone, install, run `docker-compose up -d` then `npm run dev`. Access admin at localhost:4321/admin. Git push triggers auto-deploy.
+
+---
+
+## 1. Prerequisites
+
+| Requirement | Version | Check Command |
+|-------------|---------|---------------|
+| Node.js | 20+ | `node --version` |
+| npm | 10+ | `npm --version` |
+| Docker | 24+ | `docker --version` |
+| Docker Compose | 2.x | `docker compose version` |
+| Git | 2.x | `git --version` |
+
+---
+
+## 2. Clone & Install
+
+```bash
+# Clone repository
+git clone https://github.com/jumpstartscaling/net.git spark
+cd spark
+
+# Install frontend dependencies
+cd frontend
+npm install
+cd ..
+```
+
+---
+
+## 3. Environment Configuration
+
+```bash
+# Copy example environment file
+cp .env.example .env
+```
+
+### Required Variables
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `PUBLIC_DIRECTUS_URL` | API endpoint | `https://spark.jumpstartscaling.com` |
+| `DIRECTUS_ADMIN_TOKEN` | SSR authentication | (from Directus admin) |
+| `POSTGRES_PASSWORD` | Database auth | (secure password) |
+
+### Development Overrides
+
+For local development, create `frontend/.env.local`:
+```env
+PUBLIC_DIRECTUS_URL=http://localhost:8055
+DIRECTUS_ADMIN_TOKEN=your-local-token
+```
+
+---
+
+## 4. Start Services
+
+### Option A: Full Stack (Docker)
+
+```bash
+# Start all containers
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop all
+docker-compose down
+```
+
+Services available:
+- PostgreSQL: localhost:5432
+- Redis: localhost:6379
+- Directus: localhost:8055
+- Frontend (if containerized): localhost:4321
+
+### Option B: Frontend Development (Recommended)
+
+```bash
+# Connect to staging/production Directus
+cd frontend
+npm run dev
+```
+
+Access: http://localhost:4321
+
+---
+
+## 5. Local Development Workflow
+
+### 5.1 File Structure
+
+```
+frontend/src/
+├── pages/
+│   ├── admin/          # Admin pages (.astro)
+│   ├── api/            # API endpoints (.ts)
+│   └── [...slug].astro # Dynamic router
+├── components/
+│   ├── admin/          # Admin React components
+│   ├── blocks/         # Page builder blocks
+│   └── ui/             # Shadcn-style primitives
+├── lib/
+│   ├── directus/       # SDK client & fetchers
+│   └── schemas.ts      # TypeScript types
+└── hooks/              # React hooks
+```
+
+### 5.2 Creating New Admin Page
+
+1. Create page file:
+```bash
+touch frontend/src/pages/admin/my-feature/index.astro
+```
+
+2. Add content:
+```astro
+---
+import AdminLayout from '@/layouts/AdminLayout.astro';
+import MyComponent from '@/components/admin/MyComponent';
+---
+
+<AdminLayout title="My Feature">
+    <MyComponent client:load />
+</AdminLayout>
+```
+
+3. Create component:
+```bash
+touch frontend/src/components/admin/MyComponent.tsx
+```
+
+### 5.3 Creating New API Endpoint
+
+1. Create endpoint file:
+```bash
+touch frontend/src/pages/api/my-feature/action.ts
+```
+
+2. Add handler:
+```typescript
+import type { APIRoute } from 'astro';
+import { getDirectusClient } from '@/lib/directus/client';
+
+export const POST: APIRoute = async ({ request }) => {
+    const body = await request.json();
+    const client = getDirectusClient();
+    
+    // Your logic here
+    
+    return new Response(JSON.stringify({ success: true }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' }
+    });
+};
+```
+
+### 5.4 Creating New Block Type
+
+1. Create block component:
+```bash
+touch frontend/src/components/blocks/MyBlock.tsx
+```
+
+2. Add component:
+```tsx
+interface MyBlockProps {
+    content: string;
+    settings?: Record<string, any>;
+}
+
+export function MyBlock({ content, settings }: MyBlockProps) {
+    return (
+        <section className="py-12">
+            <div className="container mx-auto">
+                {content}
+            </div>
+        </section>
+    );
+}
+```
+
+3. Register in `BlockRenderer.tsx`:
+```tsx
+case 'my_block':
+    return <MyBlock key={block.id} {...block.settings} />;
+```
+
+---
+
+## 6. Testing
+
+### 6.1 Build Verification
+
+```bash
+cd frontend
+npm run build
+```
+
+Must complete without errors before push.
+
+### 6.2 Type Checking
+
+```bash
+npm run astro check
+```
+
+### 6.3 Manual Testing
+
+1. Start dev server: `npm run dev`
+2. Open http://localhost:4321/admin
+3. Test your changes
+4. Check browser console for errors
+5. Check network tab for API failures
+
+---
+
+## 7. Debugging
+
+### 7.1 React Query Devtools
+
+Enabled in development. Click floating panel (bottom-right) to inspect:
+- Active queries
+- Cache state
+- Refetch status
+
+### 7.2 Vite Inspector
+
+Access: http://localhost:4321/__inspect/
+
+Shows:
+- Module graph
+- Plugin timing
+- Bundle analysis
+
+### 7.3 Container Logs
+
+```bash
+# All services
+docker-compose logs -f
+
+# Specific service
+docker-compose logs -f directus
+docker-compose logs -f frontend
+```
+
+### 7.4 Database Access
+
+```bash
+docker exec -it spark-postgresql-1 psql -U postgres -d directus
+```
+
+Useful queries:
+```sql
+-- List tables
+\dt
+
+-- Check collection
+SELECT * FROM sites LIMIT 5;
+
+-- Recent work log
+SELECT * FROM work_log ORDER BY timestamp DESC LIMIT 10;
+```
+
+---
+
+## 8. Code Style
+
+### 8.1 TypeScript
+
+- Strict mode enabled
+- Explicit return types for functions
+- Use types from `schemas.ts`
+
+### 8.2 React Components
+
+- Functional components only
+- Props interface above component
+- Use React Query for data fetching
+
+### 8.3 File Naming
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Page | lowercase | `index.astro` |
+| Component | PascalCase | `SiteEditor.tsx` |
+| Hook | camelCase | `useSites.ts` |
+| API | kebab-case | `generate-article.ts` |
+
+### 8.4 Commit Messages
+
+```
+feat: Add new SEO analysis feature
+fix: Resolve pagination bug in article list
+docs: Update API reference
+refactor: Extract shared utility functions
+```
+
+---
+
+## 9. Git Workflow
+
+### 9.1 Branch Strategy
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Production (auto-deploys) |
+| `feat/*` | New features |
+| `fix/*` | Bug fixes |
+
+### 9.2 Typical Flow
+
+```bash
+# Create feature branch
+git checkout -b feat/my-feature
+
+# Make changes
+# ... edit files ...
+
+# Verify build
+cd frontend && npm run build
+
+# Commit
+git add .
+git commit -m "feat: Description"
+
+# Push (triggers Coolify on main)
+git push origin feat/my-feature
+
+# Create PR for review
+# Merge to main after approval
+```
+
+---
+
+## 10. Deployment
+
+### 10.1 Auto-Deploy (Standard)
+
+```bash
+git push origin main
+```
+
+Coolify detects push and deploys within ~2-3 minutes.
+
+### 10.2 Verify Deployment
+
+1. Check Coolify dashboard for build status
+2. Test production URL after successful build
+3. Check container logs if issues
+
+### 10.3 Environment Variables
+
+Set in Coolify Secrets:
+- `GOD_MODE_TOKEN`
+- `DIRECTUS_ADMIN_TOKEN`
+- `FORCE_FRESH_INSTALL` (only for schema reset)
+
+### 10.4 Rollback
+
+In Coolify:
+1. Go to service
+2. Click "Deployments"
+3. Select previous deployment
+4. Click "Redeploy"
+
+---
+
+## 11. Common Issues
+
+### Build Fails
+
+```bash
+# Check for TypeScript errors
+npm run astro check
+
+# Verify schemas.ts matches actual collections
+# Check for missing dependencies
+npm install
+```
+
+### API 403 Errors
+
+- Verify `DIRECTUS_ADMIN_TOKEN` is set
+- Check Directus permissions for token
+- Verify CORS includes your domain
+
+### SSR Errors
+
+- Check `client.ts` SSR URL detection
+- Verify Docker network connectivity
+- Check container names match expected
+
+### Database Connection
+
+```bash
+# Verify container is running
+docker-compose ps
+
+# Check PostgreSQL logs
+docker-compose logs postgresql
+```
+
+---
+
+## 12. Useful Commands
+
+```bash
+# Frontend
+npm run dev          # Start dev server
+npm run build        # Production build
+npm run preview      # Preview production build
+
+# Docker
+docker-compose up -d          # Start all
+docker-compose down           # Stop all
+docker-compose logs -f        # Stream logs
+docker-compose restart directus  # Restart service
+
+# Git
+git status           # Check changes
+git diff             # View changes
+git log -n 5         # Recent commits
+```

docs/GLOSSARY.md

@@ -0,0 +1,104 @@
+# GLOSSARY: Spark Platform Terminology
+
+> **BLUF**: This glossary defines all platform-specific terms. Reference before reading other documentation.
+
+---
+
+## Core Concepts
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Spintax** | Syntax for text variation using braces and pipes: `{word1\|word2\|word3}`. Processor randomly selects one option per instance. | Used in headline generation, content fragments |
+| **Cartesian Pattern** | Mathematical product of spintax elements. Given `{a\|b}` × `{1\|2}`, produces: `a1`, `a2`, `b1`, `b2`. | Campaign headline permutations |
+| **Avatar** | Buyer persona profile containing demographics, psychographics, pain points, and pronoun variations. | Content personalization layer |
+| **Fragment** | Modular content block (~200-300 words) for article assembly. One fragment per content pillar. | SEO article structure |
+| **Pillar** | One of 6 content sections in SEO articles: intro_hook, keyword, uniqueness, relevance, quality, authority. | Article assembly order |
+| **Hub Page** | Parent page linking to related child articles. Creates topical authority clusters. | Internal linking strategy |
+
+---
+
+## System Modules
+
+| Term | Definition | Location |
+|------|------------|----------|
+| **Intelligence Library** | Data asset storage: Avatars, Geo clusters, Spintax dictionaries, Cartesian patterns. | `/admin/intelligence/*` |
+| **Content Factory** | Article generation pipeline: Kanban workflow, queue processing, batch operations. | `/admin/factory/*` |
+| **Launchpad** | Site builder module: Sites, Pages, Navigation, Theme settings. | `/admin/sites/*` |
+| **SEO Engine** | Content optimization: Headlines, Fragments, Link insertion, Duplicate detection. | `/admin/seo/*` |
+| **Campaign Master** | SEO campaign configuration: target locations, avatars, spintax roots, word counts. | `campaign_masters` collection |
+
+---
+
+## Schema Terms
+
+| Term | Definition |
+|------|------------|
+| **Golden Schema** | Canonical database structure. 30+ collections in Harris Matrix order. |
+| **Harris Matrix** | Dependency ordering for schema creation. Foundation → Walls → Roof. Prevents FK constraint failures. |
+| **Batch 1** | Foundation tables: `sites`, `campaign_masters`, `avatar_intelligence`, `avatar_variants`, `cartesian_patterns`, `geo_intelligence`, `offer_blocks`. Zero dependencies. |
+| **Batch 2** | First-level children: `generated_articles`, `generation_jobs`, `pages`, `posts`, `leads`, `headline_inventory`, `content_fragments`. Depend only on Batch 1. |
+| **Batch 3** | Complex children: `link_targets`, `globals`, `navigation`. Multiple dependencies or self-referential. |
+
+---
+
+## Architecture Terms
+
+| Term | Definition |
+|------|------------|
+| **SSR** | Server-Side Rendering. HTML generated on server per request. Astro default mode. |
+| **Islands Architecture** | Astro's partial hydration model. Static HTML with isolated interactive React components. Reduces JS bundle. |
+| **Multi-Tenant** | Single codebase serves multiple isolated sites. `site_id` FK on all content tables. |
+| **SSR URL Detection** | Logic to select Directus URL: Docker internal (`http://directus:8055`) for server requests, public HTTPS for browser requests. |
+| **God-Mode API** | Admin-only endpoints at `/god/*` for schema operations. Protected by `X-God-Token` header. |
+
+---
+
+## Infrastructure Terms
+
+| Term | Definition |
+|------|------------|
+| **Coolify** | Self-hosted PaaS for Docker deployments. Manages containers, SSL, and domains. |
+| **Traefik** | Reverse proxy in Coolify stack. Routes requests to containers by domain/path. |
+| **BullMQ** | Redis-based job queue for Node.js. Handles async article generation, image processing. |
+| **PostGIS** | PostgreSQL extension for geographic data. Enables spatial queries on location data. |
+
+---
+
+## Content Terms
+
+| Term | Definition |
+|------|------------|
+| **Headline Inventory** | Database of generated headline variations from spintax permutations. |
+| **Velocity Mode** | Article scheduling strategy: `RAMP_UP` (increasing), `STEADY` (constant), `SPIKES` (burst patterns). |
+| **Sitemap Drip** | Gradual sitemap exposure strategy: `ghost` → `queued` → `indexed`. |
+| **Offer Block** | Promotional content template with token placeholders: `{{CITY}}`, `{{NICHE}}`, `{{AVATAR}}`. |
+| **Geo Intelligence** | Location targeting data: states, counties, cities with population data. |
+| **Wealth Cluster** | Geographic grouping by economic profile: Tech-Native, Financial Power, etc. |
+
+---
+
+## UI/UX Terms
+
+| Term | Definition |
+|------|------------|
+| **Titanium Pro Design** | Design system: Zinc-950 background, Yellow-500/Green-500/Purple-500 accents. |
+| **Shadcn/UI** | Component library pattern. Unstyled primitives with Tailwind classes. |
+| **Kanban Board** | Workflow visualization: Queued → Processing → QC → Approved → Published. |
+| **Block Renderer** | Component that converts JSON block definitions to HTML. Core of page builder. |
+
+---
+
+## Acronyms
+
+| Acronym | Expansion |
+|---------|-----------|
+| **BLUF** | Bottom Line Up Front |
+| **CMS** | Content Management System |
+| **CORS** | Cross-Origin Resource Sharing |
+| **CRUD** | Create, Read, Update, Delete |
+| **FK** | Foreign Key |
+| **M2O** | Many-to-One (relation type) |
+| **M2M** | Many-to-Many (relation type) |
+| **PK** | Primary Key |
+| **SDK** | Software Development Kit |
+| **UUID** | Universally Unique Identifier |

docs/INVESTOR_BRIEF.md

@@ -0,0 +1,207 @@
+# INVESTOR BRIEF: Spark Platform
+
+> **BLUF**: Spark is a multi-tenant content scaling platform that generates location-targeted SEO articles using spintax permutation and Cartesian pattern matching. Current capacity: 50,000+ unique articles per campaign configuration.
+
+---
+
+## 1. Platform Function
+
+Spark automates SEO content production at scale. The system:
+1. Ingests buyer personas (Avatars), location data, and content templates
+2. Computes Cartesian products of location × persona × offer variations
+3. Generates unique articles with geo-specific and persona-specific content
+4. Manages multi-site content distribution with scheduling controls
+
+**Core Problem Solved**: Manual SEO content creation produces ~2-5 articles/day. Spark produces 100-500 articles/hour with equivalent uniqueness and targeting precision.
+
+---
+
+## 2. Technical Stack
+
+| Layer | Technology | Version | Purpose |
+|-------|------------|---------|---------|
+| Frontend | Astro | 4.7 | SSR + Islands Architecture |
+| UI | React | 18.3 | Interactive components |
+| Backend | Directus | 11 | Headless CMS + REST/GraphQL |
+| Database | PostgreSQL | 16 | Primary data store |
+| Extensions | PostGIS | 3.4 | Geographic queries |
+| Cache | Redis | 7 | Session + job queue backing |
+| Queue | BullMQ | - | Async job processing |
+| Deployment | Coolify | - | Docker orchestration |
+
+**Infrastructure**: Self-hostable via Docker Compose. No external SaaS dependencies.
+
+---
+
+## 3. Data Assets
+
+### 3.1 Location Database
+| Dataset | Count | Source |
+|---------|-------|--------|
+| US States | 51 | Census data |
+| US Counties | 3,143 | Census data |
+| US Cities | ~50 per county | Population-ranked |
+
+### 3.2 Intelligence Assets
+| Asset Type | Description | IP Value |
+|------------|-------------|----------|
+| Avatar Intelligence | 10+ buyer personas with psychographics | Proprietary |
+| Wealth Clusters | 5+ economic profile groupings | Proprietary |
+| Spintax Dictionaries | Word/phrase variation libraries | Proprietary |
+| Cartesian Patterns | Title/hook formula combinations | Proprietary |
+| Offer Blocks | 10+ promotional templates | Proprietary |
+
+---
+
+## 4. Capacity Metrics
+
+### 4.1 Theoretical Maximum
+```
+10 Avatars × 10 Niches × 50 Cities × 10 Offers = 50,000 unique articles
+```
+
+### 4.2 Practical Campaign
+```
+2 Avatars × 3 Niches × 10 Cities × 2 Offers = 120 articles
+```
+
+### 4.3 Generation Speed
+| Operation | Throughput |
+|-----------|------------|
+| Headline permutation | 1,000/second |
+| Article assembly | 100-500/hour |
+| Queue processing | Configurable batch size |
+
+---
+
+## 5. Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        USER REQUEST                              │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  TRAEFIK (Reverse Proxy)                                        │
+│  Routes by domain/path to containers                            │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+        ┌──────────────────┴──────────────────┐
+        ▼                                     ▼
+┌───────────────┐                    ┌───────────────┐
+│  FRONTEND     │                    │  DIRECTUS     │
+│  Astro SSR    │◄──── REST API ────►│  Port 8055    │
+│  Port 4321    │                    │  Headless CMS │
+└───────────────┘                    └───────┬───────┘
+                                             │
+                                             ▼
+                         ┌───────────────────────────────────┐
+                         │  POSTGRESQL 16 + POSTGIS          │
+                         │  30+ Collections                  │
+                         │  Harris Matrix Schema Order       │
+                         └───────────────────┬───────────────┘
+                                             │
+                                             ▼
+                         ┌───────────────────────────────────┐
+                         │  REDIS 7                          │
+                         │  Session Cache + BullMQ Jobs      │
+                         └───────────────────────────────────┘
+```
+
+---
+
+## 6. Multi-Tenancy Model
+
+| Isolation Level | Implementation |
+|-----------------|----------------|
+| Data | `site_id` FK on all content tables |
+| Routes | Domain-based routing via Traefik |
+| Authentication | Directus role-based access control |
+| Permissions | Site-scoped API tokens |
+
+**Tenant capacity**: Unlimited sites. Horizontal scaling via Docker replicas.
+
+---
+
+## 7. Feature Inventory
+
+### 7.1 Intelligence Library (Data Management)
+- Avatar Intelligence Manager
+- Geo Intelligence Map (Leaflet integration)
+- Spintax Dictionary Manager
+- Cartesian Pattern Builder
+
+### 7.2 Content Factory (Production)
+- Kanban workflow board
+- Campaign wizard (geo + spintax modes)
+- Jobs queue with progress monitoring
+- Scheduler with Gaussian distribution
+
+### 7.3 Launchpad (Site Builder)
+- Multi-site management
+- Block-based page builder
+- Navigation editor
+- Theme customization
+
+### 7.4 SEO Engine (Optimization)
+- Headline generation (spintax permutation)
+- Fragment assembly (6-pillar structure)
+- Internal link insertion
+- Duplicate content detection
+- Sitemap drip scheduling
+
+### 7.5 Analytics (Tracking)
+- Pageview tracking
+- Event tracking
+- Conversion tracking
+- Dashboard with aggregations
+
+---
+
+## 8. Competitive Position
+
+| Capability | Spark | Generic CMS | AI Writers |
+|------------|-------|-------------|------------|
+| Multi-tenant | ✓ | Partial | ✗ |
+| Geo-targeting | ✓ (3,143 counties) | ✗ | ✗ |
+| Persona-targeting | ✓ (10+ avatars) | ✗ | Limited |
+| Spintax processing | ✓ | ✗ | ✗ |
+| Cartesian patterns | ✓ | ✗ | ✗ |
+| Self-hostable | ✓ | Varies | ✗ |
+| Queue-based scaling | ✓ | ✗ | ✗ |
+
+---
+
+## 9. Revenue Model Indicators
+
+| Model | Mechanism |
+|-------|-----------|
+| SaaS per site | Monthly fee per managed site |
+| Volume pricing | Tiered by articles generated |
+| Enterprise | Self-hosted license + support |
+| White-label | Reseller partnerships |
+
+---
+
+## 10. Development Status
+
+| Milestone | Status | Description |
+|-----------|--------|-------------|
+| M1: Intelligence Library | ✓ Complete | Full CRUD + stats |
+| M2: Content Factory | ✓ Complete | Kanban + queue |
+| M3: All Collections | ✓ Complete | 30+ schemas |
+| M4: Launchpad | ✓ Complete | Site builder |
+| M5: Production | ✓ Deployed | Live on Coolify |
+
+**Current Status**: Operational. Active development on feature enhancements.
+
+---
+
+## 11. Key Files
+
+| File | Purpose |
+|------|---------|
+| `complete_schema.sql` | Golden Schema (Harris Matrix ordered) |
+| `docker-compose.yaml` | Infrastructure definition |
+| `frontend/src/lib/schemas.ts` | TypeScript type definitions |
+| `frontend/src/pages/api/*` | 30+ API endpoints |

docs/PLATFORM_CAPABILITIES.md

@@ -0,0 +1,403 @@
+# PLATFORM CAPABILITIES: Spark Feature Catalog
+
+> **BLUF**: Spark contains 5 major modules with 27+ subcomponents. This document catalogs all functional capabilities.
+
+---
+
+## 1. Intelligence Library
+
+**Purpose**: Centralized storage and management of content generation data assets.
+
+**Location**: `/admin/intelligence/*`
+
+### 1.1 Avatar Intelligence
+| Feature | Function |
+|---------|----------|
+| Avatar Manager | CRUD operations for buyer personas |
+| Stats Dashboard | 4 metric cards: total, by cluster, by gender, variants |
+| Variant Generator | Creates male/female/neutral variations |
+| Persona Editor | Psychographics, pain points, tech stack |
+
+**Data Model**: `avatar_intelligence` → `avatar_variants`
+
+### 1.2 Geo Intelligence
+| Feature | Function |
+|---------|----------|
+| Interactive Map | Leaflet-based US map with markers |
+| Cluster Manager | Group cities by wealth profile |
+| City Stats | Population, landmarks, targeting data |
+| Hybrid View | Map + List with synchronized filtering |
+
+**Data Model**: `locations_states` → `locations_counties` → `locations_cities`
+
+### 1.3 Spintax Dictionaries
+| Feature | Function |
+|---------|----------|
+| Dictionary Manager | Category-organized word variations |
+| Live Preview | Real-time spintax resolution testing |
+| Import/Export | JSON batch operations |
+| Test Spinner | Verify output distribution |
+
+**Data Model**: `spintax_dictionaries` (legacy) mapped to new schema
+
+### 1.4 Cartesian Patterns
+| Feature | Function |
+|---------|----------|
+| Pattern Builder | Formula editor for title combinations |
+| Dynamic Preview | Uses live Geo + Spintax data |
+| Permutation Calculator | Shows total combination count |
+| Pattern Library | Saved reusable formulas |
+
+**Data Model**: `cartesian_patterns`
+
+### 1.5 Offer Blocks
+| Feature | Function |
+|---------|----------|
+| Block Editor | Rich text with token placeholders |
+| Avatar Mapping | Match blocks to persona pain points |
+| Token Preview | See rendered output |
+| Template Library | Promotional content templates |
+
+**Data Model**: `offer_blocks`
+
+---
+
+## 2. Content Factory
+
+**Purpose**: Article production pipeline from queue to publication.
+
+**Location**: `/admin/factory/*`
+
+### 2.1 Kanban Board
+| Column | Status | Actions |
+|--------|--------|---------|
+| Queued | `status: queued` | Prioritize, schedule |
+| Processing | `status: processing` | Monitor, cancel |
+| QC | `status: qc` | Review, approve |
+| Approved | `status: approved` | Publish, hold |
+| Published | `status: published` | Archive, analytics |
+
+**Implementation**: @dnd-kit drag-and-drop library
+
+### 2.2 Jobs Queue
+| Feature | Function |
+|---------|----------|
+| Job Monitor | Real-time progress bars |
+| Batch Status | Completion percentage |
+| Retry Failed | Re-queue failed items |
+| Job Details | Config, errors, timing |
+
+**Data Model**: `generation_jobs`
+
+### 2.3 Scheduler
+| Feature | Function |
+|---------|----------|
+| Calendar View | Scheduled posts by date |
+| Gaussian Distribution | Natural spacing algorithm |
+| Bulk Schedule | Date range assignment |
+| Velocity Modes | RAMP_UP, STEADY, SPIKES |
+
+### 2.4 Campaign Wizard
+| Mode | Description |
+|------|-------------|
+| Geo Mode | State → County → City selection |
+| Spintax Mode | Variable template expansion |
+| Hybrid Mode | Geographic + linguistic targeting |
+
+**Data Model**: `campaign_masters`
+
+### 2.5 Article Assembly
+| Feature | Function |
+|---------|----------|
+| Fragment Composition | 6-pillar structure assembly |
+| Token Replacement | `{{CITY}}`, `{{NICHE}}`, `{{AVATAR}}` |
+| SEO Meta Generation | Title (60 char), Description (160 char) |
+| Schema.org JSON-LD | Structured data insertion |
+
+### 2.6 Bulk Operations
+| Feature | Function |
+|---------|----------|
+| Bulk Grid | Multi-select with actions |
+| Approve Batch | Mass status change |
+| Publish Batch | Multi-article publication |
+| Export | CSV/JSON data export |
+
+**Data Model**: `generated_articles`
+
+---
+
+## 3. Launchpad (Site Builder)
+
+**Purpose**: Multi-site management and page construction.
+
+**Location**: `/admin/sites/*`
+
+### 3.1 Site Manager
+| Feature | Function |
+|---------|----------|
+| Site List | All tenant sites with stats |
+| Site Creation | Domain, settings, defaults |
+| Site Dashboard | Tabs: Pages, Nav, Theme |
+| Site Analytics | Per-site metrics |
+
+**Data Model**: `sites`
+
+### 3.2 Page Builder
+| Feature | Function |
+|---------|----------|
+| Block Editor | Visual block placement |
+| Block Types | Hero, Content, Features, Gallery, FAQ, Form |
+| Preview | Real-time rendering |
+| JSON State | Block configuration storage |
+
+**Block Types**:
+| Block | Purpose |
+|-------|---------|
+| HeroBlock | Full-width header with CTA |
+| RichTextBlock | SEO-optimized prose |
+| ColumnsBlock | Multi-column layouts |
+| MediaBlock | Images/videos with captions |
+| StepsBlock | Numbered process visualization |
+| QuoteBlock | Testimonials, blockquotes |
+| GalleryBlock | Image grids |
+| FAQBlock | Accordions with schema.org |
+| PostsBlock | Blog listing layouts |
+| FormBlock | Lead capture forms |
+
+**Data Model**: `pages` (blocks stored as JSON in `blocks` field)
+
+### 3.3 Navigation Editor
+| Feature | Function |
+|---------|----------|
+| Menu Builder | Add/remove/sort links |
+| Parent/Child | Hierarchical structure |
+| Target Control | `_self`, `_blank` |
+| Sort Order | Drag-drop reordering |
+
+**Data Model**: `navigation`
+
+### 3.4 Theme Settings
+| Feature | Function |
+|---------|----------|
+| Color Palette | Primary, accent, background |
+| Logo Upload | Site branding |
+| Footer Config | Links, copyright |
+| Font Selection | Typography settings |
+
+**Data Model**: `globals` (site singleton)
+
+---
+
+## 4. SEO Engine
+
+**Purpose**: Content optimization and search visibility tools.
+
+**Location**: `/admin/seo/*`
+
+### 4.1 Headline Generation
+| Feature | Function |
+|---------|----------|
+| Spintax Input | Root template entry |
+| Permutation Engine | Cartesian product calculation |
+| Inventory Storage | Generated variations database |
+| Deduplication | Unique output enforcement |
+
+**Endpoint**: `POST /api/seo/generate-headlines`
+
+### 4.2 Fragment Manager
+| Feature | Function |
+|---------|----------|
+| 6-Pillar Structure | Intro, Keyword, Uniqueness, Relevance, Quality, Authority |
+| Campaign Linking | Fragments per campaign |
+| Variable Support | Token placeholders |
+| Word Count Tracking | Target enforcement |
+
+**Data Model**: `content_fragments`
+
+### 4.3 Article Generator
+| Feature | Function |
+|---------|----------|
+| Batch Generation | Configurable batch size |
+| Progress Monitoring | Real-time job updates |
+| Queue Integration | BullMQ backend |
+| Error Handling | Retry logic, logging |
+
+**Endpoint**: `POST /api/seo/generate-article`
+
+### 4.4 Link Insertion
+| Feature | Function |
+|---------|----------|
+| Anchor Text Mapping | Keyword → URL pairs |
+| Proximity Rules | Min distance between links |
+| Density Control | Max links per article |
+| Internal Link Graph | Hub → child relationships |
+
+**Endpoint**: `POST /api/seo/insert-links`
+
+**Data Model**: `link_targets`
+
+### 4.5 Duplicate Detection
+| Feature | Function |
+|---------|----------|
+| Content Hashing | Similarity scoring |
+| Threshold Config | Match percentage |
+| Conflict Resolution | Merge, delete, ignore |
+| Scan Reports | Duplicate groups |
+
+**Endpoint**: `POST /api/seo/scan-duplicates`
+
+### 4.6 Sitemap Drip
+| Feature | Function |
+|---------|----------|
+| Status Stages | ghost → queued → indexed |
+| Exposure Schedule | Configurable timing |
+| Batch Control | URLs per update |
+| XML Generation | sitemap.xml output |
+
+**Endpoint**: `POST /api/seo/sitemap-drip`
+
+### 4.7 Queue Processor
+| Feature | Function |
+|---------|----------|
+| FIFO Processing | First-in first-out |
+| Priority Override | Urgent item boost |
+| Parallel Workers | Configurable concurrency |
+| Dead Letter Queue | Failed item handling |
+
+**Endpoint**: `POST /api/seo/process-queue`
+
+### 4.8 Statistics
+| Feature | Function |
+|---------|----------|
+| Article Counts | By status, site, campaign |
+| Generation Velocity | Articles per time period |
+| Queue Depth | Pending item count |
+| Error Rate | Failure percentage |
+
+**Endpoint**: `GET /api/seo/stats`
+
+---
+
+## 5. Analytics
+
+**Purpose**: User behavior tracking and metrics aggregation.
+
+**Location**: `/admin/analytics/*`
+
+### 5.1 Dashboard
+| Feature | Function |
+|---------|----------|
+| Metrics Cards | Pageviews, events, conversions |
+| Time Range | Day, week, month, custom |
+| Site Filter | Per-tenant isolation |
+| Trend Charts | Historical comparison |
+
+**Endpoint**: `GET /api/analytics/dashboard`
+
+### 5.2 Event Tracking
+| Feature | Function |
+|---------|----------|
+| Custom Events | Named action logging |
+| Page Path | URL association |
+| Session Linking | User journey |
+| Timestamp | UTC standardized |
+
+**Endpoint**: `POST /api/track/event`
+
+**Data Model**: `events`
+
+### 5.3 Pageview Tracking
+| Feature | Function |
+|---------|----------|
+| Path Logging | URL capture |
+| Session ID | Anonymous user grouping |
+| Referrer | Traffic source |
+| Device Info | User agent parsing |
+
+**Endpoint**: `POST /api/track/pageview`
+
+**Data Model**: `pageviews`
+
+### 5.4 Conversion Tracking
+| Feature | Function |
+|---------|----------|
+| Lead Linking | Form → conversion |
+| Conversion Type | Category classification |
+| Value Assignment | Monetary attribution |
+| Source Tracking | Campaign attribution |
+
+**Endpoint**: `POST /api/track/conversion`
+
+**Data Model**: `conversions`
+
+---
+
+## 6. Lead Capture
+
+**Purpose**: Form submission handling and lead management.
+
+### 6.1 Form Builder
+| Feature | Function |
+|---------|----------|
+| Field Types | Text, email, select, textarea |
+| Validation Rules | Required, pattern, min/max |
+| Submit Actions | Webhook, email, store |
+| Success Config | Message, redirect |
+
+**Data Model**: `forms`
+
+### 6.2 Submission Handler
+| Feature | Function |
+|---------|----------|
+| Data Storage | JSON field storage |
+| Spam Filtering | Honeypot, rate limiting |
+| Notification | Email alerts |
+| Integration | Webhook dispatch |
+
+**Endpoint**: `POST /api/forms/submit`
+
+**Data Model**: `form_submissions`
+
+### 6.3 Lead Management
+| Feature | Function |
+|---------|----------|
+| Lead List | Filterable table |
+| Status Workflow | New → Contacted → Qualified → Converted |
+| Export | CSV download |
+| Source Tracking | Origin capture |
+
+**Data Model**: `leads`
+
+---
+
+## 7. System Administration
+
+### 7.1 Work Log
+| Feature | Function |
+|---------|----------|
+| Activity Stream | All system actions |
+| Entity Linking | What was affected |
+| User Attribution | Who performed action |
+| Level Filtering | Debug, info, warning, error |
+
+**Data Model**: `work_log`
+
+### 7.2 Test Suite
+| Feature | Function |
+|---------|----------|
+| Connection Tests | Directus API health |
+| Schema Validation | Collection verification |
+| Permission Check | Role access testing |
+| Performance Metrics | Response timing |
+
+**Location**: `/admin/testing/*`
+
+### 7.3 Settings Manager
+| Feature | Function |
+|---------|----------|
+| API Configuration | URLs, tokens |
+| Queue Settings | Concurrency, retry |
+| Cache Control | TTL, invalidation |
+| Feature Flags | Enable/disable modules |
+
+**Location**: `/admin/settings`

docs/TECHNICAL_ARCHITECTURE.md

@@ -0,0 +1,392 @@
+# TECHNICAL ARCHITECTURE: Spark Platform
+
+> **BLUF**: Spark uses Astro SSR + React Islands frontend, Directus headless CMS backend, PostgreSQL with PostGIS for data, and Redis-backed BullMQ for async processing. Multi-tenant via site_id foreign keys.
+
+---
+
+## 1. System Diagram
+
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        Browser[Browser]
+        PWA[PWA Service Worker]
+    end
+
+    subgraph "Edge Layer"
+        Traefik[Traefik Reverse Proxy]
+    end
+
+    subgraph "Application Layer"
+        Frontend["Astro SSR<br/>Port 4321"]
+        Directus["Directus CMS<br/>Port 8055"]
+    end
+
+    subgraph "Data Layer"
+        PostgreSQL["PostgreSQL 16<br/>+ PostGIS 3.4"]
+        Redis["Redis 7<br/>Sessions + Queue"]
+    end
+
+    subgraph "Extension Layer"
+        Endpoints["Custom Endpoints<br/>/god/*"]
+        Hooks["Event Hooks<br/>on:create, on:update"]
+    end
+
+    Browser --> Traefik
+    PWA --> Traefik
+    Traefik -->|"/*.admin, /api/*"| Frontend
+    Traefik -->|"/items/*, /collections/*"| Directus
+    Frontend -->|"REST API"| Directus
+    Directus --> PostgreSQL
+    Directus --> Redis
+    Directus --> Endpoints
+    Directus --> Hooks
+```
+
+---
+
+## 2. Component Specifications
+
+### 2.1 Frontend (Astro)
+
+| Property | Value |
+|----------|-------|
+| Framework | Astro 4.7 |
+| Rendering | SSR (Server-Side Rendering) |
+| Hydration | Islands Architecture (partial) |
+| UI Library | React 18.3 |
+| Styling | Tailwind CSS 3.4 |
+| State | React Query + Zustand |
+| Build | Vite |
+
+**SSR URL Detection Logic**:
+```typescript
+const isServer = import.meta.env.SSR || typeof window === 'undefined';
+const DIRECTUS_URL = isServer 
+    ? 'http://directus:8055'      // Docker internal
+    : import.meta.env.PUBLIC_DIRECTUS_URL;  // Public HTTPS
+```
+
+**Rationale**: Server-side requests use Docker network DNS. Browser requests use public URL.
+
+### 2.2 Backend (Directus)
+
+| Property | Value |
+|----------|-------|
+| Version | Directus 11 |
+| API | REST + GraphQL |
+| Auth | JWT + Static Tokens |
+| Storage | Local filesystem (uploads volume) |
+| Extensions | Endpoints + Hooks |
+
+**Extension Structure**:
+```
+directus-extensions/
+├── endpoints/
+│   ├── god-schema/     # Schema operations
+│   ├── god-data/       # Bulk data ops
+│   └── god-utils/      # Utility endpoints
+└── hooks/
+    ├── work-log/       # Activity logging
+    └── cache-bust/     # Invalidation
+```
+
+### 2.3 Database (PostgreSQL)
+
+| Property | Value |
+|----------|-------|
+| Version | PostgreSQL 16 |
+| Extensions | uuid-ossp, pgcrypto, PostGIS 3.4 |
+| Collections | 30+ tables |
+| Schema Order | Harris Matrix (Foundation → Walls → Roof) |
+
+**Schema Dependency Order**:
+
+| Batch | Tables | Dependencies |
+|-------|--------|--------------|
+| 1: Foundation | sites, campaign_masters, avatar_*, geo_*, offer_blocks | None |
+| 2: Walls | generated_articles, generation_jobs, pages, posts, leads, headline_*, content_* | Batch 1 only |
+| 3: Roof | link_targets, globals, navigation | Batch 1-2 |
+
+### 2.4 Cache/Queue (Redis)
+
+| Property | Value |
+|----------|-------|
+| Version | Redis 7 |
+| Mode | Append-only (persistent) |
+| Uses | Session cache, BullMQ backing |
+
+**Queue Configuration**:
+```typescript
+// BullMQ job options
+{
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 1000 },
+    removeOnComplete: 100,
+    removeOnFail: 1000
+}
+```
+
+---
+
+## 3. Data Flow
+
+### 3.1 Page Request Flow
+
+```
+1. Browser → GET /blog/article-slug
+2. Traefik → Route to Frontend (port 4321)
+3. Astro SSR → Determine site from domain
+4. Astro → GET http://directus:8055/items/posts?filter[slug]=...
+5. Directus → PostgreSQL query
+6. Directus → Return JSON
+7. Astro → Render HTML with React components
+8. Astro → Return HTML to browser
+9. Browser → Hydrate interactive islands
+```
+
+### 3.2 Article Generation Flow
+
+```
+1. Admin → POST /api/seo/generate-article
+2. Astro API → Create generation_job record
+3. Astro API → Queue job in BullMQ
+4. BullMQ Worker → Dequeue job
+5. Worker → Fetch campaign config from Directus
+6. Worker → Compute Cartesian products
+7. Worker → For each permutation:
+    a. Replace tokens
+    b. Process spintax
+    c. Generate SEO meta
+    d. Create generated_articles record
+8. Worker → Update job status: completed
+9. Admin → Kanban reflects new articles
+```
+
+### 3.3 Multi-Tenant Request Isolation
+
+```
+1. Request → https://client-a.example.com/page
+2. Middleware → Extract hostname
+3. Middleware → Query sites WHERE url LIKE %hostname%
+4. Middleware → Set site_id in context
+5. All queries → Filter by site_id
+6. Response → Only tenant data returned
+```
+
+---
+
+## 4. API Surface
+
+### 4.1 Public Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/lead` | POST | Form submission |
+| `/api/forms/submit` | POST | Generic form handler |
+| `/api/track/pageview` | POST | Analytics |
+| `/api/track/event` | POST | Custom events |
+| `/api/track/conversion` | POST | Conversion recording |
+
+### 4.2 Admin Endpoints
+
+| Endpoint | Method | Auth | Purpose |
+|----------|--------|------|---------|
+| `/api/seo/generate-headlines` | POST | Token | Spintax permutation |
+| `/api/seo/generate-article` | POST | Token | Article creation |
+| `/api/seo/approve-batch` | POST | Token | Bulk approval |
+| `/api/seo/publish-article` | POST | Token | Single publish |
+| `/api/seo/scan-duplicates` | POST | Token | Duplicate detection |
+| `/api/seo/insert-links` | POST | Token | Internal linking |
+| `/api/seo/process-queue` | POST | Token | Queue advancement |
+| `/api/campaigns` | GET/POST | Token | Campaign CRUD |
+| `/api/admin/import-blueprint` | POST | Token | Site import |
+| `/api/admin/worklog` | GET | Token | Activity log |
+
+### 4.3 God-Mode Endpoints
+
+| Endpoint | Method | Header | Purpose |
+|----------|--------|--------|---------|
+| `/god/schema/collections/create` | POST | X-God-Token | Create collection |
+| `/god/schema/relations/create` | POST | X-God-Token | Create relation |
+| `/god/schema/snapshot` | GET | X-God-Token | Export schema YAML |
+| `/god/data/bulk-insert` | POST | X-God-Token | Mass data insert |
+
+---
+
+## 5. Authentication Model
+
+### 5.1 Directus Auth
+
+| Method | Use Case |
+|--------|----------|
+| JWT | User login sessions |
+| Static Token | API integrations |
+| God-Mode Token | Administrative operations |
+
+### 5.2 Token Hierarchy
+
+```
+┌─────────────────────────────────────┐
+│  GOD_MODE_TOKEN                     │  ← Full schema access
+│  X-God-Token header                 │
+└─────────────────────────────────────┘
+                ▼
+┌─────────────────────────────────────┐
+│  DIRECTUS_ADMIN_TOKEN              │  ← All collections CRUD
+│  Authorization: Bearer              │
+└─────────────────────────────────────┘
+                ▼
+┌─────────────────────────────────────┐
+│  Site-Scoped Token                 │  ← Single site access
+│  Generated per tenant              │
+└─────────────────────────────────────┘
+                ▼
+┌─────────────────────────────────────┐
+│  Public Access                     │  ← Read-only published
+│  No token required                 │
+└─────────────────────────────────────┘
+```
+
+---
+
+## 6. Security Configuration
+
+### 6.1 CORS Policy
+
+```yaml
+CORS_ORIGIN: 'https://spark.jumpstartscaling.com,https://launch.jumpstartscaling.com,http://localhost:4321'
+CORS_ENABLED: 'true'
+```
+
+### 6.2 Rate Limiting
+
+```yaml
+RATE_LIMITER_ENABLED: 'false'  # Disabled for internal use
+```
+
+### 6.3 Payload Limits
+
+```yaml
+MAX_PAYLOAD_SIZE: '500mb'  # Large batch operations
+```
+
+---
+
+## 7. Deployment Configuration
+
+### 7.1 Docker Compose Services
+
+| Service | Image | Port | Volume |
+|---------|-------|------|--------|
+| postgresql | postgis/postgis:16-3.4-alpine | 5432 | postgres-data-fresh |
+| redis | redis:7-alpine | 6379 | redis-data |
+| directus | directus/directus:11 | 8055 | directus-uploads |
+| frontend | Built from Dockerfile | 4321 | None |
+
+### 7.2 Environment Variables
+
+| Variable | Purpose | Where Set |
+|----------|---------|-----------|
+| PUBLIC_DIRECTUS_URL | Client-side API URL | docker-compose.yaml |
+| DIRECTUS_ADMIN_TOKEN | SSR API auth | Coolify secrets |
+| GOD_MODE_TOKEN | Schema operations | Coolify secrets |
+| FORCE_FRESH_INSTALL | Wipe + rebuild schema | Coolify secrets |
+| CORS_ORIGIN | Allowed origins | docker-compose.yaml |
+
+### 7.3 Coolify Labels
+
+```yaml
+labels:
+    coolify.managed: 'true'
+    coolify.name: 'directus'
+    coolify.fqdn: 'spark.jumpstartscaling.com'
+    coolify.port: '8055'
+```
+
+---
+
+## 8. Extension Points
+
+### 8.1 Adding New Collections
+
+1. Define in `complete_schema.sql` (Harris Matrix order)
+2. Add TypeScript interface to `schemas.ts`
+3. Create API endpoint if needed
+4. Add admin page component
+
+### 8.2 Adding New Blocks
+
+1. Create component in `frontend/src/components/blocks/`
+2. Register in `BlockRenderer.tsx` switch statement
+3. Add schema to Page Builder config
+
+### 8.3 Adding New Endpoints
+
+1. Create file in `frontend/src/pages/api/`
+2. Export async handler function
+3. Add to API_REFERENCE.md
+
+### 8.4 Adding Custom Directus Extensions
+
+1. Create in `directus-extensions/endpoints/` or `hooks/`
+2. Restart Directus container
+3. Extensions auto-load from mounted volume
+
+---
+
+## 9. Performance Considerations
+
+### 9.1 SSR Caching
+
+| Strategy | Implementation |
+|----------|----------------|
+| ISR | Not used (dynamic content) |
+| Edge Cache | Traefik level (CDN potential) |
+| API Cache | Redis TTL on queries |
+
+### 9.2 Database Optimization
+
+| Technique | Application |
+|------------|-------------|
+| Indexes | FK columns, status, slug |
+| Pagination | Offset-based with limits |
+| Field Selection | Only request needed fields |
+
+### 9.3 Bundle Optimization
+
+| Technique | Implementation |
+|-----------|----------------|
+| Islands | Only hydrate interactive components |
+| Code Splitting | Vite automatic chunks |
+| Compression | Brotli via Astro adapter |
+
+---
+
+## 10. Monitoring & Logging
+
+### 10.1 Log Locations
+
+| Service | Location |
+|---------|----------|
+| Directus | Container stdout (Coolify UI) |
+| Frontend | Container stdout (Coolify UI) |
+| PostgreSQL | Container stdout |
+
+### 10.2 Health Checks
+
+| Service | Endpoint | Interval |
+|---------|----------|----------|
+| PostgreSQL | pg_isready | 5s |
+| Redis | redis-cli ping | 5s |
+| Directus | /server/health | 10s |
+
+### 10.3 Work Log Table
+
+```sql
+SELECT * FROM work_log 
+ORDER BY timestamp DESC 
+LIMIT 100;
+```
+
+Fields: action, entity_type, entity_id, details, level, user, timestamp