feat: Added the ComfyUI engine (#12)

#11 Added the complete ComfyUI engine.

Co-authored-by: Sayan Datta <sayan@Sayans-MacBook-Air.local>
Reviewed-on: sagnik/Project_Velocity#12

.Agent Context/Bibels/The Catalyst_ Brief.md

@@ -0,0 +1,91 @@
+### **Part 1: First Principles Page Structure Analysis**
+
+*If "The Catalyst" is an autonomous digital marketing agency, it cannot look like a standard Facebook Ads Manager spreadsheet. It must feel like an executive command center.*
+
+Here is the optimized page architecture for the WebOS:
+
+**1\. The Studio (Visual AI Engine)**
+
+* **Purpose:** Where your ComfyUI workflows (Wan 2.2 and Qwen-Image 2512\) live on the frontend.  
+* **Function:** Users input raw property data/images, and the system generates variations of cinematic videos and multi-lingual posters.  
+* **Meta Link:** Automatically pushes these assets to the Meta Asset Library via API.
+
+**2\. Campaign Command (Control Surface)**
+
+* **Purpose:** The strategic deployment center.  
+* **Function:** Instead of manually setting up ads, the user defines the "Objective" (e.g., "Sell 3BHKs fast") and "Budget". The Claw Agent uses the **Meta Marketing API** to execute Ad Campaign Management & Automation, handling ad sets, bulk creation, and dynamic creative rotation using the assets generated in The Studio.
+
+**3\. Intelligence & ROI (Analytics Dashboard)**
+
+* **Purpose:** Real-time visual justification of marketing spend.  
+* **Function:** Uses the **Ads Insights API** to visualize CPA (Cost Per Acquisition) and ROI. Features a "Live Optimization" log showing what the Claw Agent is doing in real-time (e.g., *"Agent paused Ad Set B due to high CPA. Shifted budget to Ad Set A."*).
+
+**4\. The War Room (Market Research & Audiences)**
+
+* **Purpose:** AI-driven competitor and audience strategy.  
+* **Function:** Integrates the **Ad Library API** to spy on competitor ads (e.g., Emaar/Damac) and uses the completed Brave Search integration to track real estate trends. Connects directly to the **Audience Management API** to build Custom/Lookalike audiences dynamically from the Supabase CRM leads.
+
+**5\. System & Meta Graph (Settings)**
+
+* **Purpose:** The plumbing.  
+* **Function:** Uses the **Meta Business API** for Client Onboarding, Business Asset Management (linking WhatsApp, Instagram, FB Pages), and Permissions Management.
+
+---
+
+### **Part 2: Software Requirements Specification (SRS)**
+
+#### **A. Tech Stack & State Management**
+
+* **Frontend (Sayan):** Next JS (Latest Version), Tailwind CSS, Framer Motion, Recharts, Zustand (for `useMarketingStore`).  
+* **Backend (Sayan):** Python (FastAPI) utilizing the official `facebook-business` Python SDK.  
+* **Visual Generation (Sagnik):** ComfyUI API mode running locally, utilizing Flux-Schnell/Qwen-Image 2512 (Images) and Wan 2.2 14B/1.3B (Video).  
+* **Autonomous Logic (Sourik/Sayan):** PicoClaw/IronClaw agent triggered via FastAPI endpoints to manage bidding and rotation.
+
+#### **B. Core API Mappings (Meta to FastAPI)**
+
+Sayan must build these specific Python routes:
+
+* `POST /api/catalyst/campaigns/create`: Triggers Meta Marketing API to build campaigns in bulk.  
+* `POST /api/catalyst/creative/sync`: Uploads ComfyUI outputs (Wan 2.2 mp4s / Qwen pngs) directly to the Meta Asset Manager.  
+* `GET /api/catalyst/insights/realtime`: Polls Meta Ads Insights API for click-through rates, CPA, and spend limits.  
+* `POST /api/catalyst/audiences/lookalike`: Pushes "Qualified" or "Whale" leads from your CRM (Supabase) into Meta to create High-Net-Worth Lookalike Audiences.
+
+---
+
+### **Part 3: Scientific Breakdown of Tasks (Sprint Plan)**
+
+Here are the actionable tasks for you and Sayan to drop directly into your Taiga board for "The Catalyst" module.
+
+#### **👑 Sagnik’s Tasks (Visual AI & Architecture)**
+
+1. **Expose ComfyUI Endpoints for Catalyst Integration:**  
+   * **Action:** Ensure the `catalyst_poster_qwen.json` (Qwen-Image 2512\) and `cinematic_wan22_14b.json` (Wan 2.2) workflows are exposed via the ComfyUI Asynchronous Queue API.  
+   * **Output:** Provide Sayan with the exact JSON payload structures required to trigger these renders programmatically from the WebOS.  
+2. **Define Agentic System Prompts for Dynamic Creative:**  
+   * **Action:** Write the system prompts for the Claw agent. Instruct the agent on how to prompt Qwen-Image 2512 for A/B testing (e.g., "Generate Image A with English typography, Image B with Arabic typography").
+
+#### **💻 Sayan’s Tasks (Full-Stack & Meta API)**
+
+1. **Build the Catalyst Zustand Store & Layout (`app/src/components/modules/Catalyst.tsx`):**  
+   * **Action:** Create `useMarketingStore.ts` in Zustand to manage `campaigns[]`, `activeAssets[]`, and `adInsights{}`.  
+   * **UI Build:** Construct the 4-column Bento grid for the Analytics Dashboard using Recharts (similar to the LeadVelocityChart in the Dashboard).  
+2. **Meta Business API \- Auth & Settings Interface:**  
+   * **Action:** Build the Settings & API entry fields using `DarkInput` and `GhostButton` components.  
+   * **Backend:** Implement the OAuth flow in FastAPI to acquire and securely store the Meta System User Access Token in Supabase.  
+3. **Meta Marketing API \- The Integration Engine (`backend/api/routes_catalyst.py`):**  
+   * **Action:** Write the Python wrappers for the Meta Ads API.  
+   * **Function 1:** Implement **Audience Management**—write a script that automatically queries the Supabase CRM for leads tagged "Closed/Won" and pushes their hashed emails to Meta to update a Custom Audience.  
+   * **Function 2:** Implement **Dynamic Creative Rotation**—write an endpoint that accepts Sagnik's ComfyUI image/video URLs, uploads them to Meta's Ad Library, and assigns them to an active Ad Set for A/B testing.
+
+4. **Design the UI/UX Components:**  
+   * **Action:** Design the frontend component states for "Asset Generation". Use "Apple/Steve Jobs" aesthetic (glassmorphism, `backdrop-blur-xl`).  
+   * **Detail:** Must include a visual "Generation Queue" that uses latency-hiding (e.g., shimmering loading states that say *"Wan 2.2 is rendering cinematic lighting..."*).
+
+5. **Real-Time Optimization Dashboard (WebOS):**  
+   * **Action:** Create a `<LiveOptimizationFeed />` component using Framer Motion (`AnimatePresence`).  
+   * **Details:** It should stream WebSocket updates from the backend showing what the autonomous bot is doing (e.g., *"Agent Sourik paused Campaign X due to CPA \> $50"*).
+
+### **First-Principles Summary for Development**
+
+By structuring the Meta API exactly like this, you are not building an Ads Manager. You are building an **Autonomous Deployment Engine**. Sagnik's models (Wan/Qwen) act as the infinite creative agency, Sayan's React/FastAPI stack acts as the pipes, and Sourik's Claw agent acts as the media buyer turning those pipes on and off based on the real-time Meta Insights data.
+