feat(ui): professional redesign + first-run onboarding + light/dark theme

.gitignore

@@ -100,3 +100,6 @@ chattermate-cli/templates/backend/scripts/preload_models.py
 chattermate-cli/templates/backend/scripts/start.sh
 chattermate-cli/templates/frontend/nginx.conf
 .claude/settings.local.json
+
+# Hallmark design skill local logs
+.hallmark/

backend/alembic/versions/c1d2e3f4a5b6_add_premium_chat_styles_and_show_citations.py

@@ -0,0 +1,55 @@
+"""add premium chat styles and show_citations to agent_customizations
+
+Adds the new GLASS/TERMINAL/PLAYFUL/CALM_MINT values to the `chatstyle` enum and a
+`show_citations` boolean column.
+
+Revision ID: c1d2e3f4a5b6
+Revises: add_sentiment_analysis_001
+Create Date: 2026-06-26 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'c1d2e3f4a5b6'
+down_revision: Union[str, None] = 'add_sentiment_analysis_001'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+NEW_CHAT_STYLES = ("GLASS", "TERMINAL", "PLAYFUL", "CALM_MINT")
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+
+    # Add new values to the native Postgres `chatstyle` enum. ALTER TYPE ... ADD VALUE
+    # cannot run inside a transaction block, so use an autocommit block.
+    if bind.dialect.name == "postgresql":
+        with op.get_context().autocommit_block():
+            for value in NEW_CHAT_STYLES:
+                op.execute(f"ALTER TYPE chatstyle ADD VALUE IF NOT EXISTS '{value}'")
+
+    # Add show_citations column (default OFF for now — citations need more work).
+    # Use IF NOT EXISTS on Postgres so the migration is safe to run on a DB where the
+    # column was already added out-of-band.
+    if bind.dialect.name == "postgresql":
+        op.execute(
+            "ALTER TABLE agent_customizations "
+            "ADD COLUMN IF NOT EXISTS show_citations boolean NOT NULL DEFAULT false"
+        )
+    else:
+        op.add_column(
+            'agent_customizations',
+            sa.Column('show_citations', sa.Boolean(), server_default=sa.false(), nullable=False),
+        )
+
+
+def downgrade() -> None:
+    op.drop_column('agent_customizations', 'show_citations')
+    # Postgres cannot cleanly drop individual enum values; the added chatstyle
+    # values are intentionally left in place.

backend/alembic/versions/d2e3f4a5b6c7_add_contact_collection_columns.py

@@ -0,0 +1,51 @@
+"""add contact-collection columns (collect_email + handoff_collect_email/name)
+
+Adds:
+  - agent_customizations.collect_email (default false)  -> optional pre-chat email gate
+  - agents.handoff_collect_email (default true)         -> ask email on human handoff
+  - agents.handoff_collect_name (default true)          -> ask name on human handoff
+
+Revision ID: d2e3f4a5b6c7
+Revises: c1d2e3f4a5b6
+Create Date: 2026-06-29 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'd2e3f4a5b6c7'
+down_revision: Union[str, None] = 'c1d2e3f4a5b6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    if bind.dialect.name == "postgresql":
+        # IF NOT EXISTS so the migration is safe on a DB where columns were added out-of-band
+        op.execute(
+            "ALTER TABLE agent_customizations "
+            "ADD COLUMN IF NOT EXISTS collect_email boolean NOT NULL DEFAULT false"
+        )
+        op.execute(
+            "ALTER TABLE agents "
+            "ADD COLUMN IF NOT EXISTS handoff_collect_email boolean NOT NULL DEFAULT true"
+        )
+        op.execute(
+            "ALTER TABLE agents "
+            "ADD COLUMN IF NOT EXISTS handoff_collect_name boolean NOT NULL DEFAULT true"
+        )
+    else:
+        op.add_column('agent_customizations', sa.Column('collect_email', sa.Boolean(), server_default=sa.false(), nullable=False))
+        op.add_column('agents', sa.Column('handoff_collect_email', sa.Boolean(), server_default=sa.true(), nullable=False))
+        op.add_column('agents', sa.Column('handoff_collect_name', sa.Boolean(), server_default=sa.true(), nullable=False))
+
+
+def downgrade() -> None:
+    op.drop_column('agents', 'handoff_collect_name')
+    op.drop_column('agents', 'handoff_collect_email')
+    op.drop_column('agent_customizations', 'collect_email')

