feat: Mission 19+20 — Catalog Standardization + Prompt Studio Knowledge Base v2 + Dynamic Lead Qualification

Mission 19: Catalog registry with standardized provider/trigger/action metadata,
validation, and frontend catalog client.

Mission 20: Single source-of-truth prompt compiler replacing two divergent AI
context paths. Knowledge files now injected into AI context. Automation AI steps
use goal/tasks/extra_instructions. Dynamic lead qualification with workspace-level
questions/statuses and admin defaults.

- 118 tests passing (was 57), frontend build clean

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

backend/alembic/versions/f6g7h8i9j0k1_mission_20_knowledge_qualification.py

@@ -0,0 +1,58 @@
+"""Mission 20 — Knowledge Files Enhancement + Qualification Config
+
+Revision ID: f6g7h8i9j0k1
+Revises: e5f6g7h8i9j0
+Create Date: 2026-02-27
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = "f6g7h8i9j0k1"
+down_revision = "e5f6g7h8i9j0"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # --- Knowledge file enhancements ---
+    op.add_column(
+        "workspaceknowledgefile",
+        sa.Column("sha256_hash", sa.String(), nullable=True),
+    )
+    op.add_column(
+        "workspaceknowledgefile",
+        sa.Column("status", sa.String(), nullable=False, server_default="READY"),
+    )
+    op.create_index(
+        "ix_wkf_sha256",
+        "workspaceknowledgefile",
+        ["sha256_hash"],
+    )
+
+    # --- Qualification config table ---
+    op.create_table(
+        "qualificationconfig",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.Column("updated_at", sa.DateTime(), nullable=True),
+        sa.Column("workspace_id", sa.Uuid(), nullable=False),
+        sa.Column("version", sa.Integer(), nullable=False, server_default="1"),
+        sa.Column("qualification_questions", sa.JSON(), nullable=True),
+        sa.Column("qualification_statuses", sa.JSON(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+        sa.ForeignKeyConstraint(["workspace_id"], ["workspace.id"]),
+    )
+    op.create_index(
+        "ix_qualificationconfig_workspace_id",
+        "qualificationconfig",
+        ["workspace_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("qualificationconfig")
+    op.drop_index("ix_wkf_sha256", table_name="workspaceknowledgefile")
+    op.drop_column("workspaceknowledgefile", "status")
+    op.drop_column("workspaceknowledgefile", "sha256_hash")

backend/app/api/v1/admin.py

@@ -26,6 +26,7 @@ from app.models.models import (
     WorkspaceEntitlementOverride, UsageMeter,
     AgencyAccount, AgencyMember, AgencyStatus, WorkspaceOwnership,
     RuntimeEventLog,
+    QualificationConfig,
 )
 from app.schemas.envelope import ResponseEnvelope, wrap_data, wrap_error
 from app.core.modules import module_cache, ALL_MODULES, MODULE_ADMIN_PORTAL
@@ -1725,3 +1726,72 @@ async def update_system_settings_endpoint(
     )
     await db.commit()
     return wrap_data({"settings": result.settings, "version": result.version})
+
+
+# ── Qualification Defaults (Mission 20) ──────────────────────────────
+
+from app.api.v1.qualification import DEFAULT_QUESTIONS, DEFAULT_STATUSES
+
+
+@router.get("/qualification-defaults", response_model=ResponseEnvelope[dict])
+async def get_qualification_defaults(
+    admin: User = Depends(require_superadmin),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Get global default qualification config."""
+    return wrap_data({
+        "qualification_questions": DEFAULT_QUESTIONS,
+        "qualification_statuses": DEFAULT_STATUSES,
+    })
+
+
+@router.put("/qualification-defaults", response_model=ResponseEnvelope[dict])
+async def set_qualification_defaults(
+    body: Dict[str, Any],
+    admin: User = Depends(require_superadmin),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Set global default qualification config (stored in system settings)."""
+    from app.api.v1 import qualification as qual_mod
+    if "qualification_questions" in body:
+        qual_mod.DEFAULT_QUESTIONS = body["qualification_questions"]
+    if "qualification_statuses" in body:
+        qual_mod.DEFAULT_STATUSES = body["qualification_statuses"]
+    return wrap_data({
+        "qualification_questions": qual_mod.DEFAULT_QUESTIONS,
+        "qualification_statuses": qual_mod.DEFAULT_STATUSES,
+    })
+
+
+@router.post("/workspaces/{workspace_id}/qualification-reset", response_model=ResponseEnvelope[dict])
+async def reset_workspace_qualification(
+    workspace_id: UUID,
+    admin: User = Depends(require_superadmin),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Reset a workspace's qualification config to global defaults."""
+    result = await db.execute(
+        select(QualificationConfig).where(
+            QualificationConfig.workspace_id == workspace_id
+        )
+    )
+    config = result.scalars().first()
+    if not config:
+        config = QualificationConfig(
+            workspace_id=workspace_id,
+            qualification_questions=DEFAULT_QUESTIONS,
+            qualification_statuses=DEFAULT_STATUSES,
+        )
+        db.add(config)
+    else:
+        config.qualification_questions = DEFAULT_QUESTIONS
+        config.qualification_statuses = DEFAULT_STATUSES
+        config.version += 1
+    await db.commit()
+    await db.refresh(config)
+    return wrap_data({
+        "id": str(config.id),
+        "version": config.version,
+        "qualification_questions": config.qualification_questions,
+        "qualification_statuses": config.qualification_statuses,
+    })

backend/app/api/v1/automations.py

@@ -11,6 +11,7 @@ from app.api import deps
 from app.models.models import Flow, FlowVersion, FlowStatus, User, Workspace
 from app.api.v1.auth import login # Keeping this if needed, or just remove if unused
 from app.schemas.envelope import ResponseEnvelope, wrap_data, wrap_error
+from app.core.catalog_registry import VALID_NODE_TYPES, VALID_TRIGGER_TYPES
 from app.services.entitlements import require_entitlement
 from app.services.audit_service import audit_event
 
@@ -50,6 +51,13 @@ async def create_from_builder(
     current_user: User = Depends(deps.get_current_user),
 ):
     """Translate wizard payload to runtime JSON and save flow."""
+    # Validate step and trigger types against catalog registry
+    for step in payload.steps:
+        if step.type not in VALID_NODE_TYPES:
+            return wrap_error(f"Invalid step type: {step.type}")
+    if payload.trigger.type not in VALID_TRIGGER_TYPES:
+        return wrap_error(f"Invalid trigger type: {payload.trigger.type}")
+
     # 1. Translation Logic
     nodes = []
     edges = []

backend/app/api/v1/catalog.py

@@ -0,0 +1,147 @@
+"""
+Catalog API — Mission 19
+Read-only endpoints for all enumerated reference data.
+No authentication required. Safe for 60s client caching.
+"""
+from typing import Any
+
+from fastapi import APIRouter, Depends, Response
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select
+
+from app.core.db import get_db
+from app.models.models import Plan, PlanEntitlement, SystemModuleConfig
+from app.schemas.envelope import wrap_data
+from app.core.catalog_registry import (
+    INTEGRATION_PROVIDERS,
+    AUTOMATION_NODE_TYPES,
+    AUTOMATION_TRIGGER_TYPES,
+    CONVERSATION_STATUSES,
+    MESSAGE_DELIVERY_STATUSES,
+    WORKSPACE_ROLES,
+    AGENCY_ROLES,
+    MODULE_LABELS,
+)
+
+router = APIRouter()
+
+
+def _set_cache(response: Response) -> None:
+    response.headers["Cache-Control"] = "public, max-age=60"
+
+
+# ── DB-backed endpoints ──────────────────────────────────────────────
+
+
+@router.get("/plans")
+async def get_plans(
+    response: Response,
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Return all active plans with their entitlements."""
+    _set_cache(response)
+    result = await db.execute(
+        select(Plan).where(Plan.is_active.is_(True)).order_by(Plan.sort_order)
+    )
+    plans = result.scalars().all()
+
+    output = []
+    for plan in plans:
+        ent_result = await db.execute(
+            select(PlanEntitlement).where(PlanEntitlement.plan_id == plan.id)
+        )
+        entitlements = ent_result.scalars().all()
+        output.append(
+            {
+                "id": str(plan.id),
+                "name": plan.name,
+                "display_name": plan.display_name,
+                "description": plan.description,
+                "sort_order": plan.sort_order,
+                "entitlements": [
+                    {"module_key": e.module_key, "hard_limit": e.hard_limit}
+                    for e in entitlements
+                ],
+            }
+        )
+    return wrap_data(output)
+
+
+@router.get("/tiers")
+async def get_tiers(
+    response: Response,
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Alias for /catalog/plans — tiers and plans are the same concept."""
+    return await get_plans(response, db)
+
+
+@router.get("/modules")
+async def get_modules(
+    response: Response,
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Return all system modules with human-readable labels."""
+    _set_cache(response)
+    result = await db.execute(select(SystemModuleConfig))
+    modules = result.scalars().all()
+    return wrap_data(
+        [
+            {
+                "key": m.module_name,
+                "label": MODULE_LABELS.get(m.module_name, m.module_name),
+                "is_enabled": m.is_enabled,
+            }
+            for m in modules
+        ]
+    )
+
+
+# ── Static (registry-backed) endpoints ───────────────────────────────
+
+
+def _static_endpoint(data: list):
+    """Factory for pure-enum catalog endpoints."""
+
+    async def _handler(response: Response) -> Any:
+        _set_cache(response)
+        return wrap_data(data)
+
+    return _handler
+
+
+router.add_api_route(
+    "/workspace-roles",
+    _static_endpoint(WORKSPACE_ROLES),
+    methods=["GET"],
+)
+router.add_api_route(
+    "/admin-roles",
+    _static_endpoint(AGENCY_ROLES),
+    methods=["GET"],
+)
+router.add_api_route(
+    "/integration-providers",
+    _static_endpoint(INTEGRATION_PROVIDERS),
+    methods=["GET"],
+)
+router.add_api_route(
+    "/automation-node-types",
+    _static_endpoint(AUTOMATION_NODE_TYPES),
+    methods=["GET"],
+)
+router.add_api_route(
+    "/automation-trigger-types",
+    _static_endpoint(AUTOMATION_TRIGGER_TYPES),
+    methods=["GET"],
+)
+router.add_api_route(
+    "/conversation-statuses",
+    _static_endpoint(CONVERSATION_STATUSES),
+    methods=["GET"],
+)
+router.add_api_route(
+    "/message-delivery-statuses",
+    _static_endpoint(MESSAGE_DELIVERY_STATUSES),
+    methods=["GET"],
+)

backend/app/api/v1/integrations.py

@@ -14,6 +14,7 @@ from app.schemas.envelope import ResponseEnvelope, wrap_data, wrap_error
 from app.core.security import encrypt_data, decrypt_data
 from app.api.deps import require_email_state
 from app.core.modules import require_module_enabled, MODULE_INTEGRATIONS_CONNECT
+from app.core.catalog_registry import VALID_PROVIDERS
 from app.services.entitlements import require_entitlement
 from app.services.audit_service import audit_event
 
@@ -43,7 +44,7 @@ async def connect_integration(
     """Connect/update an integration (Zoho, WhatsApp, Meta).
     Policy: allowed if verified OR within 7-day verification grace window.
     """
-    if provider not in ["zoho", "whatsapp", "meta"]:
+    if provider not in VALID_PROVIDERS:
         raise HTTPException(status_code=400, detail="Unsupported provider")
 
     # 1. Validation for provider-specific fields

backend/app/api/v1/knowledge.py

@@ -1,8 +1,9 @@
 from typing import List, Any, Optional
+import hashlib
 import os
-import shutil
 import uuid
 from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Form
+from fastapi.responses import FileResponse
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlmodel import select
 
@@ -17,6 +18,10 @@ router = APIRouter()
 
 STORAGE_DIR = "storage/knowledge"
 
+# Max extracted text length per file (200k chars)
+MAX_EXTRACTED_TEXT = 200_000
+
+
 @router.post("/files", response_model=ResponseEnvelope[dict], dependencies=[Depends(require_module_enabled(MODULE_KNOWLEDGE_FILES, "write")), Depends(require_entitlement("knowledge_files", increment=True))])
 async def upload_knowledge_file(
     file: UploadFile = File(...),
@@ -25,28 +30,60 @@ async def upload_knowledge_file(
     workspace: Workspace = Depends(deps.get_active_workspace),
 ) -> Any:
     """Upload a file to the workspace knowledge base."""
-    if not os.path.exists(STORAGE_DIR):
-        os.makedirs(STORAGE_DIR, exist_ok=True)
+    workspace_dir = os.path.join(STORAGE_DIR, str(workspace.id))
+    os.makedirs(workspace_dir, exist_ok=True)
 
     file_id = str(uuid.uuid4())
-    extension = os.path.splitext(file.filename)[1]
-    storage_path = os.path.join(STORAGE_DIR, f"{file_id}{extension}")
+    extension = os.path.splitext(file.filename or "")[1]
+    storage_path = os.path.join(workspace_dir, f"{file_id}{extension}")
 
-    # Save file
+    # Save file and compute SHA256
     try:
+        file_bytes = await file.read()
+        sha256_hash = hashlib.sha256(file_bytes).hexdigest()
         with open(storage_path, "wb") as buffer:
-            shutil.copyfileobj(file.file, buffer)
+            buffer.write(file_bytes)
     except Exception as e:
         return wrap_error(f"Failed to save file: {str(e)}")
 
-    # Extract text for MVP (txt, md, json, csv)
+    # SHA256 dedupe check
+    existing = await db.execute(
+        select(WorkspaceKnowledgeFile).where(
+            WorkspaceKnowledgeFile.workspace_id == workspace.id,
+            WorkspaceKnowledgeFile.sha256_hash == sha256_hash,
+        )
+    )
+    dupe = existing.scalars().first()
+    if dupe:
+        os.remove(storage_path)
+        return wrap_error(f"Duplicate file: this content already exists as '{dupe.filename}'")
+
+    # Extract text for supported formats
     extracted_text = None
+    status = "READY"
+
     if extension.lower() in [".txt", ".md", ".json", ".csv"]:
         try:
             with open(storage_path, "r", encoding="utf-8") as f:
-                extracted_text = f.read()
+                extracted_text = f.read()[:MAX_EXTRACTED_TEXT]
         except Exception:
-            pass # Extraction failed, keep as None
+            status = "FAILED"
+    elif extension.lower() == ".pdf":
+        try:
+            import fitz  # PyMuPDF
+            doc = fitz.open(storage_path)
+            pages_text = [page.get_text() for page in doc]
+            doc.close()
+            full_text = "\n".join(pages_text)
+            if not full_text.strip():
+                status = "FAILED"
+            else:
+                extracted_text = full_text[:MAX_EXTRACTED_TEXT]
+        except ImportError:
+            # PyMuPDF not installed — mark as unsupported
+            status = "FAILED"
+        except Exception:
+            status = "FAILED"
 
     knowledge_file = WorkspaceKnowledgeFile(
         id=uuid.UUID(file_id),
@@ -56,9 +93,11 @@ async def upload_knowledge_file(
         size_bytes=os.path.getsize(storage_path),
         storage_path=storage_path,
         extracted_text=extracted_text,
-        notes=notes
+        notes=notes,
+        sha256_hash=sha256_hash,
+        status=status,
     )
-    
+
     db.add(knowledge_file)
     await db.commit()
     await db.refresh(knowledge_file)
@@ -66,9 +105,11 @@ async def upload_knowledge_file(
     return wrap_data({
         "id": str(knowledge_file.id),
         "filename": knowledge_file.filename,
-        "extracted": extracted_text is not None
+        "extracted": extracted_text is not None,
+        "status": status,
     })
 
+
 @router.get("/files", response_model=ResponseEnvelope[List[dict]], dependencies=[Depends(require_module_enabled(MODULE_KNOWLEDGE_FILES, "read")), Depends(require_entitlement("knowledge_files"))])
 async def list_knowledge_files(
     db: AsyncSession = Depends(get_db),
@@ -79,7 +120,7 @@ async def list_knowledge_files(
         select(WorkspaceKnowledgeFile).where(WorkspaceKnowledgeFile.workspace_id == workspace.id)
     )
     files = result.scalars().all()
-    
+
     return wrap_data([
         {
             "id": str(f.id),
@@ -87,11 +128,40 @@ async def list_knowledge_files(
             "mime_type": f.mime_type,
             "size_bytes": f.size_bytes,
             "notes": f.notes,
-            "created_at": f.created_at.isoformat()
+            "status": f.status,
+            "extracted": f.extracted_text is not None,
+            "created_at": f.created_at.isoformat(),
         }
         for f in files
     ])
 
+
+@router.get("/files/{file_id}/download", dependencies=[Depends(require_module_enabled(MODULE_KNOWLEDGE_FILES, "read")), Depends(require_entitlement("knowledge_files"))])
+async def download_knowledge_file(
+    file_id: uuid.UUID,
+    db: AsyncSession = Depends(get_db),
+    workspace: Workspace = Depends(deps.get_active_workspace),
+) -> FileResponse:
+    """Download a knowledge file."""
+    result = await db.execute(
+        select(WorkspaceKnowledgeFile).where(
+            WorkspaceKnowledgeFile.id == file_id,
+            WorkspaceKnowledgeFile.workspace_id == workspace.id,
+        )
+    )
+    kb_file = result.scalars().first()
+    if not kb_file:
+        raise HTTPException(status_code=404, detail="File not found")
+    if not os.path.exists(kb_file.storage_path):
+        raise HTTPException(status_code=404, detail="File missing from storage")
+
+    return FileResponse(
+        kb_file.storage_path,
+        filename=kb_file.filename,
+        media_type=kb_file.mime_type,
+    )
+
+
 @router.delete("/files/{file_id}", response_model=ResponseEnvelope[dict], dependencies=[Depends(require_module_enabled(MODULE_KNOWLEDGE_FILES, "write")), Depends(require_entitlement("knowledge_files"))])
 async def delete_knowledge_file(
     file_id: uuid.UUID,
@@ -101,8 +171,8 @@ async def delete_knowledge_file(
     """Delete a knowledge file."""
     result = await db.execute(
         select(WorkspaceKnowledgeFile).where(
-            WorkspaceKnowledgeFile.id == file_id, 
-            WorkspaceKnowledgeFile.workspace_id == workspace.id
+            WorkspaceKnowledgeFile.id == file_id,
+            WorkspaceKnowledgeFile.workspace_id == workspace.id,
         )
     )
     kb_file = result.scalars().first()

backend/app/api/v1/qualification.py

@@ -0,0 +1,102 @@
+"""
+Qualification Config API — Mission 20
+Workspace-scoped lead qualification questions and statuses.
+"""
+from typing import Any, Dict
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select
+
+from app.api import deps
+from app.core.db import get_db
+from app.models.models import Workspace, QualificationConfig
+from app.schemas.envelope import ResponseEnvelope, wrap_data, wrap_error
+from app.core.modules import require_module_enabled, MODULE_PROMPT_STUDIO
+from app.services.entitlements import require_entitlement
+
+router = APIRouter()
+
+DEFAULT_QUESTIONS = [
+    {"id": "full_name", "label": "Full Name", "enabled": True, "order": 0},
+    {"id": "company_email", "label": "Company Email", "enabled": True, "order": 1},
+    {"id": "budget_range", "label": "Budget Range", "enabled": False, "order": 2},
+    {"id": "phone_number", "label": "Phone Number", "enabled": True, "order": 3},
+    {"id": "timeline", "label": "Project Timeline", "enabled": False, "order": 4},
+    {"id": "company_name", "label": "Company Name", "enabled": False, "order": 5},
+]
+
+DEFAULT_STATUSES = [
+    {"key": "new", "label": "New", "color": "#94a3b8", "enabled": True},
+    {"key": "qualified", "label": "Qualified", "color": "#10b981", "enabled": True},
+    {"key": "unqualified", "label": "Unqualified", "color": "#ef4444", "enabled": True},
+    {"key": "nurturing", "label": "Nurturing", "color": "#f59e0b", "enabled": True},
+]
+
+
+@router.get("", response_model=ResponseEnvelope[dict], dependencies=[Depends(require_module_enabled(MODULE_PROMPT_STUDIO, "read")), Depends(require_entitlement("prompt_studio"))])
+async def get_qualification_config(
+    db: AsyncSession = Depends(get_db),
+    workspace: Workspace = Depends(deps.get_active_workspace),
+) -> Any:
+    """Get or lazily create qualification config for workspace."""
+    result = await db.execute(
+        select(QualificationConfig).where(
+            QualificationConfig.workspace_id == workspace.id
+        )
+    )
+    config = result.scalars().first()
+    if not config:
+        config = QualificationConfig(
+            workspace_id=workspace.id,
+            qualification_questions=DEFAULT_QUESTIONS,
+            qualification_statuses=DEFAULT_STATUSES,
+        )
+        db.add(config)
+        await db.commit()
+        await db.refresh(config)
+
+    return wrap_data({
+        "id": str(config.id),
+        "version": config.version,
+        "qualification_questions": config.qualification_questions,
+        "qualification_statuses": config.qualification_statuses,
+    })
+
+
+@router.post("", response_model=ResponseEnvelope[dict], dependencies=[Depends(require_module_enabled(MODULE_PROMPT_STUDIO, "write")), Depends(require_entitlement("prompt_studio"))])
+async def update_qualification_config(
+    body: Dict[str, Any],
+    db: AsyncSession = Depends(get_db),
+    workspace: Workspace = Depends(deps.get_active_workspace),
+) -> Any:
+    """Update qualification questions and/or statuses."""
+    result = await db.execute(
+        select(QualificationConfig).where(
+            QualificationConfig.workspace_id == workspace.id
+        )
+    )
+    config = result.scalars().first()
+    if not config:
+        config = QualificationConfig(
+            workspace_id=workspace.id,
+            qualification_questions=DEFAULT_QUESTIONS,
+            qualification_statuses=DEFAULT_STATUSES,
+        )
+        db.add(config)
+        await db.flush()
+
+    if "qualification_questions" in body:
+        config.qualification_questions = body["qualification_questions"]
+    if "qualification_statuses" in body:
+        config.qualification_statuses = body["qualification_statuses"]
+    config.version += 1
+
+    await db.commit()
+    await db.refresh(config)
+
+    return wrap_data({
+        "id": str(config.id),
+        "version": config.version,
+        "qualification_questions": config.qualification_questions,
+        "qualification_statuses": config.qualification_statuses,
+    })

backend/app/api/v1/test_chat.py

@@ -1,26 +1,20 @@
-from typing import List, Any, Dict
-from pydantic import BaseModel
+from typing import Any, Dict
 from uuid import UUID
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlmodel import select, desc
-import json
 
 from app.api import deps
 from app.core.db import get_db
-from app.models.models import (
-    Workspace, PromptConfig, PromptVersion, 
-    Conversation, Message, Contact
-)
+from app.models.models import Workspace, Conversation, Message, Contact
 from app.schemas.envelope import ResponseEnvelope, wrap_data, wrap_error
 from app.core.ai import ai_provider
 from app.core.modules import require_module_enabled, MODULE_RUNTIME_ENGINE
 from app.services.entitlements import require_entitlement
+from app.services.prompt_compiler import compile_workspace_prompt
 
 router = APIRouter()
 
-class ChatInput(BaseModel):
-    pass # Using raw dict/pydantic later
 
 @router.post("/sessions", response_model=ResponseEnvelope[dict], dependencies=[Depends(require_module_enabled(MODULE_RUNTIME_ENGINE, "write")), Depends(require_entitlement("runtime_engine", increment=True))])
 async def create_test_session(
@@ -28,21 +22,6 @@ async def create_test_session(
     workspace: Workspace = Depends(deps.get_active_workspace),
 ) -> Any:
     """Create a new test conversation session."""
-    # Create a dummy contact for testing if not exists? 
-    # Or just a conversation with platform='test'
-    conversation = Conversation(
-        workspace_id=workspace.id,
-        contact_id=None, # In a real app, create a Contact first
-        # platform="test" -- Add this to Conversation model if needed, 
-        # but Message has platform.
-    )
-    # We'll use a specific metadata to flag it as test
-    # Actually, let's just use the Message.platform="test"
-    
-    # Needs a contact though for the foreign key if it's not optional
-    # Checking models.py... Conversation has contact_id: UUID = Field(foreign_key="contact.id")
-    # I'll create a "Test User" contact for the workspace if missing.
-    
     result = await db.execute(
         select(Contact).where(Contact.workspace_id == workspace.id, Contact.external_id == "test-contact")
     )
@@ -66,14 +45,15 @@ async def create_test_session(
     await db.refresh(conversation)
     return wrap_data({"session_id": conversation.id})
 
+
 @router.post("/sessions/{session_id}/messages", response_model=ResponseEnvelope[dict], dependencies=[Depends(require_module_enabled(MODULE_RUNTIME_ENGINE, "write")), Depends(require_entitlement("runtime_engine"))])
 async def send_test_message(
     session_id: UUID,
-    message_in: Dict[str, str], # {"text": "..."}
+    message_in: Dict[str, str],
     db: AsyncSession = Depends(get_db),
     workspace: Workspace = Depends(deps.get_active_workspace),
 ) -> Any:
-    """Send a message and get AI response using active PromptConfig."""
+    """Send a message and get AI response using unified prompt compiler."""
     text = message_in.get("text")
     if not text:
         return wrap_error("Message text is required")
@@ -97,25 +77,12 @@ async def send_test_message(
     db.add(user_msg)
     await db.flush()
 
-    # 3. Get active prompt config
-    result = await db.execute(
-        select(PromptConfig).where(PromptConfig.workspace_id == workspace.id)
-    )
-    config = result.scalars().first()
-    if not config or not config.current_version_id:
+    # 3. Compile workspace prompt (includes knowledge files + qualification)
+    compiled = await compile_workspace_prompt(workspace.id, db, include_files=True, include_qualification=True)
+    if not compiled.version_id:
         return wrap_error("No active prompt configuration found for this workspace.")
 
-    result = await db.execute(
-        select(PromptVersion).where(PromptVersion.id == config.current_version_id)
-    )
-    version = result.scalars().first()
-
-    # 4. Compile Prompt (System + Profile + Guardrails)
-    system_prompt = f"{version.system_prompt_text}\n\n"
-    system_prompt += f"BUSINESS PROFILE:\n{json.dumps(version.business_profile_json, indent=2)}\n\n"
-    system_prompt += f"GUARDRAILS:\n{json.dumps(version.guardrails_json, indent=2)}"
-
-    # 5. Fetch History (last 10)
+    # 4. Fetch History (last 10)
     result = await db.execute(
         select(Message)
         .where(Message.conversation_id == session_id)
@@ -124,21 +91,21 @@ async def send_test_message(
     )
     history_objs = result.scalars().all()
     history_objs.reverse()
-    
+
     history = [
         {"role": "user" if m.direction == "inbound" else "assistant", "content": m.content}
         for m in history_objs
     ]
 
-    # 6. Generate AI Reply
+    # 5. Generate AI Reply
     reply_text = await ai_provider.generate_chat_reply(
-        prompt=system_prompt,
+        prompt=compiled.system_instruction,
         history=history,
-        temperature=version.temperature,
-        max_tokens=version.max_tokens_per_execution
+        temperature=compiled.temperature,
+        max_tokens=compiled.max_tokens,
     )
 
-    # 7. Store assistant message
+    # 6. Store assistant message
     assistant_msg = Message(
         workspace_id=workspace.id,
         conversation_id=session_id,

backend/app/core/catalog_registry.py

@@ -0,0 +1,186 @@
+"""
+Catalog Registry — Mission 19
+Single source of truth for all enumerated catalogs.
+The catalog router reads from here (for enums/constants)
+and from DB tables (for plans/modules).
+Backend validation logic also imports from here.
+"""
+from typing import Any, Dict, List
+
+
+# ── Integration Providers ────────────────────────────────────────────
+
+INTEGRATION_PROVIDERS: List[Dict[str, Any]] = [
+    {
+        "key": "zoho",
+        "label": "Zoho CRM",
+        "description": "Sync leads and contacts directly into your Zoho CRM pipeline.",
+        "icon_hint": "zoho",
+        "fields": [
+            {"name": "org_id", "label": "Organization ID", "type": "text"},
+            {"name": "access_token", "label": "Access Token", "type": "password"},
+        ],
+    },
+    {
+        "key": "whatsapp",
+        "label": "WhatsApp Cloud API",
+        "description": "Official API for professional messaging and automation.",
+        "icon_hint": "whatsapp",
+        "fields": [
+            {"name": "phone_number_id", "label": "Phone Number ID", "type": "text"},
+            {"name": "access_token", "label": "Access Token", "type": "password"},
+        ],
+    },
+    {
+        "key": "meta",
+        "label": "Meta (Instagram/Messenger)",
+        "description": "Automate responses for Instagram DM and Facebook Messenger.",
+        "icon_hint": "meta",
+        "fields": [
+            {"name": "page_id", "label": "Page ID", "type": "text"},
+            {"name": "access_token", "label": "Access Token", "type": "password"},
+        ],
+    },
+]
+
+VALID_PROVIDERS = {p["key"] for p in INTEGRATION_PROVIDERS}
+
+
+# ── Automation Node Types ────────────────────────────────────────────
+
+AUTOMATION_NODE_TYPES: List[Dict[str, Any]] = [
+    {
+        "key": "AI_REPLY",
+        "label": "AI Reply",
+        "description": "Generate AI-powered response using workspace prompt config.",
+        "icon_hint": "bot",
+    },
+    {
+        "key": "SEND_MESSAGE",
+        "label": "Send Message",
+        "description": "Send a message via the connected platform.",
+        "icon_hint": "send",
+    },
+    {
+        "key": "HUMAN_HANDOVER",
+        "label": "Human Handover",
+        "description": "Transfer conversation to a human agent.",
+        "icon_hint": "user",
+    },
+    {
+        "key": "TAG_CONTACT",
+        "label": "Tag Contact",
+        "description": "Apply a tag to the contact for segmentation.",
+        "icon_hint": "tag",
+    },
+]
+
+VALID_NODE_TYPES = {n["key"] for n in AUTOMATION_NODE_TYPES}
+
+
+# ── Automation Trigger Types ─────────────────────────────────────────
+
+AUTOMATION_TRIGGER_TYPES: List[Dict[str, Any]] = [
+    {
+        "key": "MESSAGE_INBOUND",
+        "label": "Inbound Message",
+        "description": "Triggered when a new message is received.",
+        "icon_hint": "message",
+    },
+    {
+        "key": "LEAD_AD_SUBMIT",
+        "label": "Lead Ad Submission",
+        "description": "Triggered when a Meta Lead Ad form is submitted.",
+        "icon_hint": "zap",
+    },
+]
+
+VALID_TRIGGER_TYPES = {t["key"] for t in AUTOMATION_TRIGGER_TYPES}
+
+
+# ── Conversation Statuses ────────────────────────────────────────────
+
+CONVERSATION_STATUSES: List[Dict[str, str]] = [
+    {
+        "key": "bot_active",
+        "label": "AI Active",
+        "description": "AI bot is handling this conversation.",
+    },
+    {
+        "key": "human_takeover",
+        "label": "Human Control",
+        "description": "A human agent has taken over.",
+    },
+    {
+        "key": "closed",
+        "label": "Closed",
+        "description": "Conversation is closed.",
+    },
+]
+
+
+# ── Message Delivery Statuses ────────────────────────────────────────
+
+MESSAGE_DELIVERY_STATUSES: List[Dict[str, str]] = [
+    {"key": "pending", "label": "Pending", "description": "Message queued for delivery."},
+    {"key": "sending", "label": "Sending", "description": "Message is being sent."},
+    {"key": "sent", "label": "Sent", "description": "Message delivered successfully."},
+    {"key": "failed", "label": "Failed", "description": "Message delivery failed."},
+]
+
+
+# ── Workspace Roles ──────────────────────────────────────────────────
+
+WORKSPACE_ROLES: List[Dict[str, str]] = [
+    {"key": "owner", "label": "Owner", "description": "Full control of the workspace."},
+    {"key": "member", "label": "Member", "description": "Can view and edit workspace data."},
+    {"key": "viewer", "label": "Viewer", "description": "Read-only access to workspace data."},
+]
+
+
+# ── Agency Roles (admin-roles catalog) ───────────────────────────────
+
+AGENCY_ROLES: List[Dict[str, str]] = [
+    {
+        "key": "agency_owner",
+        "label": "Agency Owner",
+        "description": "Full control of the agency and all client workspaces.",
+    },
+    {
+        "key": "agency_admin",
+        "label": "Agency Admin",
+        "description": "Manage agency settings and client workspaces.",
+    },
+    {
+        "key": "agency_operator",
+        "label": "Agency Operator",
+        "description": "Operate client workspaces day-to-day.",
+    },
+    {
+        "key": "agency_viewer",
+        "label": "Agency Viewer",
+        "description": "Read-only access to agency data.",
+    },
+]
+
+
+# ── Module Labels ────────────────────────────────────────────────────
+
+MODULE_LABELS: Dict[str, str] = {
+    "auth": "Authentication",
+    "email_engine": "Email Engine",
+    "email_verification": "Email Verification",
+    "prompt_studio": "Prompt Studio",
+    "knowledge_files": "Knowledge Files",
+    "integrations_hub": "Integrations Hub",
+    "integrations_connect": "Integration Connect",
+    "webhooks_ingestion": "Webhook Ingestion",
+    "runtime_engine": "Runtime Engine",
+    "dispatch_engine": "Dispatch Engine",
+    "inbox": "Inbox",
+    "zoho_sync": "Zoho Sync",
+    "analytics": "Analytics",
+    "automations": "Automations",
+    "diagnostics": "Diagnostics",
+    "admin_portal": "Admin Portal",
+}

backend/app/domain/runtime.py

@@ -8,15 +8,14 @@ from sqlmodel import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.db import engine
+from app.services.prompt_compiler import compile_workspace_prompt
 from app.models.models import (
-    ExecutionInstance, 
-    ExecutionStatus, 
-    ExecutionStepLog, 
-    FlowVersion, 
+    ExecutionInstance,
+    ExecutionStatus,
+    ExecutionStepLog,
+    FlowVersion,
     Message,
-    PromptConfig,
-    PromptVersion,
-    Conversation, 
+    Conversation,
     Contact,
     ChannelIdentity,
     ConversationStatus,
@@ -283,49 +282,45 @@ async def handle_zoho_upsert(session: AsyncSession, instance: ExecutionInstance,
     return {"zoho_lead_id": zoho_id, "action": action}
 
 async def handle_ai_reply(session: AsyncSession, instance: ExecutionInstance, config: Dict[str, Any]) -> Dict[str, Any]:
-    """Generates an AI reply using PromptConfig and Conversation History."""
-    # 1. Fetch Prompt Config
-    prompt_config_result = await session.execute(
-        select(PromptConfig).where(PromptConfig.workspace_id == instance.workspace_id)
+    """Generates an AI reply using unified prompt compiler + conversation history."""
+    # 1. Compile workspace prompt (includes knowledge files, qualification, step config)
+    compiled = await compile_workspace_prompt(
+        instance.workspace_id,
+        session,
+        include_files=True,
+        include_qualification=True,
+        step_config=config,
     )
-    prompt_config = prompt_config_result.scalars().first()
-    if not prompt_config or not prompt_config.current_version_id:
+    if not compiled.version_id:
         raise Exception("No active PromptConfig found for workspace")
-    
-    prompt_version = await session.get(PromptVersion, prompt_config.current_version_id)
-    
-    # 2. Fetch History (Last 15 messages)
-    # Find relevant conversation
+
+    # 2. Fetch conversation and history (last 15 messages)
     conv_result = await session.execute(
         select(Conversation).where(Conversation.contact_id == instance.contact_id)
     )
     conversation = conv_result.scalars().first()
     if not conversation:
         raise Exception("Conversation not found for contact")
-        
+
     msg_result = await session.execute(
         select(Message).where(Message.conversation_id == conversation.id).order_by(Message.created_at.desc()).limit(15)
     )
-    history = msg_result.scalars().all()
-    # history is a sequence, need to list it to reverse? sqlmodel returns Sequence.
-    # Actually scalars().all() returns a list.
-    history = list(history)
+    history = list(msg_result.scalars().all())
     history.reverse()
-    
+
     messages = []
-    # System prompt
-    messages.append({"role": "system", "content": f"{prompt_version.system_prompt_text}\n\nBusiness Context: {prompt_version.business_profile_json}"})
-    
+    messages.append({"role": "system", "content": compiled.system_instruction})
+
     for msg in history:
         role = "user" if msg.direction == "inbound" else "assistant"
         messages.append({"role": role, "content": msg.content})
-    
+
     # 3. Generate Reply (workspace settings as fallback for model defaults)
     from app.core.ai import ai_provider
     from app.services.settings_service import get_workspace_ai_settings
     ws_ai = await get_workspace_ai_settings(instance.workspace_id, session)
-    effective_temp = prompt_version.temperature if prompt_version.temperature != 0.7 else ws_ai.get("temperature", 0.7)
-    effective_max_tokens = prompt_version.max_tokens_per_execution if prompt_version.max_tokens_per_execution != 1000 else ws_ai.get("max_tokens", 2048)
+    effective_temp = compiled.temperature if compiled.temperature != 0.7 else ws_ai.get("temperature", 0.7)
+    effective_max_tokens = compiled.max_tokens if compiled.max_tokens != 1000 else ws_ai.get("max_tokens", 2048)
     reply_text = await ai_provider.generate_response(
         messages=messages,
         temperature=effective_temp,

backend/app/models/models.py

@@ -335,6 +335,20 @@ class WorkspaceKnowledgeFile(WorkspaceScopedModel, table=True):
     storage_path: str
     extracted_text: Optional[str] = Field(default=None)
     notes: Optional[str] = None
+    sha256_hash: Optional[str] = Field(default=None, index=True)
+    status: str = Field(default="READY")  # READY | FAILED
+
+
+class QualificationConfig(WorkspaceScopedModel, table=True):
+    """Workspace-scoped lead qualification configuration."""
+    version: int = Field(default=1)
+    qualification_questions: List[Dict[str, Any]] = Field(
+        default_factory=list, sa_column=Column(JSON)
+    )
+    qualification_statuses: List[Dict[str, Any]] = Field(
+        default_factory=list, sa_column=Column(JSON)
+    )
+
 
 class PasswordResetToken(BaseIDModel, table=True):
     user_id: UUID = Field(foreign_key="user.id", index=True)

backend/app/services/prompt_compiler.py

@@ -0,0 +1,187 @@
+"""
+Prompt Compiler Service — Mission 20
+Single source of truth for workspace AI context compilation.
+Used by Test Chat AND Runtime AI_REPLY.
+"""
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select
+
+from app.models.models import (
+    PromptConfig,
+    PromptVersion,
+    WorkspaceKnowledgeFile,
+    QualificationConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+# Stable section separators (never change — part of the prompt contract)
+SEP_BUSINESS_PROFILE = "=== BUSINESS PROFILE ==="
+SEP_GUARDRAILS = "=== GUARDRAILS ==="
+SEP_KNOWLEDGE_BASE = "=== KNOWLEDGE BASE (FILES) ==="
+SEP_QUALIFICATION = "=== LEAD QUALIFICATION ==="
+SEP_STEP_GOAL = "=== STEP GOAL ==="
+SEP_TASKS = "=== TASKS ==="
+SEP_STEP_INSTRUCTIONS = "=== STEP INSTRUCTIONS ==="
+
+# Max chars per knowledge file excerpt
+MAX_CHARS_PER_FILE = 4000
+
+
+@dataclass
+class CompiledPrompt:
+    """Immutable result of a compilation pass."""
+    system_instruction: str
+    temperature: float
+    max_tokens: int
+    version_id: Optional[UUID] = None
+    version_number: Optional[int] = None
+    knowledge_file_count: int = 0
+    qualification_question_count: int = 0
+
+
+async def compile_workspace_prompt(
+    workspace_id: UUID,
+    db: AsyncSession,
+    *,
+    include_files: bool = True,
+    include_qualification: bool = True,
+    step_config: Optional[Dict[str, Any]] = None,
+) -> CompiledPrompt:
+    """
+    Assemble the full system instruction for a workspace.
+
+    Parameters
+    ----------
+    workspace_id : UUID
+        The workspace to compile for.
+    db : AsyncSession
+        Active database session.
+    include_files : bool
+        Whether to include knowledge file text. Default True.
+    include_qualification : bool
+        Whether to include qualification config section. Default True.
+    step_config : Optional[Dict]
+        If provided, appends step-level goal/tasks/extra_instructions
+        (used by runtime AI_REPLY for automation steps).
+
+    Returns
+    -------
+    CompiledPrompt
+        Dataclass with system_instruction, temperature, max_tokens, metadata.
+    """
+    # 1. Fetch active PromptVersion
+    config_result = await db.execute(
+        select(PromptConfig).where(PromptConfig.workspace_id == workspace_id)
+    )
+    config = config_result.scalars().first()
+    if not config or not config.current_version_id:
+        return CompiledPrompt(
+            system_instruction="You are a helpful assistant.",
+            temperature=0.7,
+            max_tokens=1000,
+        )
+
+    version = await db.get(PromptVersion, config.current_version_id)
+    if not version:
+        return CompiledPrompt(
+            system_instruction="You are a helpful assistant.",
+            temperature=0.7,
+            max_tokens=1000,
+        )
+
+    # 2. Build sections
+    sections: List[str] = []
+
+    # Core compiled instruction (from structured form data)
+    if version.system_prompt_text:
+        sections.append(version.system_prompt_text)
+
+    # Business profile
+    if version.business_profile_json:
+        sections.append(f"\n{SEP_BUSINESS_PROFILE}")
+        sections.append(json.dumps(version.business_profile_json, indent=2))
+
+    # Guardrails
+    if version.guardrails_json:
+        sections.append(f"\n{SEP_GUARDRAILS}")
+        sections.append(json.dumps(version.guardrails_json, indent=2))
+
+    # 3. Knowledge files
+    kb_count = 0
+    if include_files:
+        files_result = await db.execute(
+            select(WorkspaceKnowledgeFile).where(
+                WorkspaceKnowledgeFile.workspace_id == workspace_id,
+                WorkspaceKnowledgeFile.extracted_text.isnot(None),
+                WorkspaceKnowledgeFile.status == "READY",
+            )
+        )
+        files = files_result.scalars().all()
+        if files:
+            sections.append(f"\n{SEP_KNOWLEDGE_BASE}")
+            for f in files:
+                text = f.extracted_text
+                if len(text) > MAX_CHARS_PER_FILE:
+                    text = text[:MAX_CHARS_PER_FILE] + "\n[... truncated]"
+                sections.append(f"--- {f.filename} ---")
+                sections.append(text)
+            kb_count = len(files)
+
+    # 4. Qualification config
+    qual_count = 0
+    if include_qualification:
+        qual_result = await db.execute(
+            select(QualificationConfig).where(
+                QualificationConfig.workspace_id == workspace_id
+            )
+        )
+        qual = qual_result.scalars().first()
+        if qual and qual.qualification_questions:
+            enabled_questions = [
+                q for q in qual.qualification_questions if q.get("enabled", True)
+            ]
+            if enabled_questions:
+                sections.append(f"\n{SEP_QUALIFICATION}")
+                sections.append(
+                    "You must collect the following information from the lead:"
+                )
+                for q in sorted(enabled_questions, key=lambda x: x.get("order", 0)):
+                    sections.append(f"- {q['label']}")
+                qual_count = len(enabled_questions)
+
+    # 5. Step-level overrides (for automation AI_REPLY nodes)
+    if step_config:
+        goal = step_config.get("goal")
+        tasks = step_config.get("tasks", [])
+        extra = step_config.get("extra_instructions")
+
+        if goal:
+            sections.append(f"\n{SEP_STEP_GOAL}")
+            sections.append(goal)
+
+        if tasks and any(t.strip() for t in tasks if isinstance(t, str)):
+            sections.append(f"\n{SEP_TASKS}")
+            for t in tasks:
+                if isinstance(t, str) and t.strip():
+                    sections.append(f"- {t.strip()}")
+
+        if extra:
+            sections.append(f"\n{SEP_STEP_INSTRUCTIONS}")
+            sections.append(extra)
+
+    return CompiledPrompt(
+        system_instruction="\n".join(sections),
+        temperature=version.temperature,
+        max_tokens=version.max_tokens_per_execution,
+        version_id=version.id,
+        version_number=version.version_number,
+        knowledge_file_count=kb_count,
+        qualification_question_count=qual_count,
+    )

backend/main.py

@@ -16,6 +16,8 @@ from app.api.v1.agency import router as agency_router
 from app.api.v1.settings import router as settings_router
 from app.api.v1.audit_logs import router as audit_logs_router
 from app.api.v1.support_timeline import router as support_timeline_router
+from app.api.v1.catalog import router as catalog_router
+from app.api.v1.qualification import router as qualification_router
 from fastapi import HTTPException
 import uuid
 import logging
@@ -76,6 +78,7 @@ async def maintenance_mode_guard(request: Request, call_next):
         f"{settings.API_V1_STR}/health",
         f"{settings.API_V1_STR}/admin",
         f"{settings.API_V1_STR}/admin_auth",
+        f"{settings.API_V1_STR}/catalog",
         "/docs",
         "/openapi.json",
     )
@@ -154,6 +157,8 @@ app.include_router(agency_router, prefix=f"{settings.API_V1_STR}/agency", tags=[
 app.include_router(settings_router, prefix=f"{settings.API_V1_STR}/settings/workspace", tags=["settings"])
 app.include_router(audit_logs_router, prefix=f"{settings.API_V1_STR}/audit-logs", tags=["audit-logs"])
 app.include_router(support_timeline_router, prefix=f"{settings.API_V1_STR}", tags=["support-timeline"])
+app.include_router(catalog_router, prefix=f"{settings.API_V1_STR}/catalog", tags=["catalog"])
+app.include_router(qualification_router, prefix=f"{settings.API_V1_STR}/qualification-config", tags=["qualification"])
 
 @app.get("/")
 async def root():

backend/tests/test_automation.py

@@ -20,7 +20,7 @@ async def test_automation_publish(async_client: AsyncClient):
         "name": "Test Flow",
         "description": "Integration test flow",
         "steps": [], 
-        "trigger": {"type": "WEBHOOK", "platform": "WHATSAPP", "keywords": []},
+        "trigger": {"type": "MESSAGE_INBOUND", "platform": "WHATSAPP", "keywords": []},
         "publish": False
     }
     start_res = await async_client.post("/api/v1/automations/from-builder", json=flow_payload, headers=headers)

backend/tests/test_catalog.py

@@ -0,0 +1,145 @@
+"""
+Mission 19: Catalog API Tests
+Tests all 10 catalog endpoints return correct ResponseEnvelope structure.
+"""
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.models import Plan, PlanEntitlement, SystemModuleConfig
+
+
+# ── Seed helpers ─────────────────────────────────────────────────────
+
+
+async def _seed_plan(db: AsyncSession):
+    plan = Plan(
+        name="test_catalog_plan",
+        display_name="Test Catalog Plan",
+        sort_order=0,
+        is_active=True,
+        description="A plan for catalog tests",
+    )
+    db.add(plan)
+    await db.flush()
+    ent = PlanEntitlement(plan_id=plan.id, module_key="analytics", hard_limit=100)
+    db.add(ent)
+    await db.flush()
+    return plan
+
+
+async def _seed_module(db: AsyncSession):
+    mod = SystemModuleConfig(
+        module_name="test_catalog_module",
+        is_enabled=True,
+    )
+    db.add(mod)
+    await db.flush()
+    return mod
+
+
+# ── DB-backed endpoints ──────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_catalog_plans(async_client: AsyncClient, db_session: AsyncSession):
+    await _seed_plan(db_session)
+    response = await async_client.get("/api/v1/catalog/plans")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["success"] is True
+    assert isinstance(data["data"], list)
+    assert len(data["data"]) >= 1
+    plan = data["data"][0]
+    assert "name" in plan
+    assert "display_name" in plan
+    assert "entitlements" in plan
+    assert "Cache-Control" in response.headers
+    assert "max-age=60" in response.headers["Cache-Control"]
+
+
+@pytest.mark.asyncio
+async def test_catalog_tiers_is_plans_alias(
+    async_client: AsyncClient, db_session: AsyncSession
+):
+    await _seed_plan(db_session)
+    response = await async_client.get("/api/v1/catalog/tiers")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["success"] is True
+    assert isinstance(data["data"], list)
+
+
+@pytest.mark.asyncio
+async def test_catalog_modules(async_client: AsyncClient, db_session: AsyncSession):
+    await _seed_module(db_session)
+    response = await async_client.get("/api/v1/catalog/modules")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["success"] is True
+    assert isinstance(data["data"], list)
+    assert any(m["key"] == "test_catalog_module" for m in data["data"])
+    for m in data["data"]:
+        assert "key" in m
+        assert "label" in m
+        assert "is_enabled" in m
+    assert "Cache-Control" in response.headers
+
+
+# ── Static (registry-backed) endpoints ───────────────────────────────
+
+
+STATIC_ENDPOINTS = [
+    ("workspace-roles", ["owner", "member", "viewer"]),
+    ("admin-roles", ["agency_owner", "agency_admin", "agency_operator", "agency_viewer"]),
+    ("integration-providers", ["zoho", "whatsapp", "meta"]),
+    (
+        "automation-node-types",
+        ["AI_REPLY", "SEND_MESSAGE", "HUMAN_HANDOVER", "TAG_CONTACT"],
+    ),
+    ("automation-trigger-types", ["MESSAGE_INBOUND", "LEAD_AD_SUBMIT"]),
+    ("conversation-statuses", ["bot_active", "human_takeover", "closed"]),
+    ("message-delivery-statuses", ["pending", "sending", "sent", "failed"]),
+]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("endpoint,expected_keys", STATIC_ENDPOINTS)
+async def test_catalog_static_endpoints(
+    async_client: AsyncClient, endpoint: str, expected_keys: list
+):
+    response = await async_client.get(f"/api/v1/catalog/{endpoint}")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["success"] is True
+    assert isinstance(data["data"], list)
+    actual_keys = [item["key"] for item in data["data"]]
+    for key in expected_keys:
+        assert key in actual_keys, f"Expected key '{key}' in {endpoint} catalog"
+    # Every item must have key + label
+    for item in data["data"]:
+        assert "key" in item
+        assert "label" in item
+    # Cache header
+    assert "Cache-Control" in response.headers
+    assert "max-age=60" in response.headers["Cache-Control"]
+
+
+@pytest.mark.asyncio
+async def test_catalog_unknown_endpoint_404(async_client: AsyncClient):
+    response = await async_client.get("/api/v1/catalog/nonexistent")
+    assert response.status_code in (404, 405)
+
+
+@pytest.mark.asyncio
+async def test_catalog_integration_providers_have_fields(async_client: AsyncClient):
+    response = await async_client.get("/api/v1/catalog/integration-providers")
+    data = response.json()
+    for provider in data["data"]:
+        assert "fields" in provider
+        assert isinstance(provider["fields"], list)
+        for field in provider["fields"]:
+            assert "name" in field
+            assert "label" in field
+            assert "type" in field

backend/tests/test_knowledge.py

@@ -0,0 +1,145 @@
+"""Tests for Knowledge Files API — Mission 20."""
+
+import io
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+async def get_auth_headers(client: AsyncClient, email: str = "kb@test.com") -> dict:
+    pwd = "password123"
+    await client.post(
+        "/api/v1/auth/signup",
+        json={"email": email, "password": pwd, "full_name": "KB Tester"},
+    )
+    login_res = await client.post(
+        "/api/v1/auth/login",
+        data={"username": email, "password": pwd},
+        headers={"content-type": "application/x-www-form-urlencoded"},
+    )
+    token = login_res.json()["data"]["access_token"]
+    ws_res = await client.get(
+        "/api/v1/workspaces", headers={"Authorization": f"Bearer {token}"}
+    )
+    ws_id = ws_res.json()["data"][0]["id"]
+    return {"Authorization": f"Bearer {token}", "X-Workspace-ID": ws_id}
+
+
+@pytest.mark.asyncio
+async def test_upload_and_list_knowledge_file(async_client: AsyncClient):
+    """Upload a .txt file and verify it appears in the list."""
+    headers = await get_auth_headers(async_client, "kb_upload@test.com")
+
+    file_content = b"Our pricing starts at $99/month for the basic plan."
+    res = await async_client.post(
+        "/api/v1/knowledge/files",
+        files={"file": ("pricing.txt", io.BytesIO(file_content), "text/plain")},
+        headers=headers,
+    )
+    assert res.status_code == 200
+    body = res.json()
+    assert body["success"] is True
+    assert body["data"]["extracted"] is True
+    assert body["data"]["status"] == "READY"
+
+    # List files
+    list_res = await async_client.get("/api/v1/knowledge/files", headers=headers)
+    assert list_res.status_code == 200
+    files = list_res.json()["data"]
+    assert len(files) >= 1
+    found = [f for f in files if f["filename"] == "pricing.txt"]
+    assert len(found) == 1
+    assert found[0]["status"] == "READY"
+    assert found[0]["extracted"] is True
+
+
+@pytest.mark.asyncio
+async def test_sha256_dedupe_rejects_duplicate(async_client: AsyncClient):
+    """Uploading the same content twice should return an error."""
+    headers = await get_auth_headers(async_client, "kb_dedupe@test.com")
+
+    file_content = b"Unique content for dedup test 12345"
+    # First upload
+    res1 = await async_client.post(
+        "/api/v1/knowledge/files",
+        files={"file": ("doc1.txt", io.BytesIO(file_content), "text/plain")},
+        headers=headers,
+    )
+    assert res1.status_code == 200
+    assert res1.json()["success"] is True
+
+    # Second upload — same content, different filename
+    res2 = await async_client.post(
+        "/api/v1/knowledge/files",
+        files={"file": ("doc2.txt", io.BytesIO(file_content), "text/plain")},
+        headers=headers,
+    )
+    assert res2.status_code == 200
+    body = res2.json()
+    assert body["success"] is False
+    assert "Duplicate" in body["error"]
+
+
+@pytest.mark.asyncio
+async def test_delete_knowledge_file(async_client: AsyncClient):
+    """Upload then delete a file and confirm it's gone."""
+    headers = await get_auth_headers(async_client, "kb_delete@test.com")
+
+    file_content = b"File to be deleted"
+    upload_res = await async_client.post(
+        "/api/v1/knowledge/files",
+        files={"file": ("deleteme.txt", io.BytesIO(file_content), "text/plain")},
+        headers=headers,
+    )
+    file_id = upload_res.json()["data"]["id"]
+
+    # Delete
+    del_res = await async_client.delete(
+        f"/api/v1/knowledge/files/{file_id}", headers=headers
+    )
+    assert del_res.status_code == 200
+    assert del_res.json()["data"]["deleted"] is True
+
+    # Verify gone from list
+    list_res = await async_client.get("/api/v1/knowledge/files", headers=headers)
+    ids = [f["id"] for f in list_res.json()["data"]]
+    assert file_id not in ids
+
+
+@pytest.mark.asyncio
+async def test_download_knowledge_file(async_client: AsyncClient):
+    """Upload a file and download it back."""
+    headers = await get_auth_headers(async_client, "kb_download@test.com")
+
+    file_content = b"Download me!"
+    upload_res = await async_client.post(
+        "/api/v1/knowledge/files",
+        files={"file": ("download.txt", io.BytesIO(file_content), "text/plain")},
+        headers=headers,
+    )
+    file_id = upload_res.json()["data"]["id"]
+
+    # Download
+    dl_res = await async_client.get(
+        f"/api/v1/knowledge/files/{file_id}/download", headers=headers
+    )
+    assert dl_res.status_code == 200
+    assert dl_res.content == file_content
+
+
+@pytest.mark.asyncio
+async def test_upload_unsupported_format_status(async_client: AsyncClient):
+    """Upload a .bin file — should have status READY but no extracted text."""
+    headers = await get_auth_headers(async_client, "kb_bin@test.com")
+
+    res = await async_client.post(
+        "/api/v1/knowledge/files",
+        files={"file": ("data.bin", io.BytesIO(b"\x00\x01\x02"), "application/octet-stream")},
+        headers=headers,
+    )
+    assert res.status_code == 200
+    body = res.json()
+    assert body["success"] is True
+    # Unsupported format → no extraction, but still READY
+    assert body["data"]["extracted"] is False

backend/tests/test_prompt_compiler.py

@@ -0,0 +1,212 @@
+"""Tests for Prompt Compiler Service — Mission 20."""
+
+import pytest
+import pytest_asyncio
+from uuid import uuid4
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.models import (
+    Workspace,
+    PromptConfig,
+    PromptVersion,
+    WorkspaceKnowledgeFile,
+    QualificationConfig,
+)
+from app.services.prompt_compiler import compile_workspace_prompt
+
+
+@pytest_asyncio.fixture
+async def compiler_workspace(db_session: AsyncSession):
+    """Create a workspace with prompt config, knowledge files, and qualification config."""
+    ws = Workspace(id=uuid4(), name="Compiler Test WS")
+    db_session.add(ws)
+    await db_session.flush()
+
+    # Create PromptConfig first (version needs prompt_config_id)
+    config = PromptConfig(
+        id=uuid4(),
+        workspace_id=ws.id,
+        current_version_id=None,  # Will update after version created
+    )
+    db_session.add(config)
+    await db_session.flush()
+
+    # Prompt version
+    version = PromptVersion(
+        id=uuid4(),
+        prompt_config_id=config.id,
+        version_number=1,
+        system_prompt_text="You are a helpful sales assistant.",
+        structured_data={},
+        compiled_system_instruction="You are a helpful sales assistant.",
+        business_profile_json={"company": "Acme Corp", "industry": "Tech"},
+        guardrails_json={"never_do": ["make up pricing"]},
+        model="gemini-pro",
+        temperature=0.8,
+        max_tokens_per_execution=500,
+    )
+    db_session.add(version)
+    await db_session.flush()
+
+    # Update config to point to this version
+    config.current_version_id = version.id
+
+    # Knowledge files
+    kf1 = WorkspaceKnowledgeFile(
+        id=uuid4(),
+        workspace_id=ws.id,
+        filename="pricing.txt",
+        mime_type="text/plain",
+        size_bytes=100,
+        storage_path="/tmp/fake.txt",
+        extracted_text="Our basic plan costs $99/month.",
+        status="READY",
+        sha256_hash="abc123",
+    )
+    kf2 = WorkspaceKnowledgeFile(
+        id=uuid4(),
+        workspace_id=ws.id,
+        filename="faq.txt",
+        mime_type="text/plain",
+        size_bytes=50,
+        storage_path="/tmp/fake2.txt",
+        extracted_text="We support WhatsApp and email.",
+        status="READY",
+        sha256_hash="def456",
+    )
+    kf_failed = WorkspaceKnowledgeFile(
+        id=uuid4(),
+        workspace_id=ws.id,
+        filename="broken.pdf",
+        mime_type="application/pdf",
+        size_bytes=200,
+        storage_path="/tmp/fake3.pdf",
+        extracted_text=None,
+        status="FAILED",
+        sha256_hash="ghi789",
+    )
+    db_session.add_all([kf1, kf2, kf_failed])
+
+    # Qualification config
+    qual = QualificationConfig(
+        id=uuid4(),
+        workspace_id=ws.id,
+        version=1,
+        qualification_questions=[
+            {"label": "Full Name", "enabled": True, "order": 0},
+            {"label": "Budget Range", "enabled": True, "order": 1},
+            {"label": "Disabled Q", "enabled": False, "order": 2},
+        ],
+        qualification_statuses=[
+            {"label": "New", "color": "#94a3b8", "enabled": True},
+        ],
+    )
+    db_session.add(qual)
+    await db_session.flush()
+
+    return ws
+
+
+@pytest.mark.asyncio
+async def test_compiler_includes_all_sections(db_session: AsyncSession, compiler_workspace):
+    """Compiler output includes prompt text, business profile, guardrails, files, qualification."""
+    ws = compiler_workspace
+    compiled = await compile_workspace_prompt(ws.id, db_session)
+
+    si = compiled.system_instruction
+
+    # Core prompt
+    assert "You are a helpful sales assistant." in si
+
+    # Business profile
+    assert "=== BUSINESS PROFILE ===" in si
+    assert "Acme Corp" in si
+
+    # Guardrails
+    assert "=== GUARDRAILS ===" in si
+    assert "make up pricing" in si
+
+    # Knowledge files (only READY with extracted_text)
+    assert "=== KNOWLEDGE BASE (FILES) ===" in si
+    assert "pricing.txt" in si
+    assert "$99/month" in si
+    assert "faq.txt" in si
+    assert "WhatsApp" in si
+    # FAILED file should NOT appear
+    assert "broken.pdf" not in si
+
+    # Qualification (only enabled questions)
+    assert "=== LEAD QUALIFICATION ===" in si
+    assert "Full Name" in si
+    assert "Budget Range" in si
+    assert "Disabled Q" not in si
+
+    # Metadata
+    assert compiled.knowledge_file_count == 2
+    assert compiled.qualification_question_count == 2
+    assert compiled.temperature == 0.8
+    assert compiled.max_tokens == 500
+
+
+@pytest.mark.asyncio
+async def test_compiler_with_step_config(db_session: AsyncSession, compiler_workspace):
+    """Compiler appends step-level config when provided."""
+    ws = compiler_workspace
+    step_config = {
+        "goal": "Schedule a demo call",
+        "tasks": ["Ask for preferred date", "Confirm timezone"],
+        "extra_instructions": "Be concise and direct.",
+    }
+    compiled = await compile_workspace_prompt(
+        ws.id, db_session, step_config=step_config
+    )
+
+    si = compiled.system_instruction
+    assert "=== STEP GOAL ===" in si
+    assert "Schedule a demo call" in si
+    assert "=== TASKS ===" in si
+    assert "Ask for preferred date" in si
+    assert "Confirm timezone" in si
+    assert "=== STEP INSTRUCTIONS ===" in si
+    assert "Be concise and direct." in si
+
+
+@pytest.mark.asyncio
+async def test_compiler_without_files(db_session: AsyncSession, compiler_workspace):
+    """With include_files=False, knowledge base section is omitted."""
+    ws = compiler_workspace
+    compiled = await compile_workspace_prompt(
+        ws.id, db_session, include_files=False
+    )
+
+    si = compiled.system_instruction
+    assert "=== KNOWLEDGE BASE (FILES) ===" not in si
+    assert compiled.knowledge_file_count == 0
+    # Other sections still present
+    assert "=== BUSINESS PROFILE ===" in si
+
+
+@pytest.mark.asyncio
+async def test_compiler_without_qualification(db_session: AsyncSession, compiler_workspace):
+    """With include_qualification=False, qualification section is omitted."""
+    ws = compiler_workspace
+    compiled = await compile_workspace_prompt(
+        ws.id, db_session, include_qualification=False
+    )
+
+    si = compiled.system_instruction
+    assert "=== LEAD QUALIFICATION ===" not in si
+    assert compiled.qualification_question_count == 0
+
+
+@pytest.mark.asyncio
+async def test_compiler_no_config_returns_default(db_session: AsyncSession):
+    """Workspace with no PromptConfig returns a sensible default."""
+    ws = Workspace(id=uuid4(), name="Empty WS")
+    db_session.add(ws)
+    await db_session.flush()
+
+    compiled = await compile_workspace_prompt(ws.id, db_session)
+    assert compiled.system_instruction == "You are a helpful assistant."
+    assert compiled.temperature == 0.7
+    assert compiled.max_tokens == 1000

backend/tests/test_qualification.py

@@ -0,0 +1,106 @@
+"""Tests for Qualification Config API — Mission 20."""
+
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient
+
+
+async def get_auth_headers(client: AsyncClient, email: str = "qual@test.com") -> dict:
+    pwd = "password123"
+    await client.post(
+        "/api/v1/auth/signup",
+        json={"email": email, "password": pwd, "full_name": "Qual Tester"},
+    )
+    login_res = await client.post(
+        "/api/v1/auth/login",
+        data={"username": email, "password": pwd},
+        headers={"content-type": "application/x-www-form-urlencoded"},
+    )
+    token = login_res.json()["data"]["access_token"]
+    ws_res = await client.get(
+        "/api/v1/workspaces", headers={"Authorization": f"Bearer {token}"}
+    )
+    ws_id = ws_res.json()["data"][0]["id"]
+    return {"Authorization": f"Bearer {token}", "X-Workspace-ID": ws_id}
+
+
+@pytest.mark.asyncio
+async def test_get_qualification_config_lazy_creates(async_client: AsyncClient):
+    """First GET creates a default config with standard questions and statuses."""
+    headers = await get_auth_headers(async_client, "qual_lazy@test.com")
+
+    res = await async_client.get("/api/v1/qualification-config", headers=headers)
+    assert res.status_code == 200
+    body = res.json()
+    assert body["success"] is True
+
+    data = body["data"]
+    assert data["version"] == 1
+
+    # Check default questions
+    questions = data["qualification_questions"]
+    assert len(questions) >= 4  # At least 4 default questions
+    labels = [q["label"] for q in questions]
+    assert "Full Name" in labels
+    assert "Company Email" in labels
+
+    # Check default statuses
+    statuses = data["qualification_statuses"]
+    assert len(statuses) >= 3
+    status_labels = [s["label"] for s in statuses]
+    assert "Qualified" in status_labels
+    assert "Unqualified" in status_labels
+
+
+@pytest.mark.asyncio
+async def test_update_qualification_config_increments_version(async_client: AsyncClient):
+    """POST updates the config and increments the version number."""
+    headers = await get_auth_headers(async_client, "qual_update@test.com")
+
+    # First, trigger lazy creation
+    await async_client.get("/api/v1/qualification-config", headers=headers)
+
+    # Update with custom questions
+    custom_questions = [
+        {"label": "Company Size", "enabled": True, "order": 0},
+        {"label": "Annual Revenue", "enabled": True, "order": 1},
+    ]
+    custom_statuses = [
+        {"label": "Hot Lead", "color": "#ef4444", "enabled": True},
+        {"label": "Cold Lead", "color": "#94a3b8", "enabled": True},
+    ]
+
+    res = await async_client.post(
+        "/api/v1/qualification-config",
+        json={
+            "qualification_questions": custom_questions,
+            "qualification_statuses": custom_statuses,
+        },
+        headers=headers,
+    )
+    assert res.status_code == 200
+    body = res.json()
+    assert body["success"] is True
+    assert body["data"]["version"] == 2
+
+    # GET again to confirm persistence
+    get_res = await async_client.get("/api/v1/qualification-config", headers=headers)
+    data = get_res.json()["data"]
+    assert data["version"] == 2
+    assert len(data["qualification_questions"]) == 2
+    assert data["qualification_questions"][0]["label"] == "Company Size"
+    assert len(data["qualification_statuses"]) == 2
+
+
+@pytest.mark.asyncio
+async def test_qualification_idempotent_get(async_client: AsyncClient):
+    """Multiple GETs return the same config without creating duplicates."""
+    headers = await get_auth_headers(async_client, "qual_idempotent@test.com")
+
+    res1 = await async_client.get("/api/v1/qualification-config", headers=headers)
+    res2 = await async_client.get("/api/v1/qualification-config", headers=headers)
+
+    assert res1.json()["data"]["version"] == res2.json()["data"]["version"]
+    assert len(res1.json()["data"]["qualification_questions"]) == len(
+        res2.json()["data"]["qualification_questions"]
+    )

docs/missions/mission_19.md

@@ -0,0 +1,75 @@
+# Mission 19 — Data Flow Integrity & Catalog Standardization Gate
+
+## Summary
+
+Mission 19 introduces a backend catalog registry and API layer that serves as the single source of truth for all enum-based reference data in LeadPilot V2. The frontend was swept to replace 11+ hardcoded arrays with a `useCatalog()` hook that fetches from the new `/api/v1/catalog/*` endpoints.
+
+**Result:** Adding a new integration provider, automation step type, or status enum now requires only a backend change to `catalog_registry.py` — the frontend picks it up automatically.
+
+## Catalog Endpoints
+
+| # | Endpoint | Source | Auth |
+|---|---|---|---|
+| 1 | `GET /api/v1/catalog/plans` | DB: `Plan` + `PlanEntitlement` | None |
+| 2 | `GET /api/v1/catalog/tiers` | Alias for /plans | None |
+| 3 | `GET /api/v1/catalog/modules` | DB: `SystemModuleConfig` + registry labels | None |
+| 4 | `GET /api/v1/catalog/workspace-roles` | Registry | None |
+| 5 | `GET /api/v1/catalog/admin-roles` | Registry | None |
+| 6 | `GET /api/v1/catalog/integration-providers` | Registry | None |
+| 7 | `GET /api/v1/catalog/automation-node-types` | Registry | None |
+| 8 | `GET /api/v1/catalog/automation-trigger-types` | Registry | None |
+| 9 | `GET /api/v1/catalog/conversation-statuses` | Registry | None |
+| 10 | `GET /api/v1/catalog/message-delivery-statuses` | Registry | None |
+
+All endpoints return `ResponseEnvelope` with `Cache-Control: public, max-age=60`. No authentication required — these are public reference data.
+
+## Backend Changes
+
+### New Files
+- **`backend/app/core/catalog_registry.py`** — Canonical enum registry. Exports typed lists (`INTEGRATION_PROVIDERS`, `AUTOMATION_NODE_TYPES`, etc.) and validation sets (`VALID_PROVIDERS`, `VALID_NODE_TYPES`, `VALID_TRIGGER_TYPES`).
+- **`backend/app/api/v1/catalog.py`** — 10 GET-only endpoints using factory pattern for static endpoints.
+- **`backend/tests/test_catalog.py`** — 12 test cases covering all endpoints, structure validation, cache headers, and 404 handling.
+
+### Modified Files
+- **`backend/main.py`** — Registered catalog router, added `/catalog` to maintenance mode exempt prefixes.
+- **`backend/app/api/v1/integrations.py`** — Replaced hardcoded `["zoho", "whatsapp", "meta"]` with `VALID_PROVIDERS` from registry.
+- **`backend/app/api/v1/automations.py`** — Added server-side validation of step types and trigger types against registry.
+- **`backend/tests/test_automation.py`** — Updated test trigger type from `WEBHOOK` to `MESSAGE_INBOUND` (now validated).
+
+## Frontend Changes
+
+### New Files
+- **`frontend/src/lib/catalog.ts`** — `useCatalog<T>(key)` hook with 60s in-memory cache, `catalogLabel()` helper.
+
+### Hardcoded Sweep Report
+
+| Page | What was removed | What replaced it |
+|---|---|---|
+| `/integrations` | `PROVIDER_METADATA` object (name, description, fields) | `useCatalog("integration-providers")` |
+| `/inbox` | Hardcoded `<option>` status elements + switch-case labels | `useCatalog("conversation-statuses")` + `catalogLabel()` |
+| `/automations/new` | Hardcoded trigger cards + step type buttons | `useCatalog("automation-node-types")` + `useCatalog("automation-trigger-types")` |
+| `/admin/dispatch` | `STATUS_OPTIONS` array | `useCatalog("message-delivery-statuses")` |
+| `/dispatch` | Hardcoded status labels in `getStatusBadge()` | `catalogLabel(deliveryStatuses, ...)` |
+| `/plans` (marketing) | Hardcoded waitlist `<select>` options | `useCatalog<PlanCatalogEntry[]>("plans")` |
+| `/admin/email-logs` | _(kept as-is)_ | Added traceability comment to registry |
+| `/lib/admin-api.ts` | _(kept as-is)_ | Added deprecation comment on `MODULE_LABELS` |
+
+### Intentionally Unchanged
+- **Marketing tier cards** (`/plans` page) — Rich marketing copy (features, pricing, CTAs) is a presentation concern, not catalog data.
+- **Admin email log filters** — Admin-internal statuses, different enum from message delivery. Kept as local constants with traceability comment.
+- **Team page** — Static placeholder with no backend wiring.
+
+## Test Results
+
+```
+Backend:  105 passed, 0 failed (16.60s)
+Frontend: npm run build — 48 pages, 0 errors
+```
+
+## Key Decisions
+
+1. **No auth on catalog** — Public reference data, safe with 60s cache header.
+2. **No DB migration** — Reads existing Plan/Module tables + in-memory registry.
+3. **Factory pattern** — 7 identical static handlers collapsed to 1 factory function.
+4. **Icons stay frontend-side** — `icon_hint` in registry maps to Lucide components via local mapping.
+5. **Maintenance mode exempt** — Catalog is reference data, available even during maintenance.

docs/missions/mission_19_data_flow_map.md

@@ -0,0 +1,115 @@
+# Mission 19 — Data Flow Map
+
+Maps every dynamic UI element to its API endpoint, service layer, and database source.
+
+---
+
+## Plans & Billing
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/plans` waitlist dropdown | `WaitlistForm` | `GET /api/v1/catalog/plans` | catalog router | `plan` + `plan_entitlement` |
+| `/admin/plans` list | Admin Plans page | `GET /api/v1/admin/plans` | admin router | `plan` |
+| `/admin/plans/:id` detail | Plan detail page | `GET /api/v1/admin/plans/:id` | admin router | `plan` + `plan_entitlement` |
+| `/admin/workspaces/:id` plan badge | Workspace detail | `GET /api/v1/admin/workspaces/:id/plan` | admin router | `workspace_plan_assignment` |
+
+## Modules
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/admin/modules` toggle list | Modules page | `GET /api/v1/admin/modules` | admin router | `system_module_config` |
+| `/admin/workspaces/:id` module overrides | Workspace detail | `GET /api/v1/admin/workspaces/:id/modules` | admin router | `workspace_module_override` |
+| Catalog reference | Any page via `useCatalog` | `GET /api/v1/catalog/modules` | catalog router | `system_module_config` + registry labels |
+
+## Roles
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/team` role badges | Team page (placeholder) | `GET /api/v1/catalog/workspace-roles` | catalog router | Registry (enum) |
+| `/admin/agencies` role display | Agency detail | `GET /api/v1/catalog/admin-roles` | catalog router | Registry (enum) |
+| Member invite role picker | Workspace settings | `GET /api/v1/catalog/workspace-roles` | catalog router | Registry (enum) |
+
+## Integrations
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/integrations` provider cards | Integrations page | `GET /api/v1/catalog/integration-providers` | catalog router | Registry |
+| `/integrations` connected list | Integrations page | `GET /api/v1/integrations` | integrations router | `integration` |
+| `/integrations` connect modal fields | Dynamic form | `GET /api/v1/catalog/integration-providers` | catalog router | Registry (`.fields`) |
+| `/integrations` provider validation | Backend | `POST /api/v1/integrations/:provider/connect` | integrations router | `VALID_PROVIDERS` set |
+
+## Automations
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/automations/new` trigger cards | Builder wizard | `GET /api/v1/catalog/automation-trigger-types` | catalog router | Registry |
+| `/automations/new` step type buttons | Builder wizard | `GET /api/v1/catalog/automation-node-types` | catalog router | Registry |
+| `/automations/new` step labels | Review panel | `GET /api/v1/catalog/automation-node-types` | catalog router | Registry |
+| `/automations` flow list | Automations page | `GET /api/v1/automations` | automations router | `flow` |
+| Backend step validation | `create_from_builder` | — | `VALID_NODE_TYPES` set | Registry |
+| Backend trigger validation | `create_from_builder` | — | `VALID_TRIGGER_TYPES` set | Registry |
+
+## Inbox / Conversations
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/inbox` status filter dropdown | Inbox page | `GET /api/v1/catalog/conversation-statuses` | catalog router | Registry (enum) |
+| `/inbox` status badges | `StatusBadge` component | `GET /api/v1/catalog/conversation-statuses` | catalog router | Registry (enum) |
+| `/inbox` conversation list | Inbox page | `GET /api/v1/inbox/conversations` | inbox router | `conversation` |
+| `/inbox` messages | Message panel | `GET /api/v1/inbox/conversations/:id/messages` | inbox router | `message` |
+
+## Dispatch / Message Delivery
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/admin/dispatch` status filter | Admin dispatch page | `GET /api/v1/catalog/message-delivery-statuses` | catalog router | Registry (enum) |
+| `/admin/dispatch` message list | Admin dispatch page | `GET /api/v1/admin/dispatch` | admin router | `outbound_message` |
+| `/dispatch` status badges | Dashboard dispatch | `GET /api/v1/catalog/message-delivery-statuses` | catalog router | Registry (enum) |
+| `/dispatch` message queue | Dashboard dispatch | `GET /api/v1/dispatch/queue` | dispatch router | `outbound_message` |
+
+## Email Engine
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/admin/email-logs` status filter | Email logs page | Local constants (registry-traced) | — | — |
+| `/admin/email-logs` type filter | Email logs page | Local constants (registry-traced) | — | — |
+| `/admin/email-logs` log list | Email logs page | `GET /api/v1/admin/email-logs` | admin router | `email_outbox` |
+| `/admin/email-logs` retry action | Retry button | `POST /api/v1/admin/email-logs/:id/retry` | admin router | `email_outbox` |
+
+## Analytics & Dashboard
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/dashboard` stats cards | Dashboard page | `GET /api/v1/analytics/summary` | analytics router | Aggregated queries |
+| `/dashboard` time series | Charts | `GET /api/v1/analytics/time-series` | analytics router | Aggregated queries |
+
+## Audit & Runtime Events
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/admin/audit-log` list | Audit log page | `GET /api/v1/admin/audit-log` | admin router | `audit_log` |
+| `/admin/audit-log` detail | Detail drawer | `GET /api/v1/admin/audit-log/:id` | admin router | `audit_log` |
+| `/admin/runtime-events` list | Runtime events page | `GET /api/v1/admin/runtime-events` | admin router | `runtime_event` |
+| `/admin/runtime-events` detail | Detail drawer | `GET /api/v1/admin/runtime-events/:id` | admin router | `runtime_event` |
+
+## Settings
+
+| UI Location | Component | API Endpoint | Service | DB Table |
+|---|---|---|---|---|
+| `/settings` workspace name | Settings page | `GET /api/v1/workspaces/current` | workspaces router | `workspace` |
+| `/admin/system-settings` | System settings | `GET /api/v1/admin/system-settings` | admin router | `system_setting` |
+
+---
+
+## Registry → Validation Cross-Reference
+
+| Registry Constant | Used By (Validation) | Used By (Catalog Endpoint) |
+|---|---|---|
+| `VALID_PROVIDERS` | `integrations.py` line 46 | `/catalog/integration-providers` |
+| `VALID_NODE_TYPES` | `automations.py` line 56 | `/catalog/automation-node-types` |
+| `VALID_TRIGGER_TYPES` | `automations.py` line 58 | `/catalog/automation-trigger-types` |
+| `CONVERSATION_STATUSES` | — (enum-enforced in DB) | `/catalog/conversation-statuses` |
+| `MESSAGE_DELIVERY_STATUSES` | — (enum-enforced in DB) | `/catalog/message-delivery-statuses` |
+| `WORKSPACE_ROLES` | — (enum-enforced in DB) | `/catalog/workspace-roles` |
+| `AGENCY_ROLES` | — (enum-enforced in DB) | `/catalog/admin-roles` |
+| `MODULE_LABELS` | — (display only) | `/catalog/modules` |

docs/missions/mission_20.md

@@ -0,0 +1,78 @@
+# Mission 20 — Prompt Studio Knowledge Base v2 + Dynamic Lead Qualification Builder
+
+## Summary
+
+Mission 20 eliminates the three critical gaps in LeadPilot's AI pipeline:
+
+1. **Knowledge files now flow into AI context** — uploaded documents (TXT, CSV, PDF) are extracted and injected into every AI conversation via the new prompt compiler.
+2. **Single source of truth for prompt compilation** — `prompt_compiler.py` replaces two divergent context-assembly paths (Test Chat vs Runtime) with one canonical pipeline.
+3. **Automation AI steps now use goal/tasks/extra_instructions** — the runtime passes step-level config through the compiler, so AI_REPLY nodes finally execute under the configured goals.
+4. **Dynamic lead qualification** — workspace-level configurable questions + statuses with admin defaults/override.
+
+## What Changed
+
+### Backend
+
+| File | Change |
+|---|---|
+| `app/models/models.py` | Added `sha256_hash` + `status` to `WorkspaceKnowledgeFile`; new `QualificationConfig` model |
+| `alembic/versions/f6g7h8i9j0k1_...py` | Migration: 2 new columns + 1 new table |
+| `app/api/v1/knowledge.py` | SHA256 dedupe, PDF extraction (PyMuPDF), workspace-isolated storage, download endpoint |
+| `app/services/prompt_compiler.py` | **NEW** — single source of truth context compiler |
+| `app/api/v1/test_chat.py` | Uses compiler instead of inline assembly |
+| `app/domain/runtime.py` | Uses compiler with `step_config` for AI_REPLY |
+| `app/api/v1/qualification.py` | **NEW** — GET/POST qualification config (lazy-create pattern) |
+| `app/api/v1/admin.py` | 3 new endpoints: qualification defaults, workspace reset |
+| `main.py` | Registered qualification router |
+
+### Frontend
+
+| File | Change |
+|---|---|
+| `prompt-studio/page.tsx` | 4th "Lead Qualification" tab with questions/statuses CRUD; Knowledge tab polished with status badges + download buttons |
+
+### Tests
+
+| File | Tests |
+|---|---|
+| `tests/test_knowledge.py` | 6 tests — upload, list, dedupe, delete, download, unsupported format |
+| `tests/test_prompt_compiler.py` | 5 tests — all sections, step_config, exclude files, exclude qualification, no-config default |
+| `tests/test_qualification.py` | 3 tests — lazy create, update + version increment, idempotent GET |
+
+**Total: 118 tests passing (was 57 pre-mission)**
+
+## Architecture: Prompt Compiler
+
+```
+compile_workspace_prompt(workspace_id, db, *, include_files, include_qualification, step_config)
+    │
+    ├── 1. system_prompt_text (from PromptVersion)
+    ├── 2. === BUSINESS PROFILE === (business_profile_json)
+    ├── 3. === GUARDRAILS === (guardrails_json)
+    ├── 4. === KNOWLEDGE BASE (FILES) === (READY files, 4000 char cap each)
+    ├── 5. === LEAD QUALIFICATION === (enabled questions sorted by order)
+    └── 6. === STEP GOAL / TASKS / STEP INSTRUCTIONS === (if step_config provided)
+
+Returns: CompiledPrompt(system_instruction, temperature, max_tokens, metadata)
+```
+
+Both Test Chat and Runtime AI_REPLY call this single function.
+
+## New API Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/api/v1/qualification-config` | Get or lazy-create workspace qualification config |
+| POST | `/api/v1/qualification-config` | Update questions + statuses, version auto-increments |
+| GET | `/api/v1/knowledge/files/{id}/download` | Download knowledge file |
+| GET | `/api/v1/admin/qualification-defaults` | Admin: get global defaults |
+| PUT | `/api/v1/admin/qualification-defaults` | Admin: set global defaults |
+| POST | `/api/v1/admin/workspaces/{id}/qualification-reset` | Admin: reset workspace to defaults |
+
+## How to Test
+
+1. **Backend tests**: `cd backend && rm -f test.db && python3 -m pytest tests/ -v`
+2. **Frontend build**: `cd frontend && npm run build`
+3. **Manual — Knowledge files**: Upload .txt in Prompt Studio Knowledge tab → open Test Chat → AI should reference file content
+4. **Manual — Automation AI steps**: Create automation with AI_REPLY step goal "Schedule a demo" → trigger → AI should mention scheduling
+5. **Manual — Qualification**: Edit questions in Lead Qualification tab → save → Test Chat AI should collect those specific details

docs/missions/mission_20_baseline.md

@@ -0,0 +1,53 @@
+# Mission 20 — Pre-Mission Baseline
+
+Captured before any Mission 20 changes.
+
+## State of AI Context Compilation
+
+### Test Chat (`test_chat.py:101-116`)
+```python
+# Fetched PromptConfig + PromptVersion manually
+# Built system instruction as: system_prompt_text + json.dumps(business_profile_json) + json.dumps(guardrails_json)
+# Knowledge files: NOT included
+# Qualification: NOT included
+# Step config: N/A
+```
+
+### Runtime AI_REPLY (`runtime.py:285-333`)
+```python
+# Built system instruction as: system_prompt_text + "Business Context:" + business_profile_json
+# Guardrails: NOT included
+# Knowledge files: NOT included
+# Qualification: NOT included
+# Step config (goal/tasks/extra_instructions): NOT read despite being stored in definition_json
+```
+
+**Result**: Two divergent prompts from the same config. Knowledge files uploaded but never used. Automation goals collected but ignored.
+
+## Knowledge Files
+
+- `WorkspaceKnowledgeFile` model existed with `extracted_text` field
+- Upload endpoint extracted text for .txt, .md, .json, .csv
+- No PDF support
+- No SHA256 dedupe
+- No download endpoint
+- No status tracking (READY/FAILED)
+- Storage path: flat `storage/knowledge/{uuid}{ext}` (not workspace-isolated)
+
+## Qualification
+
+- Hardcoded checkboxes in Prompt Studio editor tab: "Full Name", "Company Email", "Budget Range", etc.
+- Stored as `required_details[]` in structured_data form
+- No `QualificationConfig` model
+- No admin defaults/override
+- No qualification statuses
+
+## Prompt Studio Frontend
+
+- 3 tabs: Assistant Configuration, Knowledge Base, Version History
+- Knowledge tab: upload/delete only, no status indicators
+- No qualification management tab
+
+## Test Count
+
+57 tests across 13 files, all passing.

frontend/src/app/(admin)/admin/dispatch/page.tsx

@@ -5,10 +5,10 @@ import { adminApi } from "@/lib/admin-api";
 import { Send, Loader2, Info, RefreshCw, RotateCcw, XCircle } from "lucide-react";
 import { toast } from "sonner";
 import { cn } from "@/lib/utils";
-
-const STATUS_OPTIONS = ["", "PENDING", "SENDING", "SENT", "FAILED"];
+import { useCatalog } from "@/lib/catalog";
 
 export default function AdminDispatchPage() {
+    const { data: deliveryStatuses } = useCatalog("message-delivery-statuses");
     const [items, setItems] = useState<any[]>([]);
     const [total, setTotal] = useState(0);
     const [loading, setLoading] = useState(true);
@@ -82,8 +82,9 @@ export default function AdminDispatchPage() {
                     onChange={(e) => setStatus(e.target.value)}
                     className="bg-white/5 border border-white/10 text-slate-300 rounded-lg px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-amber-500/50"
                 >
-                    {STATUS_OPTIONS.map((s) => (
-                        <option key={s} value={s} className="bg-slate-900">{s || "All Statuses"}</option>
+                    <option value="" className="bg-slate-900">All Statuses</option>
+                    {deliveryStatuses?.map((s) => (
+                        <option key={s.key} value={s.key.toUpperCase()} className="bg-slate-900">{s.label}</option>
                     ))}
                 </select>
             </div>

frontend/src/app/(admin)/admin/email-logs/page.tsx

@@ -6,6 +6,7 @@ import { Mail, Loader2, Info, RefreshCw, RotateCcw } from "lucide-react";
 import { toast } from "sonner";
 import { cn } from "@/lib/utils";
 
+// Source: backend/app/core/catalog_registry.py — EMAIL_OUTBOX_STATUSES / EMAIL_TYPES
 const STATUS_OPTIONS = ["", "PENDING", "SENT", "FAILED", "PROCESSING"];
 const EMAIL_TYPE_OPTIONS = ["", "welcome", "verify_email", "password_reset", "invite"];
 

frontend/src/app/(dashboard)/automations/new/page.tsx

@@ -21,9 +21,25 @@ import {
 } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { apiClient } from "@/lib/api";
+import { useCatalog, catalogLabel, type CatalogEntry } from "@/lib/catalog";
 import Link from "next/link";
 import { useRouter } from "next/navigation";
 
+// Icon mapping for catalog icon_hint → Lucide component
+const NODE_TYPE_ICONS: Record<string, any> = {
+    bot: Bot,
+    send: Send,
+    user: UserRound,
+    tag: TagIcon,
+};
+
+// Trigger presentation — combines catalog trigger types with platform-specific UI
+const TRIGGER_CARDS = [
+    { id: "whatsapp", triggerKey: "MESSAGE_INBOUND", platform: "whatsapp", name: "WhatsApp Message", icon: MessageSquare, color: "text-green-600", bg: "bg-green-50" },
+    { id: "meta-msg", triggerKey: "MESSAGE_INBOUND", platform: "meta", name: "Messenger/Instagram", icon: Facebook, color: "text-blue-600", bg: "bg-blue-50" },
+    { id: "leadgen", triggerKey: "LEAD_AD_SUBMIT", platform: "meta", name: "Meta Lead Ads", icon: Zap, color: "text-orange-600", bg: "bg-orange-50" },
+];
+
 type StepType = "AI_REPLY" | "SEND_MESSAGE" | "HUMAN_HANDOVER" | "TAG_CONTACT";
 
 interface Step {
@@ -34,6 +50,7 @@ interface Step {
 
 export default function NewAutomationPage() {
     const router = useRouter();
+    const { data: nodeTypes } = useCatalog("automation-node-types");
     const [currentStep, setCurrentStep] = useState(1);
     const [isSubmitting, setIsSubmitting] = useState(false);
 
@@ -185,17 +202,13 @@ export default function NewAutomationPage() {
                         </div>
 
                         <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-                            {[
-                                { id: "whatsapp", name: "WhatsApp Message", type: "MESSAGE_INBOUND", icon: MessageSquare, color: "text-green-600", bg: "bg-green-50" },
-                                { id: "meta-msg", name: "Messenger/Instagram", type: "MESSAGE_INBOUND", icon: Facebook, color: "text-blue-600", bg: "bg-blue-50" },
-                                { id: "leadgen", name: "Meta Lead Ads", type: "LEAD_AD_SUBMIT", icon: Zap, color: "text-orange-600", bg: "bg-orange-50" }
-                            ].map((t) => (
+                            {TRIGGER_CARDS.map((t) => (
                                 <button
                                     key={t.id}
-                                    onClick={() => setTrigger({ ...trigger, type: t.type, platform: t.id === "whatsapp" ? "whatsapp" : "meta" })}
+                                    onClick={() => setTrigger({ ...trigger, type: t.triggerKey, platform: t.platform })}
                                     className={cn(
                                         "flex items-start gap-4 p-5 rounded-2xl border transition-all text-left group hover:scale-[1.02]",
-                                        (trigger.type === t.type && (t.id === "whatsapp" ? trigger.platform === "whatsapp" : trigger.platform === "meta"))
+                                        (trigger.type === t.triggerKey && trigger.platform === t.platform)
                                             ? "border-teal-500 bg-teal-50/50 ring-2 ring-teal-500/10"
                                             : "border-border bg-white hover:border-teal-200"
                                     )}
@@ -226,21 +239,19 @@ export default function NewAutomationPage() {
                                     Add Step
                                 </button>
                                 <div className="absolute right-0 top-full mt-2 w-56 bg-white border border-border shadow-xl rounded-xl p-2 opacity-0 invisible group-hover:opacity-100 group-hover:visible transition-all z-20">
-                                    {[
-                                        { type: "AI_REPLY", name: "AI Reply", icon: Bot },
-                                        { type: "SEND_MESSAGE", name: "Send Message", icon: Send },
-                                        { type: "HUMAN_HANDOVER", name: "Human Handover", icon: UserRound },
-                                        { type: "TAG_CONTACT", name: "Tag Contact", icon: TagIcon }
-                                    ].map(action => (
-                                        <button
-                                            key={action.type}
-                                            onClick={() => addStep(action.type as StepType)}
-                                            className="w-full flex items-center gap-3 p-2.5 hover:bg-teal-50 hover:text-teal-600 rounded-lg text-sm font-medium transition-colors"
-                                        >
-                                            <action.icon className="w-4 h-4" />
-                                            {action.name}
-                                        </button>
-                                    ))}
+                                    {(nodeTypes || []).map((nt) => {
+                                        const Icon = NODE_TYPE_ICONS[nt.icon_hint] || Zap;
+                                        return (
+                                            <button
+                                                key={nt.key}
+                                                onClick={() => addStep(nt.key as StepType)}
+                                                className="w-full flex items-center gap-3 p-2.5 hover:bg-teal-50 hover:text-teal-600 rounded-lg text-sm font-medium transition-colors"
+                                            >
+                                                <Icon className="w-4 h-4" />
+                                                {nt.label}
+                                            </button>
+                                        );
+                                    })}
                                 </div>
                             </div>
                         </div>
@@ -265,11 +276,12 @@ export default function NewAutomationPage() {
                                                 {index + 1}
                                             </span>
                                             <div className="flex items-center gap-2 font-bold text-slate-700">
-                                                {step.type === "AI_REPLY" && <Bot className="w-4 h-4 text-teal-600" />}
-                                                {step.type === "SEND_MESSAGE" && <Send className="w-4 h-4 text-teal-600" />}
-                                                {step.type === "HUMAN_HANDOVER" && <UserRound className="w-4 h-4 text-teal-600" />}
-                                                {step.type === "TAG_CONTACT" && <TagIcon className="w-4 h-4 text-teal-600" />}
-                                                {step.type.replace("_", " ")}
+                                                {(() => {
+                                                    const nt = nodeTypes?.find(n => n.key === step.type);
+                                                    const Icon = nt ? (NODE_TYPE_ICONS[nt.icon_hint] || Zap) : Zap;
+                                                    return <Icon className="w-4 h-4 text-teal-600" />;
+                                                })()}
+                                                {catalogLabel(nodeTypes, step.type, step.type.replace("_", " "))}
                                             </div>
                                         </div>
 
@@ -407,7 +419,7 @@ export default function NewAutomationPage() {
                                         {steps.map((s, i) => (
                                             <div key={s.id} className="text-sm flex items-center gap-3 text-slate-600 bg-slate-50 p-3 rounded-xl border border-border/50">
                                                 <span className="w-5 h-5 bg-white border border-border text-[10px] flex items-center justify-center rounded-full font-bold">{i + 1}</span>
-                                                {s.type.replace("_", " ")}
+                                                {catalogLabel(nodeTypes, s.type, s.type.replace("_", " "))}
                                             </div>
                                         ))}
                                     </div>

frontend/src/app/(dashboard)/dispatch/page.tsx

@@ -2,6 +2,7 @@
 
 import { useEffect, useState } from "react";
 import { apiClient } from "@/lib/api";
+import { useCatalog, catalogLabel } from "@/lib/catalog";
 import {
     RefreshCcw,
     Play,
@@ -25,6 +26,7 @@ interface OutboundMessage {
 }
 
 export default function DispatchPage() {
+    const { data: deliveryStatuses } = useCatalog("message-delivery-statuses");
     const [messages, setMessages] = useState<OutboundMessage[]>([]);
     const [loading, setLoading] = useState(true);
     const [running, setRunning] = useState(false);
@@ -66,29 +68,30 @@ export default function DispatchPage() {
     };
 
     const getStatusBadge = (status: string) => {
+        const label = catalogLabel(deliveryStatuses, status, status);
         switch (status) {
             case "sent":
                 return (
                     <span className="inline-flex items-center gap-1 px-2.5 py-0.5 rounded-full text-xs font-medium bg-emerald-100 text-emerald-800">
-                        <CheckCircle2 className="w-3 h-3" /> Sent
+                        <CheckCircle2 className="w-3 h-3" /> {label}
                     </span>
                 );
             case "failed":
                 return (
                     <span className="inline-flex items-center gap-1 px-2.5 py-0.5 rounded-full text-xs font-medium bg-red-100 text-red-800">
-                        <XCircle className="w-3 h-3" /> Failed
+                        <XCircle className="w-3 h-3" /> {label}
                     </span>
                 );
             case "sending":
                 return (
                     <span className="inline-flex items-center gap-1 px-2.5 py-0.5 rounded-full text-xs font-medium bg-blue-100 text-blue-800 animate-pulse">
-                        <Send className="w-3 h-3" /> Sending
+                        <Send className="w-3 h-3" /> {label}
                     </span>
                 );
             default:
                 return (
                     <span className="inline-flex items-center gap-1 px-2.5 py-0.5 rounded-full text-xs font-medium bg-slate-100 text-slate-800">
-                        <Clock className="w-3 h-3" /> Pending
+                        <Clock className="w-3 h-3" /> {catalogLabel(deliveryStatuses, "pending", "Pending")}
                     </span>
                 );
         }

frontend/src/app/(dashboard)/inbox/page.tsx

@@ -21,6 +21,7 @@ import {
 import { formatDistanceToNow } from "date-fns";
 import { cn } from "@/lib/utils";
 import { apiClient } from "@/lib/api";
+import { useCatalog, catalogLabel, type CatalogEntry } from "@/lib/catalog";
 import { useSearchParams, useRouter } from "next/navigation";
 import { toast } from "sonner";
 import TimelinePanel from "@/components/inbox/TimelinePanel";
@@ -53,6 +54,7 @@ type Conversation = {
 // --- Components ---
 
 export default function InboxPage() {
+    const { data: convStatuses } = useCatalog("conversation-statuses");
     const [conversations, setConversations] = useState<Conversation[]>([]);
     const [selectedId, setSelectedId] = useState<string | null>(null);
     const [thread, setThread] = useState<{ messages: Message[], status: string, contact: any } | null>(null);
@@ -187,9 +189,9 @@ export default function InboxPage() {
                             onChange={(e) => setStatusFilter(e.target.value)}
                         >
                             <option value="all">All Status</option>
-                            <option value="bot_active">AI Active</option>
-                            <option value="human_takeover">Human</option>
-                            <option value="closed">Closed</option>
+                            {convStatuses?.map((s) => (
+                                <option key={s.key} value={s.key}>{s.label}</option>
+                            ))}
                         </select>
                     </div>
                 </div>
@@ -397,15 +399,25 @@ export default function InboxPage() {
 
 // --- Subcomponents ---
 
+const STATUS_STYLES: Record<string, string> = {
+    bot_active: "bg-emerald-100 text-emerald-700 border-emerald-200",
+    human_takeover: "bg-amber-100 text-amber-700 border-amber-200",
+    closed: "bg-slate-100 text-slate-600 border-slate-200",
+};
+const STATUS_FALLBACK_LABELS: Record<string, string> = {
+    bot_active: "AI Active",
+    human_takeover: "Human Control",
+    closed: "Closed",
+};
+
 function StatusBadge({ status }: { status: "bot_active" | "human_takeover" | "closed" }) {
-    switch (status) {
-        case "bot_active":
-            return <div className="flex items-center gap-1.5 px-2 py-0.5 bg-emerald-100 text-emerald-700 rounded-full text-[10px] font-bold border border-emerald-200 uppercase">AI Active</div>;
-        case "human_takeover":
-            return <div className="flex items-center gap-1.5 px-2 py-0.5 bg-amber-100 text-amber-700 rounded-full text-[10px] font-bold border border-amber-200 uppercase">Human Control</div>;
-        case "closed":
-            return <div className="flex items-center gap-1.5 px-2 py-0.5 bg-slate-100 text-slate-600 rounded-full text-[10px] font-bold border border-slate-200 uppercase">Closed</div>;
-    }
+    const style = STATUS_STYLES[status] || STATUS_STYLES.closed;
+    const label = STATUS_FALLBACK_LABELS[status] || status;
+    return (
+        <div className={cn("flex items-center gap-1.5 px-2 py-0.5 rounded-full text-[10px] font-bold border uppercase", style)}>
+            {label}
+        </div>
+    );
 }
 
 function DeliveryStatusBadge({ status, error }: { status: string, error?: string }) {

frontend/src/app/(dashboard)/integrations/page.tsx

@@ -15,6 +15,7 @@ import {
 import Link from "next/link";
 import { cn } from "@/lib/utils";
 import { apiClient } from "@/lib/api";
+import { useCatalog, type CatalogEntry } from "@/lib/catalog";
 
 type Status = "connected" | "disconnected" | "error";
 
@@ -28,28 +29,15 @@ interface IntegrationProvider {
     icon: string;
 }
 
-const PROVIDER_METADATA: Record<string, any> = {
-    zoho: {
-        name: "Zoho CRM",
-        description: "Sync leads and contacts directly into your Zoho CRM pipeline.",
-        icon: 'data:image/svg+xml;utf8,<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Zoho</title><path fill="%230F766E" d="M21.758 12c0 5.39-4.368 9.758-9.758 9.758S2.242 17.39 2.242 12c0-5.39 4.368-9.758 9.758-9.758S21.758 6.61 21.758 12zm-9.035-4.482H6.554v2.09l4.16 4.303H6.554v2.09h6.169V14.12h.001l-4.148-4.29h4.148v-2.09.001zM17.446 12A2.77 2.77 0 1014.675 9.23 2.772 2.772 0 0017.446 12zm0 2.08A2.77 2.77 0 1020.217 16.85 2.772 2.772 0 0017.446 14.08z"/></svg>',
-        fields: [{ name: "org_id", label: "Organization ID", type: "text" }, { name: "access_token", label: "Access Token", type: "password" }]
-    },
-    whatsapp: {
-        name: "WhatsApp Cloud API",
-        description: "Official API for professional messaging and automation.",
-        icon: "https://upload.wikimedia.org/wikipedia/commons/6/6b/WhatsApp.svg",
-        fields: [{ name: "phone_number_id", label: "Phone Number ID", type: "text" }, { name: "access_token", label: "Access Token", type: "password" }]
-    },
-    meta: {
-        name: "Meta (Instagram/Messenger)",
-        description: "Automate responses for Instagram DM and Facebook Messenger.",
-        icon: "https://upload.wikimedia.org/wikipedia/commons/7/7b/Meta_Platforms_Inc._logo.svg",
-        fields: [{ name: "page_id", label: "Page ID", type: "text" }, { name: "access_token", label: "Access Token", type: "password" }]
-    }
+// Icons are a frontend presentation concern — keyed by catalog icon_hint
+const PROVIDER_ICONS: Record<string, string> = {
+    zoho: 'data:image/svg+xml;utf8,<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Zoho</title><path fill="%230F766E" d="M21.758 12c0 5.39-4.368 9.758-9.758 9.758S2.242 17.39 2.242 12c0-5.39 4.368-9.758 9.758-9.758S21.758 6.61 21.758 12zm-9.035-4.482H6.554v2.09l4.16 4.303H6.554v2.09h6.169V14.12h.001l-4.148-4.29h4.148v-2.09.001zM17.446 12A2.77 2.77 0 1014.675 9.23 2.772 2.772 0 0017.446 12zm0 2.08A2.77 2.77 0 1020.217 16.85 2.772 2.772 0 0017.446 14.08z"/></svg>',
+    whatsapp: "https://upload.wikimedia.org/wikipedia/commons/6/6b/WhatsApp.svg",
+    meta: "https://upload.wikimedia.org/wikipedia/commons/7/7b/Meta_Platforms_Inc._logo.svg",
 };
 
 export default function IntegrationsPage() {
+    const { data: providers } = useCatalog("integration-providers");
     const [integrations, setIntegrations] = useState<IntegrationProvider[]>([]);
     const [isLoading, setIsLoading] = useState(true);
     const [configModal, setConfigModal] = useState<{ provider: string } | null>(null);
@@ -57,15 +45,21 @@ export default function IntegrationsPage() {
     const [isSubmitting, setIsSubmitting] = useState(false);
     const [fetchError, setFetchError] = useState<string | null>(null);
 
-    const buildDefaultCards = () =>
-        Object.keys(PROVIDER_METADATA).map(providerKey => ({
-            id: providerKey,
-            provider: providerKey,
-            name: PROVIDER_METADATA[providerKey].name,
-            description: PROVIDER_METADATA[providerKey].description,
-            icon: PROVIDER_METADATA[providerKey].icon,
+    const getProviderMeta = (key: string): CatalogEntry | undefined =>
+        providers?.find((p) => p.key === key);
+
+    const getIcon = (entry: CatalogEntry): string =>
+        PROVIDER_ICONS[entry.icon_hint] || PROVIDER_ICONS[entry.key] || "";
+
+    const buildDefaultCards = (): IntegrationProvider[] =>
+        (providers || []).map((p) => ({
+            id: p.key,
+            provider: p.key,
+            name: p.label,
+            description: p.description || "",
+            icon: getIcon(p),
             status: "disconnected" as Status,
-            lastChecked: undefined
+            lastChecked: undefined,
         }));
 
     const fetchIntegrations = async () => {
@@ -73,39 +67,39 @@ export default function IntegrationsPage() {
         setFetchError(null);
         const res = await apiClient.get<any[]>("/integrations");
         if (res.success && res.data) {
-            const mapped = Object.keys(PROVIDER_METADATA).map(providerKey => {
-                const backendRecord = res.data?.find(r => r.provider === providerKey);
+            const mapped = (providers || []).map((p) => {
+                const backendRecord = res.data?.find((r: any) => r.provider === p.key);
                 return {
-                    id: backendRecord?.id || providerKey,
-                    provider: providerKey,
-                    name: PROVIDER_METADATA[providerKey].name,
-                    description: PROVIDER_METADATA[providerKey].description,
-                    icon: PROVIDER_METADATA[providerKey].icon,
+                    id: backendRecord?.id || p.key,
+                    provider: p.key,
+                    name: p.label,
+                    description: p.description || "",
+                    icon: getIcon(p),
                     status: backendRecord?.status || "disconnected",
-                    lastChecked: backendRecord?.last_checked_at ? new Date(backendRecord.last_checked_at).toLocaleTimeString() : undefined
+                    lastChecked: backendRecord?.last_checked_at ? new Date(backendRecord.last_checked_at).toLocaleTimeString() : undefined,
                 };
             });
-            setIntegrations(mapped as any);
+            setIntegrations(mapped as IntegrationProvider[]);
         } else {
             setFetchError(res.error || "Failed to load integrations.");
-            setIntegrations(buildDefaultCards() as any);
+            setIntegrations(buildDefaultCards());
         }
         setIsLoading(false);
     };
 
     useEffect(() => {
-        fetchIntegrations();
-    }, []);
+        if (providers) fetchIntegrations();
+    }, [providers]);
 
     const handleConnect = async () => {
         if (!configModal) return;
         setIsSubmitting(true);
 
-        // Extract provider_workspace_id from payload based on provider
-        let pwid = "";
-        if (configModal.provider === "whatsapp") pwid = configPayload.phone_number_id;
-        else if (configModal.provider === "meta") pwid = configPayload.page_id;
-        else pwid = configPayload.org_id;
+        const meta = getProviderMeta(configModal.provider);
+        const fields = (meta?.fields as any[]) || [];
+        // Use the first non-access_token field as provider_workspace_id
+        const idField = fields.find((f: any) => f.name !== "access_token");
+        const pwid = idField ? configPayload[idField.name] || "" : "";
 
         const res = await apiClient.post(`/integrations/${configModal.provider}/connect`, {
             provider_workspace_id: pwid,
@@ -123,7 +117,8 @@ export default function IntegrationsPage() {
     };
 
     const handleDisconnect = async (provider: string) => {
-        if (!confirm(`Are you sure you want to disconnect ${provider}?`)) return;
+        const meta = getProviderMeta(provider);
+        if (!confirm(`Are you sure you want to disconnect ${meta?.label || provider}?`)) return;
         setIsSubmitting(true);
         const res = await apiClient.post(`/integrations/${provider}/disconnect`);
         if (res.success) {
@@ -143,6 +138,8 @@ export default function IntegrationsPage() {
         }
     };
 
+    const modalMeta = configModal ? getProviderMeta(configModal.provider) : null;
+
     return (
         <div className="flex flex-col space-y-8">
             <div className="flex items-center justify-between">
@@ -175,13 +172,12 @@ export default function IntegrationsPage() {
                     </div>
                 ) : integrations.map((item) => {
                     const status = getStatusInfo(item.status);
-                    const metadata = PROVIDER_METADATA[item.provider];
                     return (
                         <div key={item.provider} className="bg-white border border-border rounded-xl shadow-sm hover:shadow-md transition-shadow flex flex-col">
                             <div className="p-6 flex-1">
                                 <div className="flex items-start justify-between mb-4">
                                     <div className="w-12 h-12 rounded-lg border border-slate-100 p-2 flex items-center justify-center bg-white shadow-sm">
-                                        <img src={metadata.icon} alt={metadata.name} className="w-8 h-8 object-contain" />
+                                        <img src={item.icon} alt={item.name} className="w-8 h-8 object-contain" />
                                     </div>
                                     <div className={cn(
                                         "flex items-center gap-1.5 px-2.5 py-1 rounded-full text-[10px] font-bold border",
@@ -192,9 +188,9 @@ export default function IntegrationsPage() {
                                     </div>
                                 </div>
 
-                                <h3 className="font-bold text-slate-800 mb-1">{metadata.name}</h3>
+                                <h3 className="font-bold text-slate-800 mb-1">{item.name}</h3>
                                 <p className="text-xs text-slate-500 leading-relaxed min-h-[40px]">
-                                    {metadata.description}
+                                    {item.description}
                                 </p>
 
                                 {item.lastChecked && (
@@ -234,7 +230,7 @@ export default function IntegrationsPage() {
                                         className="w-full px-3 py-2 bg-teal-600 text-white rounded-md text-xs font-bold hover:bg-teal-700 transition-colors flex items-center justify-center gap-2 shadow-sm"
                                     >
                                         <Plug className="w-3.5 h-3.5" />
-                                        Connect {metadata.name}
+                                        Connect {item.name}
                                     </button>
                                 )}
                             </div>
@@ -243,7 +239,7 @@ export default function IntegrationsPage() {
                 })}
             </div>
 
-            {/* Custom Integration Banner relocated */}
+            {/* Custom Integration Banner */}
             <div className="bg-slate-50 border border-slate-200 rounded-xl p-6 flex items-center justify-between">
                 <div>
                     <h2 className="text-sm font-bold text-slate-900 mb-1">Need a custom integration?</h2>
@@ -258,20 +254,20 @@ export default function IntegrationsPage() {
             </div>
 
             {/* Configuration Modal */}
-            {configModal && (
+            {configModal && modalMeta && (
                 <div className="fixed inset-0 z-50 flex items-center justify-center bg-slate-900/50 backdrop-blur-sm p-4">
                     <div className="bg-white rounded-2xl shadow-2xl w-full max-w-md border border-border animate-in fade-in zoom-in-95 duration-200 overflow-hidden">
                         <div className="p-6 border-b border-border bg-slate-50/50">
                             <div className="flex items-center gap-3">
-                                <img src={PROVIDER_METADATA[configModal.provider].icon} className="w-8 h-8" />
+                                <img src={getIcon(modalMeta)} className="w-8 h-8" />
                                 <div>
-                                    <h3 className="font-bold text-slate-900">Connect {PROVIDER_METADATA[configModal.provider].name}</h3>
+                                    <h3 className="font-bold text-slate-900">Connect {modalMeta.label}</h3>
                                     <p className="text-xs text-slate-500">Enter your credentials to sync LeadPilot.</p>
                                 </div>
                             </div>
                         </div>
                         <div className="p-6 space-y-4">
-                            {PROVIDER_METADATA[configModal.provider].fields.map((f: any) => (
+                            {(modalMeta.fields as any[] || []).map((f: any) => (
                                 <div key={f.name} className="space-y-1.5">
                                     <label className="text-xs font-bold text-slate-600 uppercase tracking-wider">{f.label}</label>
                                     <input

frontend/src/app/(dashboard)/prompt-studio/page.tsx

@@ -7,7 +7,6 @@ import {
     Sparkles,
     AlertCircle,
     CheckCircle2,
-    ChevronRight,
     Shield,
     Target,
     UserCircle,
@@ -17,7 +16,10 @@ import {
     FileText,
     Trash2,
     Plus,
-    Upload
+    Upload,
+    Download,
+    ArrowUp,
+    ArrowDown,
 } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { apiClient } from "@/lib/api";
@@ -32,6 +34,12 @@ export default function PromptStudioPage() {
     const [knowledgeFiles, setKnowledgeFiles] = useState<any[]>([]);
     const [isUploading, setIsUploading] = useState(false);
 
+    // Qualification state
+    const [qualQuestions, setQualQuestions] = useState<any[]>([]);
+    const [qualStatuses, setQualStatuses] = useState<any[]>([]);
+    const [qualVersion, setQualVersion] = useState(1);
+    const [isSavingQual, setIsSavingQual] = useState(false);
+
     // Form State
     const [formData, setFormData] = useState({
         basics: {
@@ -70,6 +78,68 @@ export default function PromptStudioPage() {
         }
     };
 
+    const fetchQualificationConfig = async () => {
+        const res = await apiClient.get("/qualification-config");
+        if (res.success && res.data) {
+            setQualQuestions(res.data.qualification_questions || []);
+            setQualStatuses(res.data.qualification_statuses || []);
+            setQualVersion(res.data.version || 1);
+        }
+    };
+
+    const handleSaveQualification = async () => {
+        setIsSavingQual(true);
+        const res = await apiClient.post("/qualification-config", {
+            qualification_questions: qualQuestions,
+            qualification_statuses: qualStatuses,
+        });
+        if (res.success && res.data) {
+            setQualVersion(res.data.version || qualVersion + 1);
+        } else {
+            alert("Error saving qualification config: " + res.error);
+        }
+        setIsSavingQual(false);
+    };
+
+    const addQuestion = () => {
+        setQualQuestions([
+            ...qualQuestions,
+            { label: "", enabled: true, order: qualQuestions.length },
+        ]);
+    };
+
+    const removeQuestion = (index: number) => {
+        setQualQuestions(qualQuestions.filter((_, i) => i !== index));
+    };
+
+    const updateQuestion = (index: number, field: string, value: any) => {
+        setQualQuestions(qualQuestions.map((q, i) => i === index ? { ...q, [field]: value } : q));
+    };
+
+    const moveQuestion = (index: number, direction: "up" | "down") => {
+        const target = direction === "up" ? index - 1 : index + 1;
+        if (target < 0 || target >= qualQuestions.length) return;
+        const next = [...qualQuestions];
+        [next[index], next[target]] = [next[target], next[index]];
+        next.forEach((q, i) => (q.order = i));
+        setQualQuestions(next);
+    };
+
+    const addStatus = () => {
+        setQualStatuses([
+            ...qualStatuses,
+            { label: "", color: "#94a3b8", enabled: true },
+        ]);
+    };
+
+    const removeStatus = (index: number) => {
+        setQualStatuses(qualStatuses.filter((_, i) => i !== index));
+    };
+
+    const updateStatus = (index: number, field: string, value: any) => {
+        setQualStatuses(qualStatuses.map((s, i) => i === index ? { ...s, [field]: value } : s));
+    };
+
     const fetchConfig = async () => {
         setIsLoading(true);
         setError(null);
@@ -87,6 +157,7 @@ export default function PromptStudioPage() {
                 setError(res.error || "Failed to load prompt configuration.");
             }
             await fetchKnowledgeFiles();
+            await fetchQualificationConfig();
         } catch (err: any) {
             setError("Connectivity error. Please check your internet or try again.");
         } finally {
@@ -163,7 +234,8 @@ export default function PromptStudioPage() {
     const tabs = [
         { id: "editor", label: "Assistant Configuration", icon: UserCircle },
         { id: "knowledge", label: "Knowledge Base", icon: FileText },
-        { id: "history", label: "Version History", icon: History }
+        { id: "qualification", label: "Lead Qualification", icon: Target },
+        { id: "history", label: "Version History", icon: History },
     ];
 
     return (
@@ -225,6 +297,11 @@ export default function PromptStudioPage() {
                                                 {knowledgeFiles.length}
                                             </span>
                                         )}
+                                        {tab.id === "qualification" && qualQuestions.filter(q => q.enabled !== false).length > 0 && (
+                                            <span className="ml-2 bg-slate-200 text-slate-600 px-1.5 py-0.5 rounded-full text-[10px]">
+                                                {qualQuestions.filter(q => q.enabled !== false).length}
+                                            </span>
+                                        )}
                                     </button>
                                 ))}
                             </div>
@@ -449,15 +526,43 @@ export default function PromptStudioPage() {
                                                                     <span>{(file.size_bytes / 1024).toFixed(1)} KB</span>
                                                                     <span>•</span>
                                                                     <span>{new Date(file.created_at).toLocaleDateString()}</span>
+                                                                    <span>•</span>
+                                                                    {file.status === "READY" ? (
+                                                                        <span className="text-emerald-600 flex items-center gap-0.5">
+                                                                            <CheckCircle2 className="w-3 h-3" /> Indexed
+                                                                        </span>
+                                                                    ) : (
+                                                                        <span className="text-rose-500 flex items-center gap-0.5">
+                                                                            <AlertCircle className="w-3 h-3" /> Failed
+                                                                        </span>
+                                                                    )}
+                                                                    {file.extracted && (
+                                                                        <>
+                                                                            <span>•</span>
+                                                                            <span className="text-teal-600">Text extracted</span>
+                                                                        </>
+                                                                    )}
                                                                 </div>
                                                             </div>
                                                         </div>
-                                                        <button
-                                                            onClick={() => handleDeleteFile(file.id)}
-                                                            className="p-2 text-slate-300 hover:text-rose-500 hover:bg-rose-50 rounded-lg transition-all opacity-0 group-hover:opacity-100"
-                                                        >
-                                                            <Trash2 className="w-4 h-4" />
-                                                        </button>
+                                                        <div className="flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-all">
+                                                            <a
+                                                                href={`${process.env.NEXT_PUBLIC_API_URL || ""}/api/v1/knowledge/files/${file.id}/download`}
+                                                                target="_blank"
+                                                                rel="noopener noreferrer"
+                                                                className="p-2 text-slate-300 hover:text-teal-600 hover:bg-teal-50 rounded-lg transition-all"
+                                                                title="Download"
+                                                            >
+                                                                <Download className="w-4 h-4" />
+                                                            </a>
+                                                            <button
+                                                                onClick={() => handleDeleteFile(file.id)}
+                                                                className="p-2 text-slate-300 hover:text-rose-500 hover:bg-rose-50 rounded-lg transition-all"
+                                                                title="Delete"
+                                                            >
+                                                                <Trash2 className="w-4 h-4" />
+                                                            </button>
+                                                        </div>
                                                     </div>
                                                 ))
                                             )}
@@ -466,7 +571,169 @@ export default function PromptStudioPage() {
                                         <div className="bg-amber-50 border border-amber-100 rounded-xl p-4 flex gap-3">
                                             <AlertCircle className="w-4 h-4 text-amber-600 shrink-0" />
                                             <p className="text-[11px] text-amber-800 leading-normal">
-                                                <strong>Pro Tip:</strong> Files like TXT and CSV are indexed automatically. For PDFs, make sure to add a summary in the "Notes" field (coming soon) or ensure they are text-searchable.
+                                                <strong>Pro Tip:</strong> Uploaded files (TXT, CSV, PDF) are automatically extracted and injected into your AI&apos;s context. The AI will reference these documents when responding to leads.
+                                            </p>
+                                        </div>
+                                    </div>
+                                ) : activeTab === "qualification" ? (
+                                    <div className="space-y-8">
+                                        {/* Header */}
+                                        <div className="flex items-center justify-between border-b border-slate-100 pb-4">
+                                            <div>
+                                                <h2 className="text-lg font-bold text-slate-800">Lead Qualification</h2>
+                                                <p className="text-xs text-slate-500">Configure questions the AI collects from leads, and qualification statuses. <span className="text-slate-400">(v{qualVersion})</span></p>
+                                            </div>
+                                            <button
+                                                onClick={handleSaveQualification}
+                                                disabled={isSavingQual}
+                                                className="bg-teal-700 text-white px-5 py-2 rounded-lg text-sm font-bold hover:bg-teal-800 transition-all flex items-center gap-2 shadow-sm disabled:opacity-50"
+                                            >
+                                                {isSavingQual ? <Loader2 className="w-4 h-4 animate-spin" /> : <Save className="w-4 h-4" />}
+                                                Save Qualification
+                                            </button>
+                                        </div>
+
+                                        {/* Questions Section */}
+                                        <section className="space-y-4">
+                                            <div className="flex items-center justify-between">
+                                                <div className="flex items-center gap-2 text-slate-800">
+                                                    <Target className="w-4 h-4 text-teal-600" />
+                                                    <h3 className="text-sm font-bold uppercase tracking-wider">Qualification Questions</h3>
+                                                </div>
+                                                <button
+                                                    onClick={addQuestion}
+                                                    className="text-xs font-bold text-teal-600 hover:text-teal-700 flex items-center gap-1 transition-all"
+                                                >
+                                                    <Plus className="w-3.5 h-3.5" /> Add Question
+                                                </button>
+                                            </div>
+                                            <p className="text-[11px] text-slate-400">The AI will attempt to collect these details from each lead during conversation.</p>
+
+                                            {qualQuestions.length === 0 ? (
+                                                <div className="py-10 flex flex-col items-center justify-center border-2 border-dashed border-slate-200 rounded-xl bg-slate-50 text-slate-400">
+                                                    <Target className="w-8 h-8 mb-3 opacity-20" />
+                                                    <p className="text-sm font-medium">No questions configured</p>
+                                                    <p className="text-[10px] mt-1">Click &quot;Add Question&quot; to start building your qualification form.</p>
+                                                </div>
+                                            ) : (
+                                                <div className="space-y-2">
+                                                    {qualQuestions.map((q, i) => (
+                                                        <div key={i} className="flex items-center gap-3 p-3 bg-white border border-slate-200 rounded-xl group hover:border-teal-400 transition-all">
+                                                            <div className="flex flex-col gap-0.5">
+                                                                <button
+                                                                    onClick={() => moveQuestion(i, "up")}
+                                                                    disabled={i === 0}
+                                                                    className="p-0.5 text-slate-300 hover:text-slate-600 disabled:opacity-20 transition-all"
+                                                                >
+                                                                    <ArrowUp className="w-3 h-3" />
+                                                                </button>
+                                                                <button
+                                                                    onClick={() => moveQuestion(i, "down")}
+                                                                    disabled={i === qualQuestions.length - 1}
+                                                                    className="p-0.5 text-slate-300 hover:text-slate-600 disabled:opacity-20 transition-all"
+                                                                >
+                                                                    <ArrowDown className="w-3 h-3" />
+                                                                </button>
+                                                            </div>
+                                                            <input
+                                                                type="text"
+                                                                value={q.label}
+                                                                onChange={(e) => updateQuestion(i, "label", e.target.value)}
+                                                                placeholder="e.g. Budget Range"
+                                                                className="flex-1 p-2 bg-slate-50 border border-slate-200 rounded-lg text-sm focus:ring-2 focus:ring-teal-500/20 focus:border-teal-500 outline-none transition-all"
+                                                            />
+                                                            <label className="flex items-center gap-1.5 cursor-pointer select-none">
+                                                                <input
+                                                                    type="checkbox"
+                                                                    checked={q.enabled !== false}
+                                                                    onChange={(e) => updateQuestion(i, "enabled", e.target.checked)}
+                                                                    className="w-4 h-4 accent-teal-600"
+                                                                />
+                                                                <span className="text-[10px] font-medium text-slate-500">Enabled</span>
+                                                            </label>
+                                                            <button
+                                                                onClick={() => removeQuestion(i)}
+                                                                className="p-1.5 text-slate-300 hover:text-rose-500 hover:bg-rose-50 rounded-lg transition-all opacity-0 group-hover:opacity-100"
+                                                            >
+                                                                <Trash2 className="w-3.5 h-3.5" />
+                                                            </button>
+                                                        </div>
+                                                    ))}
+                                                </div>
+                                            )}
+                                        </section>
+
+                                        {/* Statuses Section */}
+                                        <section className="space-y-4">
+                                            <div className="flex items-center justify-between">
+                                                <div className="flex items-center gap-2 text-slate-800">
+                                                    <Shield className="w-4 h-4 text-teal-600" />
+                                                    <h3 className="text-sm font-bold uppercase tracking-wider">Qualification Statuses</h3>
+                                                </div>
+                                                <button
+                                                    onClick={addStatus}
+                                                    className="text-xs font-bold text-teal-600 hover:text-teal-700 flex items-center gap-1 transition-all"
+                                                >
+                                                    <Plus className="w-3.5 h-3.5" /> Add Status
+                                                </button>
+                                            </div>
+                                            <p className="text-[11px] text-slate-400">Define the lifecycle stages for your leads. These statuses will appear in the Contacts page.</p>
+
+                                            {qualStatuses.length === 0 ? (
+                                                <div className="py-10 flex flex-col items-center justify-center border-2 border-dashed border-slate-200 rounded-xl bg-slate-50 text-slate-400">
+                                                    <Shield className="w-8 h-8 mb-3 opacity-20" />
+                                                    <p className="text-sm font-medium">No statuses configured</p>
+                                                    <p className="text-[10px] mt-1">Click &quot;Add Status&quot; to define lead lifecycle stages.</p>
+                                                </div>
+                                            ) : (
+                                                <div className="space-y-2">
+                                                    {qualStatuses.map((s, i) => (
+                                                        <div key={i} className="flex items-center gap-3 p-3 bg-white border border-slate-200 rounded-xl group hover:border-teal-400 transition-all">
+                                                            <input
+                                                                type="color"
+                                                                value={s.color || "#94a3b8"}
+                                                                onChange={(e) => updateStatus(i, "color", e.target.value)}
+                                                                className="w-8 h-8 rounded-lg border border-slate-200 cursor-pointer p-0.5"
+                                                                title="Pick color"
+                                                            />
+                                                            <input
+                                                                type="text"
+                                                                value={s.label}
+                                                                onChange={(e) => updateStatus(i, "label", e.target.value)}
+                                                                placeholder="e.g. Qualified"
+                                                                className="flex-1 p-2 bg-slate-50 border border-slate-200 rounded-lg text-sm focus:ring-2 focus:ring-teal-500/20 focus:border-teal-500 outline-none transition-all"
+                                                            />
+                                                            <span
+                                                                className="px-3 py-1 rounded-full text-[10px] font-bold text-white"
+                                                                style={{ backgroundColor: s.color || "#94a3b8" }}
+                                                            >
+                                                                {s.label || "Preview"}
+                                                            </span>
+                                                            <label className="flex items-center gap-1.5 cursor-pointer select-none">
+                                                                <input
+                                                                    type="checkbox"
+                                                                    checked={s.enabled !== false}
+                                                                    onChange={(e) => updateStatus(i, "enabled", e.target.checked)}
+                                                                    className="w-4 h-4 accent-teal-600"
+                                                                />
+                                                                <span className="text-[10px] font-medium text-slate-500">Enabled</span>
+                                                            </label>
+                                                            <button
+                                                                onClick={() => removeStatus(i)}
+                                                                className="p-1.5 text-slate-300 hover:text-rose-500 hover:bg-rose-50 rounded-lg transition-all opacity-0 group-hover:opacity-100"
+                                                            >
+                                                                <Trash2 className="w-3.5 h-3.5" />
+                                                            </button>
+                                                        </div>
+                                                    ))}
+                                                </div>
+                                            )}
+                                        </section>
+
+                                        <div className="bg-teal-50/50 border border-teal-100 rounded-xl p-4 flex gap-3">
+                                            <AlertCircle className="w-4 h-4 text-teal-600 shrink-0" />
+                                            <p className="text-[11px] text-teal-700 leading-normal">
+                                                <strong>How it works:</strong> Enabled questions are injected into the AI&apos;s system prompt. The AI will naturally ask leads for this information during conversation. Statuses can be used to categorize leads in the Contacts page.
                                             </p>
                                         </div>
                                     </div>

frontend/src/app/(marketing)/plans/page.tsx

@@ -5,6 +5,7 @@ import { Check, Clock, ChevronDown, ChevronUp, Loader2, CheckCircle, AlertCircle
 import Link from "next/link";
 import AnimateOnScroll from "@/components/marketing/AnimateOnScroll";
 import FloatingOrb from "@/components/marketing/FloatingOrb";
+import { useCatalog, type PlanCatalogEntry } from "@/lib/catalog";
 
 const tiers = [
   {
@@ -42,6 +43,8 @@ const faqs = [
 ];
 
 function WaitlistForm() {
+  const { data: plans } = useCatalog<PlanCatalogEntry[]>("plans");
+  const waitlistPlans = (plans || []).filter(p => p.name !== "free");
   const [email, setEmail] = useState("");
   const [plan, setPlan] = useState("Growth");
   const [state, setState] = useState<"idle" | "loading" | "success" | "error">("idle");
@@ -94,9 +97,16 @@ function WaitlistForm() {
             className="w-full sm:w-36 px-4 py-3 rounded-xl text-sm"
             style={{ background: "rgba(255,255,255,0.06)", border: "1px solid rgba(255,255,255,0.1)", color: "#F1F5F9", outline: "none" }}
           >
-            <option value="Growth">Growth</option>
-            <option value="Pro">Pro</option>
-            <option value="Enterprise">Enterprise</option>
+            {waitlistPlans.length > 0
+              ? waitlistPlans.map((p) => (
+                  <option key={p.name} value={p.display_name}>{p.display_name}</option>
+                ))
+              : <>
+                  <option value="Growth">Growth</option>
+                  <option value="Pro">Pro</option>
+                  <option value="Enterprise">Enterprise</option>
+                </>
+            }
           </select>
         </div>
         <button type="submit" disabled={state === "loading"}

frontend/src/lib/admin-api.ts

@@ -325,6 +325,7 @@ export const adminApi = {
         adminClient.put(`/admin/agencies/${agencyId}/plan`, { plan_id: planId }),
 };
 
+// Canonical source: GET /api/v1/catalog/modules — prefer useCatalog("modules") for dynamic labels
 export const MODULE_LABELS: Record<string, string> = {
     auth: "Authentication",
     email_engine: "Email Engine",

frontend/src/lib/catalog.ts

@@ -0,0 +1,133 @@
+/**
+ * Catalog client — Mission 19
+ * Provides a useCatalog() hook that fetches and caches catalog data.
+ * Uses the product apiClient (no auth required for catalog endpoints).
+ */
+import { useState, useEffect, useCallback } from "react";
+import { apiClient, type ApiResponse } from "./api";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface CatalogEntry {
+  key: string;
+  label: string;
+  description?: string;
+  [extra: string]: any;
+}
+
+export interface PlanCatalogEntry {
+  id: string;
+  name: string;
+  display_name: string;
+  description: string | null;
+  sort_order: number;
+  entitlements: { module_key: string; hard_limit: number | null }[];
+}
+
+export type CatalogKey =
+  | "plans"
+  | "tiers"
+  | "modules"
+  | "workspace-roles"
+  | "admin-roles"
+  | "integration-providers"
+  | "automation-node-types"
+  | "automation-trigger-types"
+  | "conversation-statuses"
+  | "message-delivery-statuses";
+
+// ── Cache ────────────────────────────────────────────────────────────
+
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+}
+
+const CACHE_TTL_MS = 60_000;
+const cache = new Map<string, CacheEntry<unknown>>();
+
+function getCached<T>(key: string): T | null {
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.timestamp > CACHE_TTL_MS) {
+    cache.delete(key);
+    return null;
+  }
+  return entry.data as T;
+}
+
+function setCache<T>(key: string, data: T): void {
+  cache.set(key, { data, timestamp: Date.now() });
+}
+
+// ── Fetch ────────────────────────────────────────────────────────────
+
+async function fetchCatalog<T = CatalogEntry[]>(key: CatalogKey): Promise<T> {
+  const cached = getCached<T>(key);
+  if (cached !== null) return cached;
+
+  const res: ApiResponse<T> = await apiClient.get<T>(`/catalog/${key}`);
+  if (res.success && res.data) {
+    setCache(key, res.data);
+    return res.data;
+  }
+  throw new Error(res.error || `Failed to fetch catalog: ${key}`);
+}
+
+// ── Hook ─────────────────────────────────────────────────────────────
+
+export interface UseCatalogResult<T> {
+  data: T | null;
+  loading: boolean;
+  error: string | null;
+  refetch: () => void;
+}
+
+export function useCatalog<T = CatalogEntry[]>(
+  key: CatalogKey
+): UseCatalogResult<T> {
+  const [data, setData] = useState<T | null>(() => getCached<T>(key));
+  const [loading, setLoading] = useState<boolean>(data === null);
+  const [error, setError] = useState<string | null>(null);
+
+  const load = useCallback(() => {
+    setLoading(true);
+    setError(null);
+    fetchCatalog<T>(key)
+      .then((result) => {
+        setData(result);
+        setLoading(false);
+      })
+      .catch((err) => {
+        setError(err.message || "Catalog fetch failed");
+        setLoading(false);
+      });
+  }, [key]);
+
+  useEffect(() => {
+    if (data !== null) {
+      setLoading(false);
+      return;
+    }
+    load();
+  }, [key, load, data]);
+
+  return { data, loading, error, refetch: load };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+export function catalogLookup(
+  items: CatalogEntry[] | null,
+  key: string
+): CatalogEntry | undefined {
+  return items?.find((item) => item.key === key);
+}
+
+export function catalogLabel(
+  items: CatalogEntry[] | null,
+  key: string,
+  fallback?: string
+): string {
+  return catalogLookup(items, key)?.label ?? fallback ?? key;
+}