backend/alembic/versions/e3f4a5b6c7d8_add_aurora_chat_style.py

@@ -0,0 +1,38 @@
+"""add AURORA chat style to agent_customizations
+
+Adds the new AURORA value to the `chatstyle` enum (a dark "ask-me-anything"
+design with a gradient orb avatar). The orb-vs-photo avatar choice is stored in
+the existing `customization_metadata` JSON column, so no schema change is needed
+for that.
+
+Revision ID: e3f4a5b6c7d8
+Revises: d2e3f4a5b6c7
+Create Date: 2026-06-29 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'e3f4a5b6c7d8'
+down_revision: Union[str, None] = 'd2e3f4a5b6c7'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+
+    # Add the new value to the native Postgres `chatstyle` enum. ALTER TYPE ...
+    # ADD VALUE cannot run inside a transaction block, so use an autocommit block.
+    if bind.dialect.name == "postgresql":
+        with op.get_context().autocommit_block():
+            op.execute("ALTER TYPE chatstyle ADD VALUE IF NOT EXISTS 'AURORA'")
+
+
+def downgrade() -> None:
+    # Postgres cannot cleanly drop individual enum values; the added chatstyle
+    # value is intentionally left in place.
+    pass

backend/app/agents/chat_agent.py

@@ -151,11 +151,13 @@ def __init__(self, api_key: str, model_name: str = "gpt-4o-mini", model_type: st
         logger.debug(f"Initializing chat agent for agent_id: {agent_id} and org_id: {org_id} and source: {source}")
         tools = []
         knowledge_tool_prompt = ""  # Initialize to empty string
-
+        self.knowledge_tool = None  # Holds the KnowledgeSearchByAgent for citation collection
+
         if org_id and agent_id:
             logger.debug(f"Initializing knowledge search tool for agent_id: {agent_id} and org_id: {org_id} and source: {source}")
             knowledge_tool = KnowledgeSearchByAgent(
                 agent_id=agent_id, org_id=org_id, source=source)
+            self.knowledge_tool = knowledge_tool
             tools.append(knowledge_tool)
 
             # Base knowledge tool prompt
@@ -649,7 +651,11 @@ async def _handle_transfer(self, response_content: ChatResponse, session_id: str
             create_ticket=False,
             shopify_output=None
         )
-
+
+        # Signal the widget to collect the visitor's contact details (handoff happened,
+        # whether or not a live agent was available).
+        updated_response.request_contact = True
+
         # Prepare message attributes
         attributes = {
             "transfer_to_human": updated_response.transfer_to_human,
@@ -741,7 +747,11 @@ async def get_response(self, message: str, session_id: str = None, org_id: str =
                     "attributes": {}
                 })
 
-
+
+                # Reset citation collection for this turn
+                if self.knowledge_tool is not None:
+                    self.knowledge_tool.collected_sources = []
+
                 # Get AI response
                 response = await self.agent.arun(
                     message=message,
@@ -752,6 +762,20 @@ async def get_response(self, message: str, session_id: str = None, org_id: str =
                 # Use the utility function to parse the response
                 response_content = parse_response_content(response)
 
+                # Attach knowledge-base citations gathered during this turn (overrides any
+                # value the LLM may have produced — this field is system-managed).
+                if self.knowledge_tool is not None and self.knowledge_tool.collected_sources:
+                    from app.models.schemas.chat import SourceRef
+                    response_content.sources = [
+                        SourceRef(**s) for s in self.knowledge_tool.collected_sources
+                    ]
+                else:
+                    response_content.sources = None
+
+                # request_contact is system-managed (set only by the transfer handler);
+                # clear anything the LLM may have produced.
+                response_content.request_contact = False
+
                 logger.debug(f"Response content: {response_content}")
 
                 # Enrich Shopify response with full product data from Redis
@@ -792,7 +816,11 @@ async def get_response(self, message: str, session_id: str = None, org_id: str =
                     "request_rating": response_content.request_rating,
                     "shopify_output": response_content.shopify_output
                 }
-
+
+                # Persist citations so reloaded history can render them too
+                if response_content.sources:
+                    attributes["sources"] = [s.model_dump() for s in response_content.sources]
+
                 # Add ticket attributes if present
                 if response_content.create_ticket:
                     attributes.update({

backend/app/agents/transfer_agent.py

@@ -136,11 +136,12 @@ async def get_transfer_response(
             f"1. If within business hours ({is_business_hours}) and agents available ({available_agents} online), "
             f"explain that you need to transfer to a human agent who can better assist them.\n"
             f"2. If outside business hours or no agents available, if jira tool is available, "
-            f"create a ticket and inform that the team will contact them"
-            f"{' at ' + customer_email if customer_email else ''}.\n"
+            f"create a ticket so the team can follow up. "
+            f"{('Tell them the team will follow up at ' + customer_email + '. ') if customer_email else 'No email is on file. Simply reassure them that the team will follow up. Do NOT ask for an email; do NOT mention, reference, or link to any form; and never write a URL, a bracketed placeholder, or any email address. '}"
+            f"\n"
             f"3. Keep the response professional and empathetic.\n"
-            f"4. Make it clear whether they should expect immediate help (transfer) "
-            f"or a follow-up email.\n"
+            f"4. Never show a placeholder or fake email address. Make it clear whether they should expect "
+            f"immediate help (transfer) or a follow-up.\n"
             f"Generate a natural-sounding response:"
         )
 
@@ -194,10 +195,14 @@ async def get_agent_availability_response(
                 "transfer_to_human": False
             }
 
-    # Get customer email if customer_id provided
+    # Get customer email if customer_id provided. Treat the auto-generated anonymous
+    # placeholder (…@noemail.com) as "no email" so the bot never promises to follow up
+    # at a fake address — the handoff contact form collects a real one instead.
     customer_email = None
     if customer_id:
         customer_email = customer_repo.get_customer_email(customer_id)
+        if CustomerRepository.is_placeholder_email(customer_email):
+            customer_email = None
 
     # Get available users with proper session handling
     available_users = []

backend/app/api/agent.py

@@ -216,6 +216,8 @@ async def create_agent(
             customization=None,
             transfer_to_human=agent.transfer_to_human or False,
             ask_for_rating=agent.ask_for_rating or False,
+            handoff_collect_email=agent.handoff_collect_email,
+            handoff_collect_name=agent.handoff_collect_name,
             enable_rate_limiting=agent.enable_rate_limiting or False,
             overall_limit_per_ip=agent.overall_limit_per_ip or 100,
             requests_per_sec=agent.requests_per_sec or 1.0,
@@ -316,6 +318,8 @@ async def update_agent(
             customization=customization,
             transfer_to_human=agent.transfer_to_human,
             ask_for_rating=agent.ask_for_rating,
+            handoff_collect_email=agent.handoff_collect_email,
+            handoff_collect_name=agent.handoff_collect_name,
             enable_rate_limiting=agent.enable_rate_limiting,
             overall_limit_per_ip=agent.overall_limit_per_ip,
             requests_per_sec=agent.requests_per_sec,
@@ -374,6 +378,8 @@ async def get_organization_agents(
                 organization_id=agent.organization_id,
                 transfer_to_human=agent.transfer_to_human or False,
                 ask_for_rating=agent.ask_for_rating or False,
+                handoff_collect_email=agent.handoff_collect_email,
+                handoff_collect_name=agent.handoff_collect_name,
                 enable_rate_limiting=agent.enable_rate_limiting or False,
                 overall_limit_per_ip=agent.overall_limit_per_ip or 100,
                 requests_per_sec=agent.requests_per_sec or 1.0,
@@ -568,6 +574,8 @@ async def update_agent_groups(
             customization=customization,
             transfer_to_human=agent.transfer_to_human,
             ask_for_rating=agent.ask_for_rating,
+            handoff_collect_email=agent.handoff_collect_email,
+            handoff_collect_name=agent.handoff_collect_name,
             enable_rate_limiting=agent.enable_rate_limiting,
             overall_limit_per_ip=agent.overall_limit_per_ip,
             requests_per_sec=agent.requests_per_sec,