Prepare for HF Space deployment

.dockerignore

@@ -0,0 +1,187 @@
+# =============================================================================
+# .dockerignore - Exclude files from Docker build context
+# =============================================================================
+# This file ensures clean, efficient Docker builds by excluding unnecessary
+# files from the build context. Smaller context = faster builds.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Python Artifacts
+# -----------------------------------------------------------------------------
+# Bytecode, compiled files, and Python build artifacts
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# -----------------------------------------------------------------------------
+# Virtual Environments
+# -----------------------------------------------------------------------------
+# Local Python virtual environments - Docker creates its own
+therm_venv/
+venv/
+.venv/
+env/
+ENV/
+.env.local
+
+# -----------------------------------------------------------------------------
+# IDE and Editor Files
+# -----------------------------------------------------------------------------
+# Editor-specific settings and temporary files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+*.sublime-project
+*.sublime-workspace
+
+# -----------------------------------------------------------------------------
+# Version Control
+# -----------------------------------------------------------------------------
+# Git history and configuration (not needed in container)
+.git/
+.gitignore
+.gitattributes
+
+# -----------------------------------------------------------------------------
+# Testing and Coverage
+# -----------------------------------------------------------------------------
+# Test files, caches and coverage reports
+tests/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+.nox/
+
+# -----------------------------------------------------------------------------
+# Development Tools
+# -----------------------------------------------------------------------------
+# Linting, type checking, and pre-commit caches
+.pre-commit-config.yaml
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# -----------------------------------------------------------------------------
+# Data and Build Pipeline
+# -----------------------------------------------------------------------------
+# Raw data and build scripts (artifacts downloaded at runtime)
+data/
+scripts/
+
+# -----------------------------------------------------------------------------
+# Frontend
+# -----------------------------------------------------------------------------
+# Next.js frontend has its own Dockerfile
+frontend/
+
+# -----------------------------------------------------------------------------
+# Documentation and Project Files
+# -----------------------------------------------------------------------------
+# Markdown docs, documentation directories, and project-specific files
+*.md
+docs/
+CLAUDE.md
+PROJECT_README.md
+RAG_Chatbot_Plan.md
+IMPLEMENTATION_PLAN.md
+README.rst
+LICENSE
+
+# -----------------------------------------------------------------------------
+# Development Files
+# -----------------------------------------------------------------------------
+# Development-only files not needed in production
+commands
+raw_data/
+
+# -----------------------------------------------------------------------------
+# Environment and Secrets
+# -----------------------------------------------------------------------------
+# Environment files containing secrets (injected at runtime)
+.env
+.env.*
+*.local
+.secrets
+
+# -----------------------------------------------------------------------------
+# Build Artifacts
+# -----------------------------------------------------------------------------
+# Python package build outputs
+dist/
+build/
+*.egg-info/
+*.egg
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+MANIFEST
+
+# -----------------------------------------------------------------------------
+# Jupyter Notebooks
+# -----------------------------------------------------------------------------
+# Notebooks and checkpoints (development only)
+*.ipynb
+.ipynb_checkpoints/
+
+# -----------------------------------------------------------------------------
+# Logs
+# -----------------------------------------------------------------------------
+# Log files generated during development
+*.log
+logs/
+log/
+
+# -----------------------------------------------------------------------------
+# Docker Files
+# -----------------------------------------------------------------------------
+# Prevent recursive Docker context issues
+Dockerfile*
+docker-compose*
+.docker/
+.dockerignore
+
+# -----------------------------------------------------------------------------
+# Miscellaneous
+# -----------------------------------------------------------------------------
+# OS-generated files and other artifacts
+.DS_Store
+Thumbs.db
+*.bak
+*.tmp
+*.temp
+.cache/
+tmp/
+temp/
+
+# -----------------------------------------------------------------------------
+# CI/CD Configuration
+# -----------------------------------------------------------------------------
+# CI configuration files not needed in container
+.github/
+.gitlab-ci.yml
+.travis.yml
+.circleci/
+Makefile
+Taskfile.yml
+
+# =============================================================================
+# IMPORTANT: Files that ARE included (not ignored):
+# - src/           (application source code)
+# - pyproject.toml (Poetry dependency specification)
+# - poetry.lock    (reproducible dependency versions)
+# - py.typed       (type hint marker file)
+# =============================================================================

.gitignore

@@ -152,8 +152,16 @@ cython_debug/
 # User requested exclusions
 IMPLEMENTATION_PLAN.md
 RAG_Chatbot_Plan.md
+PROJECT_README.md
+CLAUDE.md
+commands
 data/
+raw_data/
+tests/
+
+# Hidden directories (except specific ones)
 .*/
 !.gitignore
 !.pre-commit-config.yaml
 !.env.example
+!.dockerignore

CLAUDE.md

@@ -55,7 +55,7 @@ Downloads prebuilt artifacts from HF dataset, serves FastAPI backend with hybrid
 - `src/rag_chatbot/chunking/` - Structure-aware chunking with heading inheritance
 - `src/rag_chatbot/embeddings/` - BGE encoder with float16 storage
 - `src/rag_chatbot/retrieval/` - Hybrid retriever (dense + BM25 with RRF fusion)
-- `src/rag_chatbot/llm/` - Provider registry with fallback: Gemini -> Groq -> DeepSeek
+- `src/rag_chatbot/llm/` - Provider registry with fallback: Gemini -> DeepSeek -> Anthropic
 - `src/rag_chatbot/api/` - FastAPI endpoints with SSE streaming
 - `src/rag_chatbot/qlog/` - Async query logging to HF dataset
 
@@ -77,7 +77,7 @@ Downloads prebuilt artifacts from HF dataset, serves FastAPI backend with hybrid
 ## Environment Variables
 
 Required secrets for deployment:
-- `GEMINI_API_KEY`, `DEEPSEEK_API_KEY`, `GROQ_API_KEY` - LLM providers
+- `GEMINI_API_KEY`, `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY` - LLM providers
 - `HF_TOKEN` - HuggingFace authentication
 
 Key configuration:

Dockerfile

@@ -0,0 +1,654 @@
+# =============================================================================
+# RAG Chatbot Combined Dockerfile - HuggingFace Spaces Production Deployment
+# =============================================================================
+# This is a multi-stage Dockerfile that combines the Next.js frontend and
+# FastAPI backend into a single container, using nginx as a reverse proxy.
+#
+# Architecture Overview:
+#   - External port: 7860 (HuggingFace Spaces requirement)
+#   - nginx: Reverse proxy on port 7860
+#   - Frontend: Next.js standalone on internal port 3000
+#   - Backend: FastAPI/uvicorn on internal port 8000
+#
+# Routing:
+#   - /api/*  -> Backend (FastAPI) on port 8000
+#   - /*      -> Frontend (Next.js) on port 3000
+#
+# Stages (4 total):
+#   1. frontend-deps:    Install npm dependencies
+#   2. frontend-builder: Build Next.js standalone output
+#   3. backend-builder:  Export Python dependencies via Poetry
+#   4. runtime:          Final image with nginx + Node.js + Python
+#
+# Target image size: < 1.5GB (no torch, no build dependencies)
+# Base image: python:3.11-slim (Debian-based for nginx availability)
+#
+# Build command:
+#   docker build -t rag-chatbot .
+#
+# Run command:
+#   docker run -p 7860:7860 \
+#     -e GEMINI_API_KEY=xxx \
+#     -e HF_TOKEN=xxx \
+#     rag-chatbot
+#
+# =============================================================================
+
+
+# =============================================================================
+# STAGE 1: FRONTEND DEPENDENCIES
+# =============================================================================
+# Purpose: Install all npm dependencies in an isolated stage
+# This stage uses Node.js Alpine for minimal footprint during dependency install.
+# The node_modules are passed to the builder stage; this stage is discarded.
+# =============================================================================
+FROM node:22-alpine AS frontend-deps
+
+# -----------------------------------------------------------------------------
+# Install System Dependencies
+# -----------------------------------------------------------------------------
+# libc6-compat: Required for some native Node.js modules that expect glibc
+# Alpine uses musl libc by default, and this compatibility layer helps with
+# packages that have native bindings compiled against glibc.
+# -----------------------------------------------------------------------------
+RUN apk add --no-cache libc6-compat
+
+# -----------------------------------------------------------------------------
+# Set Working Directory
+# -----------------------------------------------------------------------------
+WORKDIR /app
+
+# -----------------------------------------------------------------------------
+# Copy Package Files
+# -----------------------------------------------------------------------------
+# Copy only package.json and package-lock.json for optimal layer caching.
+# This layer is cached until these files change, avoiding unnecessary
+# reinstalls when only source code changes.
+# -----------------------------------------------------------------------------
+COPY frontend/package.json frontend/package-lock.json ./
+
+# -----------------------------------------------------------------------------
+# Install Dependencies
+# -----------------------------------------------------------------------------
+# npm ci (Clean Install) is preferred because:
+#   - Faster: Uses exact versions from lock file
+#   - Reproducible: Guarantees identical dependency tree
+#   - Strict: Fails if lock file is out of sync
+#   - Clean: Removes existing node_modules before install
+#
+# --prefer-offline: Use cached packages when available (faster in CI/CD)
+# Clean npm cache after install to reduce layer size.
+# -----------------------------------------------------------------------------
+RUN npm ci --prefer-offline && npm cache clean --force
+
+
+# =============================================================================
+# STAGE 2: FRONTEND BUILDER
+# =============================================================================
+# Purpose: Build the Next.js application with standalone output
+# This stage compiles TypeScript, bundles assets, and creates the minimal
+# standalone server that will be copied to the runtime image.
+# =============================================================================
+FROM node:22-alpine AS frontend-builder
+
+# -----------------------------------------------------------------------------
+# Set Working Directory
+# -----------------------------------------------------------------------------
+WORKDIR /app
+
+# -----------------------------------------------------------------------------
+# Copy Dependencies from frontend-deps Stage
+# -----------------------------------------------------------------------------
+# Reuse the installed node_modules to avoid reinstalling.
+# This ensures consistent dependencies across stages.
+# -----------------------------------------------------------------------------
+COPY --from=frontend-deps /app/node_modules ./node_modules
+
+# -----------------------------------------------------------------------------
+# Copy Frontend Source Code
+# -----------------------------------------------------------------------------
+# Copy all frontend files needed for the build.
+# The .dockerignore in frontend/ should exclude node_modules, .next, etc.
+# -----------------------------------------------------------------------------
+COPY frontend/ .
+
+# -----------------------------------------------------------------------------
+# Build-Time Environment Variables
+# -----------------------------------------------------------------------------
+# NEXT_PUBLIC_API_URL: Empty string = same-origin requests via nginx
+#   The frontend will use relative URLs like /api/query, and nginx will
+#   proxy these to the backend. This avoids CORS and simplifies deployment.
+#
+# NEXT_TELEMETRY_DISABLED: Prevent telemetry during build
+#
+# NODE_ENV: Production mode for optimized output
+# -----------------------------------------------------------------------------
+ENV NEXT_PUBLIC_API_URL=""
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV NODE_ENV=production
+
+# -----------------------------------------------------------------------------
+# Build the Application
+# -----------------------------------------------------------------------------
+# Run Next.js production build. The --webpack flag ensures compatibility
+# with the custom webpack configuration in next.config.ts.
+#
+# Output structure:
+#   .next/standalone/ - Minimal Node.js server with bundled deps
+#   .next/static/     - Static assets (JS, CSS chunks)
+#   public/           - Static files (images, fonts)
+# -----------------------------------------------------------------------------
+RUN npx next build --webpack
+
+
+# =============================================================================
+# STAGE 3: BACKEND BUILDER
+# =============================================================================
+# Purpose: Use Poetry to export serve-only dependencies to requirements.txt
+# This stage is discarded after generating the requirements file.
+# We don't need torch, sentence-transformers, or build tools in production.
+# =============================================================================
+FROM python:3.11-slim AS backend-builder
+
+# -----------------------------------------------------------------------------
+# Install Poetry
+# -----------------------------------------------------------------------------
+# Poetry manages Python dependencies. We use the official installer for
+# proper isolation. The version is pinned for reproducible builds.
+# -----------------------------------------------------------------------------
+ENV POETRY_VERSION=1.8.2
+ENV POETRY_HOME=/opt/poetry
+ENV PATH="${POETRY_HOME}/bin:${PATH}"
+
+# Install Poetry using the official installer script
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl \
+    && curl -sSL https://install.python-poetry.org | python3 - \
+    && apt-get purge -y curl \
+    && apt-get autoremove -y \
+    && rm -rf /var/lib/apt/lists/*
+
+# -----------------------------------------------------------------------------
+# Set Working Directory
+# -----------------------------------------------------------------------------
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# Copy Dependency Files
+# -----------------------------------------------------------------------------
+# Copy only pyproject.toml and poetry.lock for dependency resolution.
+# This layer is cached until these files change.
+# -----------------------------------------------------------------------------
+COPY pyproject.toml poetry.lock ./
+
+# -----------------------------------------------------------------------------
+# Export Requirements
+# -----------------------------------------------------------------------------
+# Export only main + serve dependencies (no dense, build, or dev groups).
+#
+# INCLUDED:
+#   - Core: pydantic, numpy, httpx, tiktoken, rank-bm25, faiss-cpu, etc.
+#   - Serve: fastapi, uvicorn, sse-starlette
+#
+# EXCLUDED:
+#   - Dense: torch, sentence-transformers (too large, not needed for CPU serving)
+#   - Build: pymupdf4llm, pyarrow, datasets (offline pipeline only)
+#   - Dev: mypy, ruff, pytest (development tools only)
+#
+# --without-hashes: Required for pip compatibility
+# -----------------------------------------------------------------------------
+RUN poetry export --only main,serve --without-hashes -f requirements.txt -o requirements.txt
+
+
+# =============================================================================
+# STAGE 4: RUNTIME
+# =============================================================================
+# Purpose: Final production image with nginx, Node.js, and Python
+# This image serves both frontend and backend through nginx reverse proxy.
+#
+# Components:
+#   - nginx:   Reverse proxy on port 7860
+#   - Node.js: Runs Next.js standalone server on port 3000
+#   - Python:  Runs FastAPI/uvicorn on port 8000
+#
+# Security:
+#   - Non-root nginx worker processes
+#   - Minimal installed packages
+#   - No build tools or development dependencies
+# =============================================================================
+FROM python:3.11-slim AS runtime
+
+# -----------------------------------------------------------------------------
+# Environment Variables
+# -----------------------------------------------------------------------------
+# PYTHONDONTWRITEBYTECODE: Don't write .pyc files (reduces image size)
+# PYTHONUNBUFFERED: Ensure logs appear immediately in container output
+# PYTHONPATH: Add src/ to Python path for module imports
+# NODE_ENV: Production mode for Node.js
+# -----------------------------------------------------------------------------
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app/backend/src
+ENV NODE_ENV=production
+
+# -----------------------------------------------------------------------------
+# Install System Dependencies
+# -----------------------------------------------------------------------------
+# nginx:        Reverse proxy server
+# curl:         Health checks
+# supervisor:   Process manager to run multiple services
+# gnupg:        Required for adding NodeSource GPG key
+# ca-certificates: SSL certificates for HTTPS
+#
+# Node.js 22.x is installed from NodeSource repository for Debian.
+# This provides an up-to-date Node.js version compatible with Next.js.
+# -----------------------------------------------------------------------------
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        nginx \
+        curl \
+        supervisor \
+        gnupg \
+        ca-certificates \
+    # Add NodeSource repository for Node.js 22.x
+    && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    # Clean up apt cache to reduce image size
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# -----------------------------------------------------------------------------
+# Create Application User
+# -----------------------------------------------------------------------------
+# Create a non-root user for running the application services.
+# Using UID/GID 1000 for compatibility with common host systems.
+#
+# Note: nginx master process runs as root (required for port binding),
+# but worker processes run as www-data (configured in nginx.conf).
+# -----------------------------------------------------------------------------
+RUN groupadd --gid 1000 appgroup \
+    && useradd --uid 1000 --gid appgroup --shell /bin/false --no-create-home appuser
+
+# -----------------------------------------------------------------------------
+# Set Working Directory
+# -----------------------------------------------------------------------------
+WORKDIR /app
+
+# -----------------------------------------------------------------------------
+# Copy Python Requirements from Backend Builder
+# -----------------------------------------------------------------------------
+# The requirements.txt was generated by Poetry and contains only serve deps.
+# -----------------------------------------------------------------------------
+COPY --from=backend-builder /build/requirements.txt ./requirements.txt
+
+# -----------------------------------------------------------------------------
+# Install Python Dependencies
+# -----------------------------------------------------------------------------
+# Install all serve dependencies using pip.
+# Flags:
+#   --no-cache-dir: Don't cache packages (reduces image size)
+#   --no-compile:   Don't compile .py to .pyc (PYTHONDONTWRITEBYTECODE handles this)
+# -----------------------------------------------------------------------------
+RUN pip install --no-cache-dir --no-compile -r requirements.txt
+
+# -----------------------------------------------------------------------------
+# Copy Backend Source Code
+# -----------------------------------------------------------------------------
+# Copy the Python source code to /app/backend/src/
+# PYTHONPATH=/app/backend/src allows importing rag_chatbot module
+# -----------------------------------------------------------------------------
+COPY src/ /app/backend/src/
+
+# -----------------------------------------------------------------------------
+# Copy Frontend Standalone Build
+# -----------------------------------------------------------------------------
+# Copy the Next.js standalone output from the frontend-builder stage.
+# Structure:
+#   /app/frontend/server.js       - Next.js production server
+#   /app/frontend/.next/          - Compiled application
+#   /app/frontend/node_modules/   - Minimal runtime dependencies
+#   /app/frontend/public/         - Static assets
+# -----------------------------------------------------------------------------
+COPY --from=frontend-builder /app/public /app/frontend/public
+COPY --from=frontend-builder /app/.next/standalone /app/frontend
+COPY --from=frontend-builder /app/.next/static /app/frontend/.next/static
+
+# -----------------------------------------------------------------------------
+# Create nginx Configuration
+# -----------------------------------------------------------------------------
+# Configure nginx as reverse proxy:
+#   - Listen on port 7860 (HuggingFace Spaces requirement)
+#   - Proxy /api/* requests to backend on port 8000
+#   - Proxy all other requests to frontend on port 3000
+#   - Enable gzip compression for text content
+#   - Configure appropriate timeouts for SSE streaming
+# -----------------------------------------------------------------------------
+RUN cat > /etc/nginx/nginx.conf << 'EOF'
+# =============================================================================
+# nginx Configuration for RAG Chatbot
+# =============================================================================
+# This configuration sets up nginx as a reverse proxy for the combined
+# frontend (Next.js) and backend (FastAPI) application.
+# =============================================================================
+
+# Run nginx master process as root (required for port binding)
+# Worker processes run as www-data for security
+user www-data;
+
+# Auto-detect number of CPU cores for worker processes
+worker_processes auto;
+
+# Error log location and level
+error_log /var/log/nginx/error.log warn;
+
+# PID file location
+pid /var/run/nginx.pid;
+
+# -----------------------------------------------------------------------------
+# Events Configuration
+# -----------------------------------------------------------------------------
+events {
+    # Maximum simultaneous connections per worker
+    worker_connections 1024;
+
+    # Use epoll for better performance on Linux
+    use epoll;
+
+    # Accept multiple connections at once
+    multi_accept on;
+}
+
+# -----------------------------------------------------------------------------
+# HTTP Configuration
+# -----------------------------------------------------------------------------
+http {
+    # Include MIME types for proper content-type headers
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    # Logging format
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" "$http_x_forwarded_for"';
+
+    access_log /var/log/nginx/access.log main;
+
+    # Performance optimizations
+    sendfile on;
+    tcp_nopush on;
+    tcp_nodelay on;
+
+    # Keep-alive settings
+    keepalive_timeout 65;
+
+    # Gzip compression for text content
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_types text/plain text/css text/xml application/json application/javascript
+               application/xml application/xml+rss text/javascript application/x-javascript;
+
+    # Upstream definitions for backend and frontend
+    upstream backend {
+        server 127.0.0.1:8000;
+        keepalive 32;
+    }
+
+    upstream frontend {
+        server 127.0.0.1:3000;
+        keepalive 32;
+    }
+
+    # -------------------------------------------------------------------------
+    # Main Server Block
+    # -------------------------------------------------------------------------
+    server {
+        # Listen on port 7860 (HuggingFace Spaces requirement)
+        listen 7860;
+        server_name _;
+
+        # Client body size limit (for potential file uploads)
+        client_max_body_size 10M;
+
+        # ---------------------------------------------------------------------
+        # Backend API Routes
+        # ---------------------------------------------------------------------
+        # Proxy all /api/* requests to the FastAPI backend
+        # This includes /api/query, /api/health, etc.
+        # ---------------------------------------------------------------------
+        location /api/ {
+            proxy_pass http://backend/;
+            proxy_http_version 1.1;
+
+            # Headers for proper proxying
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+
+            # Connection upgrade for WebSocket (if needed in future)
+            proxy_set_header Connection "";
+
+            # Timeouts for long-running requests (SSE streaming)
+            # These are generous to support streaming LLM responses
+            proxy_connect_timeout 60s;
+            proxy_send_timeout 300s;
+            proxy_read_timeout 300s;
+
+            # Disable buffering for SSE (Server-Sent Events)
+            # This ensures streaming responses are sent immediately
+            proxy_buffering off;
+            proxy_cache off;
+
+            # SSE-specific headers
+            proxy_set_header Accept-Encoding "";
+        }
+
+        # ---------------------------------------------------------------------
+        # Health Check Endpoint (direct to backend)
+        # ---------------------------------------------------------------------
+        # Allow direct access to health endpoints for container orchestration
+        # ---------------------------------------------------------------------
+        location /health {
+            proxy_pass http://backend/health;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header Connection "";
+        }
+
+        # ---------------------------------------------------------------------
+        # Frontend Routes (catch-all)
+        # ---------------------------------------------------------------------
+        # Proxy all other requests to the Next.js frontend
+        # This includes pages, static assets, and _next/* resources
+        # ---------------------------------------------------------------------
+        location / {
+            proxy_pass http://frontend;
+            proxy_http_version 1.1;
+
+            # Headers for proper proxying
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+
+            # Standard timeouts for frontend
+            proxy_connect_timeout 60s;
+            proxy_send_timeout 60s;
+            proxy_read_timeout 60s;
+        }
+
+        # ---------------------------------------------------------------------
+        # Static Files Caching
+        # ---------------------------------------------------------------------
+        # Cache static assets with long expiry for performance
+        # Next.js includes content hashes in filenames, so this is safe
+        # ---------------------------------------------------------------------
+        location /_next/static {
+            proxy_pass http://frontend;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header Connection "";
+
+            # Cache static assets for 1 year (immutable content-hashed files)
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+        }
+    }
+}
+EOF
+
+# -----------------------------------------------------------------------------
+# Create Supervisor Configuration
+# -----------------------------------------------------------------------------
+# Supervisor manages multiple processes in a single container:
+#   - nginx: Reverse proxy (master process)
+#   - frontend: Next.js server (node process)
+#   - backend: FastAPI/uvicorn (python process)
+#
+# All processes are started together and supervisor monitors their health.
+# If any process crashes, supervisor will restart it automatically.
+# -----------------------------------------------------------------------------
+RUN cat > /etc/supervisor/conf.d/supervisord.conf << 'EOF'
+; =============================================================================
+; Supervisor Configuration for RAG Chatbot
+; =============================================================================
+; Manages nginx, frontend (Next.js), and backend (FastAPI) processes.
+; All processes run in the foreground (nodaemon=true).
+; =============================================================================
+
+[supervisord]
+nodaemon=true
+user=root
+logfile=/var/log/supervisor/supervisord.log
+pidfile=/var/run/supervisord.pid
+childlogdir=/var/log/supervisor
+
+; -----------------------------------------------------------------------------
+; nginx - Reverse Proxy
+; -----------------------------------------------------------------------------
+; nginx master process must run as root for port binding.
+; Worker processes run as www-data (configured in nginx.conf).
+; -----------------------------------------------------------------------------
+[program:nginx]
+command=/usr/sbin/nginx -g "daemon off;"
+autostart=true
+autorestart=true
+priority=10
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+
+; -----------------------------------------------------------------------------
+; Frontend - Next.js Server
+; -----------------------------------------------------------------------------
+; Runs the Next.js standalone server on port 3000.
+; The standalone server is minimal and includes only required dependencies.
+; -----------------------------------------------------------------------------
+[program:frontend]
+command=node /app/frontend/server.js
+directory=/app/frontend
+autostart=true
+autorestart=true
+priority=20
+user=appuser
+environment=NODE_ENV="production",PORT="3000",HOSTNAME="0.0.0.0"
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+
+; -----------------------------------------------------------------------------
+; Backend - FastAPI/Uvicorn Server
+; -----------------------------------------------------------------------------
+; Runs the FastAPI application on port 8000.
+; Uses the app factory pattern for proper initialization.
+;
+; LLM Provider API Keys (inherited from container environment):
+;   - GEMINI_API_KEY:    Google Gemini API (primary provider)
+;   - DEEPSEEK_API_KEY:  DeepSeek API (fallback provider)
+;   - ANTHROPIC_API_KEY: Anthropic API (fallback provider)
+;   - GROQ_API_KEY:      Groq API (optional provider)
+;   - HF_TOKEN:          HuggingFace token for dataset access and logging
+;
+; Note: The environment= directive ADDS to the inherited environment.
+; API keys set via "docker run -e" or HuggingFace Spaces secrets are
+; automatically passed through to this process without explicit listing.
+; -----------------------------------------------------------------------------
+[program:backend]
+command=python -m uvicorn rag_chatbot.api.main:create_app --factory --host 0.0.0.0 --port 8000
+directory=/app/backend
+autostart=true
+autorestart=true
+priority=30
+user=appuser
+environment=PYTHONPATH="/app/backend/src",PYTHONDONTWRITEBYTECODE="1",PYTHONUNBUFFERED="1"
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+EOF
+
+# -----------------------------------------------------------------------------
+# Create Log Directories
+# -----------------------------------------------------------------------------
+# Create directories for nginx and supervisor logs with proper permissions.
+# -----------------------------------------------------------------------------
+RUN mkdir -p /var/log/nginx /var/log/supervisor \
+    && chown -R www-data:www-data /var/log/nginx \
+    && chmod -R 755 /var/log/supervisor
+
+# -----------------------------------------------------------------------------
+# Set Permissions
+# -----------------------------------------------------------------------------
+# Ensure appuser can read application files and write to necessary locations.
+# nginx runs as www-data, frontend/backend run as appuser.
+# -----------------------------------------------------------------------------
+RUN chown -R appuser:appgroup /app/frontend /app/backend
+
+# -----------------------------------------------------------------------------
+# Expose Port
+# -----------------------------------------------------------------------------
+# HuggingFace Spaces expects the application to listen on port 7860.
+# All traffic flows through nginx on this port.
+# -----------------------------------------------------------------------------
+EXPOSE 7860
+
+# -----------------------------------------------------------------------------
+# Health Check
+# -----------------------------------------------------------------------------
+# Docker health check for container orchestration.
+# Checks the /health endpoint via nginx, which proxies to the backend.
+#
+# Options:
+#   --interval=30s:    Check every 30 seconds
+#   --timeout=10s:     Wait up to 10 seconds for response
+#   --start-period=60s: Grace period for all services to start
+#   --retries=3:       Mark unhealthy after 3 consecutive failures
+#
+# Note: Using /health/ready because it returns 200 when ready, 503 when loading.
+# The start-period is longer (60s) because we need nginx + frontend + backend
+# to all be ready before the health check can pass.
+# -----------------------------------------------------------------------------
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD curl --fail http://localhost:7860/health/ready || exit 1
+
+# -----------------------------------------------------------------------------
+# Entrypoint
+# -----------------------------------------------------------------------------
+# Start supervisor, which manages all three services:
+#   1. nginx (reverse proxy on port 7860)
+#   2. frontend (Next.js on port 3000)
+#   3. backend (FastAPI on port 8000)
+#
+# Supervisor runs in the foreground (nodaemon=true) as the main process.
+# It monitors all child processes and restarts them if they crash.
+#
+# Environment variables (GEMINI_API_KEY, HF_TOKEN, etc.) should be passed
+# at runtime via docker run -e or configured in HuggingFace Spaces secrets.
+# Supervisor passes them through to the backend process.
+# -----------------------------------------------------------------------------
+CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

Dockerfile.backend

@@ -0,0 +1,225 @@
+# =============================================================================
+# RAG Chatbot Backend - Production Dockerfile
+# =============================================================================
+# This is a multi-stage Dockerfile optimized for HuggingFace Spaces deployment.
+# It creates a minimal runtime image that excludes heavy build-time dependencies
+# like torch, sentence-transformers, and pyarrow.
+#
+# Architecture:
+#   Stage 1 (builder): Installs Poetry and exports serve-only dependencies
+#   Stage 2 (runtime): Minimal image with only runtime dependencies
+#
+# Target image size: < 2GB
+# Base image: python:3.11-slim (Debian-based, ~150MB)
+# =============================================================================
+
+# =============================================================================
+# STAGE 1: BUILDER
+# =============================================================================
+# Purpose: Use Poetry to export a clean requirements.txt for serve dependencies
+# This stage is discarded after build, so Poetry overhead doesn't affect runtime
+# =============================================================================
+FROM python:3.11-slim AS builder
+
+# -----------------------------------------------------------------------------
+# Install Poetry
+# -----------------------------------------------------------------------------
+# Poetry is used to manage dependencies and export requirements.txt
+# We pin the version for reproducible builds
+# Using pipx isolation avoids polluting the system Python
+# -----------------------------------------------------------------------------
+ENV POETRY_VERSION=1.8.2
+ENV POETRY_HOME=/opt/poetry
+ENV PATH="${POETRY_HOME}/bin:${PATH}"
+
+# Install Poetry using the official installer script
+# This method is recommended over pip install for isolation
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl \
+    && curl -sSL https://install.python-poetry.org | python3 - \
+    && apt-get purge -y curl \
+    && apt-get autoremove -y \
+    && rm -rf /var/lib/apt/lists/*
+
+# -----------------------------------------------------------------------------
+# Set Working Directory
+# -----------------------------------------------------------------------------
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# Copy Dependency Files
+# -----------------------------------------------------------------------------
+# Copy only the files needed for dependency resolution
+# This layer is cached until pyproject.toml or poetry.lock changes
+# -----------------------------------------------------------------------------
+COPY pyproject.toml poetry.lock ./
+
+# -----------------------------------------------------------------------------
+# Export Requirements
+# -----------------------------------------------------------------------------
+# Export only the serve group dependencies to requirements.txt
+# Flags explained:
+#   --only main,serve  : Include core deps + serve group (FastAPI, uvicorn, SSE)
+#   --without-hashes   : Omit hashes for compatibility with pip install
+#   -f requirements.txt: Output to requirements.txt file
+#
+# IMPORTANT: This excludes:
+#   - dense group (torch, sentence-transformers) - not needed at runtime
+#   - build group (pymupdf4llm, pyarrow, etc.) - offline pipeline only
+#   - dev group (mypy, ruff, pytest) - development tools only
+# -----------------------------------------------------------------------------
+RUN poetry export --only main,serve --without-hashes -f requirements.txt -o requirements.txt
+
+# =============================================================================
+# STAGE 2: RUNTIME
+# =============================================================================
+# Purpose: Minimal production image with only serve dependencies
+# This is the final image that runs on HuggingFace Spaces
+# =============================================================================
+FROM python:3.11-slim AS runtime
+
+# -----------------------------------------------------------------------------
+# Environment Variables
+# -----------------------------------------------------------------------------
+# PYTHONDONTWRITEBYTECODE: Prevents Python from writing .pyc bytecode files
+#   - Reduces image size slightly
+#   - Avoids permission issues with read-only filesystems
+#
+# PYTHONUNBUFFERED: Forces stdout/stderr to be unbuffered
+#   - Ensures log messages appear immediately in container logs
+#   - Critical for debugging and monitoring in production
+#
+# PYTHONPATH: Adds src/ to Python's module search path
+#   - Allows importing rag_chatbot package without installation
+#   - Matches the src layout convention used in the project
+# -----------------------------------------------------------------------------
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app/src
+
+# -----------------------------------------------------------------------------
+# Create Non-Root User
+# -----------------------------------------------------------------------------
+# Security best practice: Run the application as a non-root user
+# This limits the impact of potential security vulnerabilities
+#
+# - Create group 'appgroup' with GID 1000
+# - Create user 'appuser' with UID 1000 in that group
+# - No home directory needed (-M), no login shell (-s /bin/false)
+# -----------------------------------------------------------------------------
+RUN groupadd --gid 1000 appgroup \
+    && useradd --uid 1000 --gid appgroup --shell /bin/false --no-create-home appuser
+
+# -----------------------------------------------------------------------------
+# Install System Dependencies
+# -----------------------------------------------------------------------------
+# Install curl for health checks and clean up apt cache to reduce image size
+# The health check endpoint will be probed using curl
+# -----------------------------------------------------------------------------
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# -----------------------------------------------------------------------------
+# Set Working Directory
+# -----------------------------------------------------------------------------
+WORKDIR /app
+
+# -----------------------------------------------------------------------------
+# Copy Requirements from Builder Stage
+# -----------------------------------------------------------------------------
+# The requirements.txt was generated by Poetry in the builder stage
+# It contains only the serve dependencies (no torch, no build deps)
+# -----------------------------------------------------------------------------
+COPY --from=builder /build/requirements.txt .
+
+# -----------------------------------------------------------------------------
+# Install Python Dependencies
+# -----------------------------------------------------------------------------
+# Install all serve dependencies using pip
+# Flags explained:
+#   --no-cache-dir  : Don't cache pip packages (reduces image size)
+#   --no-compile    : Don't compile .py to .pyc (PYTHONDONTWRITEBYTECODE=1 handles this)
+#   -r requirements.txt : Install from the exported requirements
+#
+# This installs:
+#   - Core deps: pydantic, numpy, httpx, tiktoken, rank-bm25, faiss-cpu, etc.
+#   - Serve deps: fastapi, uvicorn, sse-starlette
+#
+# This does NOT install:
+#   - torch, sentence-transformers (dense group)
+#   - pymupdf4llm, pyarrow, datasets (build group)
+#   - mypy, ruff, pytest (dev group)
+# -----------------------------------------------------------------------------
+RUN pip install --no-cache-dir --no-compile -r requirements.txt
+
+# -----------------------------------------------------------------------------
+# Copy Application Source Code
+# -----------------------------------------------------------------------------
+# Copy the source code from the host to the container
+# The src/rag_chatbot/ directory contains the application package
+# PYTHONPATH=/app/src allows Python to find the rag_chatbot module
+# -----------------------------------------------------------------------------
+COPY src/ /app/src/
+
+# -----------------------------------------------------------------------------
+# Set Ownership
+# -----------------------------------------------------------------------------
+# Change ownership of the application directory to the non-root user
+# This ensures the application can read its own files when running as appuser
+# -----------------------------------------------------------------------------
+RUN chown -R appuser:appgroup /app
+
+# -----------------------------------------------------------------------------
+# Switch to Non-Root User
+# -----------------------------------------------------------------------------
+# From this point on, all commands run as appuser (UID 1000)
+# This is the user that will run the application in production
+# -----------------------------------------------------------------------------
+USER appuser
+
+# -----------------------------------------------------------------------------
+# Expose Port
+# -----------------------------------------------------------------------------
+# HuggingFace Spaces expects the application to listen on port 7860
+# This documents the port but doesn't actually publish it (done at runtime)
+# -----------------------------------------------------------------------------
+EXPOSE 7860
+
+# -----------------------------------------------------------------------------
+# Health Check
+# -----------------------------------------------------------------------------
+# Docker health check configuration for container orchestration
+# This allows Docker/HF Spaces to know if the application is healthy
+#
+# --interval=30s  : Check every 30 seconds
+# --timeout=10s   : Wait up to 10 seconds for response
+# --start-period=40s : Grace period for startup (resources load lazily on first request)
+# --retries=3     : Mark unhealthy after 3 consecutive failures
+#
+# Health endpoint paths:
+#   /health/ready - Simple readiness probe (200 OK when ready, 503 when loading)
+#   /health/health - Full health status with version and component details
+#
+# Note: Using /health/ready because it returns 200/503 which curl --fail can detect.
+# The endpoint returns 503 while resources are loading, which is expected during
+# the start period. Once resources load (on first request), it returns 200.
+# -----------------------------------------------------------------------------
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+    CMD curl --fail http://localhost:7860/health/ready || exit 1
+
+# -----------------------------------------------------------------------------
+# Entrypoint
+# -----------------------------------------------------------------------------
+# Start the FastAPI application using uvicorn ASGI server
+# Command breakdown:
+#   uvicorn                    : ASGI server for async Python web apps
+#   rag_chatbot.api.main:create_app : Module path to the app factory function
+#   --factory                  : create_app is a factory function, not an app instance
+#   --host 0.0.0.0             : Listen on all network interfaces (required for containers)
+#   --port 7860                : HuggingFace Spaces default port
+#
+# Using CMD allows the command to be overridden for debugging if needed
+# Using exec form (JSON array) ensures proper signal handling
+# -----------------------------------------------------------------------------
+CMD ["uvicorn", "rag_chatbot.api.main:create_app", "--factory", "--host", "0.0.0.0", "--port", "7860"]

Dockerfile.frontend

@@ -0,0 +1,353 @@
+# =============================================================================
+# RAG Chatbot Frontend - Production Dockerfile
+# =============================================================================
+# This is a multi-stage Dockerfile optimized for production deployment of the
+# Next.js frontend application on HuggingFace Spaces or any Docker-based hosting.
+#
+# Architecture (3 stages):
+#   Stage 1 (deps):    Install all dependencies using npm ci
+#   Stage 2 (builder): Build the Next.js application with standalone output
+#   Stage 3 (runner):  Minimal production image with only runtime files
+#
+# Key optimizations:
+#   - Alpine-based images for minimal size
+#   - Multi-stage build eliminates build-time dependencies from final image
+#   - Standalone output mode bundles only required node_modules
+#   - Gzip compression enabled via Node.js flags
+#   - Non-root user for security
+#
+# Target image size: < 500MB
+# Base image: node:22-alpine (~50MB base)
+#
+# Build command:
+#   docker build -f Dockerfile.frontend -t frontend ./frontend
+#
+# Run command:
+#   docker run -p 3000:3000 frontend
+#
+# =============================================================================
+
+
+# =============================================================================
+# STAGE 1: DEPENDENCIES
+# =============================================================================
+# Purpose: Install all npm dependencies in an isolated stage
+# This stage installs both production and dev dependencies because we need
+# devDependencies (TypeScript, Tailwind, etc.) to build the application.
+# The final image will not include these - only the standalone output.
+# =============================================================================
+FROM node:22-alpine AS deps
+
+# -----------------------------------------------------------------------------
+# Install System Dependencies
+# -----------------------------------------------------------------------------
+# libc6-compat: Required for some native Node.js modules that expect glibc
+# Alpine uses musl libc by default, and this compatibility layer helps with
+# packages that have native bindings compiled against glibc.
+# -----------------------------------------------------------------------------
+RUN apk add --no-cache libc6-compat
+
+# -----------------------------------------------------------------------------
+# Set Working Directory
+# -----------------------------------------------------------------------------
+# Use /app as the standard working directory for the application
+# -----------------------------------------------------------------------------
+WORKDIR /app
+
+# -----------------------------------------------------------------------------
+# Copy Package Files
+# -----------------------------------------------------------------------------
+# Copy only package.json and package-lock.json first for better layer caching.
+# Docker caches this layer until these files change, avoiding unnecessary
+# reinstalls when only source code changes.
+# -----------------------------------------------------------------------------
+COPY package.json package-lock.json ./
+
+# -----------------------------------------------------------------------------
+# Install Dependencies
+# -----------------------------------------------------------------------------
+# npm ci (Clean Install) is used instead of npm install because:
+#   - It's faster: skips package resolution, uses exact versions from lock file
+#   - It's reproducible: guarantees exact same dependency tree
+#   - It's stricter: fails if lock file is out of sync with package.json
+#   - It clears node_modules before install: ensures clean state
+#
+# --prefer-offline: Use cached packages when available (faster in CI/CD)
+#
+# After install, clean npm cache to reduce layer size.
+# -----------------------------------------------------------------------------
+RUN npm ci --prefer-offline && npm cache clean --force
+
+
+# =============================================================================
+# STAGE 2: BUILDER
+# =============================================================================
+# Purpose: Build the Next.js application for production
+# This stage:
+#   1. Copies dependencies from the deps stage
+#   2. Copies source code
+#   3. Runs the production build
+#   4. Outputs standalone server + static assets
+#
+# The standalone output (enabled in next.config.ts) creates:
+#   - .next/standalone/ - Minimal Node.js server with bundled dependencies
+#   - .next/static/     - Static assets (JS, CSS chunks)
+#   - public/           - Public static files (images, fonts, etc.)
+# =============================================================================
+FROM node:22-alpine AS builder
+
+# -----------------------------------------------------------------------------
+# Set Working Directory
+# -----------------------------------------------------------------------------
+WORKDIR /app
+
+# -----------------------------------------------------------------------------
+# Copy Dependencies from deps Stage
+# -----------------------------------------------------------------------------
+# Copy the fully installed node_modules from the deps stage.
+# This is faster than reinstalling and ensures consistent dependencies.
+# -----------------------------------------------------------------------------
+COPY --from=deps /app/node_modules ./node_modules
+
+# -----------------------------------------------------------------------------
+# Copy Source Code and Configuration
+# -----------------------------------------------------------------------------
+# Copy all source files needed for the build.
+# Note: Files matching patterns in .dockerignore are excluded automatically.
+#
+# The key files needed:
+#   - src/           : Application source code (pages, components, etc.)
+#   - public/        : Static assets to be copied to output
+#   - package.json   : Project metadata and scripts
+#   - next.config.ts : Next.js configuration (standalone output enabled)
+#   - tsconfig.json  : TypeScript configuration
+#   - postcss.config.mjs, tailwind config : CSS processing
+# -----------------------------------------------------------------------------
+COPY . .
+
+# -----------------------------------------------------------------------------
+# Build-Time Environment Variables
+# -----------------------------------------------------------------------------
+# NEXT_PUBLIC_API_URL: The base URL for API requests
+#   - Set at build time because NEXT_PUBLIC_* vars are inlined into the bundle
+#   - Empty string = same-origin requests (frontend and backend on same domain)
+#   - Set to absolute URL if backend is on different domain
+#
+# NEXT_TELEMETRY_DISABLED: Disable Next.js anonymous telemetry
+#   - Prevents outbound network requests during build
+#   - Recommended for CI/CD and production environments
+#
+# NODE_ENV: Set to production for optimized build output
+#   - Enables production optimizations (minification, dead code elimination)
+#   - Disables development-only features and warnings
+# -----------------------------------------------------------------------------
+ENV NEXT_PUBLIC_API_URL=""
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV NODE_ENV=production
+
+# -----------------------------------------------------------------------------
+# Build the Application
+# -----------------------------------------------------------------------------
+# Run the Next.js production build using webpack bundler.
+#
+# Note: Next.js 16+ uses Turbopack by default, but we use --webpack flag here
+# because the next.config.ts contains a webpack configuration block.
+# Using webpack ensures compatibility with existing configuration.
+#
+# This command will:
+#   1. Compile TypeScript to JavaScript
+#   2. Bundle and optimize client-side code using webpack
+#   3. Pre-render static pages (if any)
+#   4. Generate standalone output in .next/standalone/
+#   5. Generate static assets in .next/static/
+#
+# The standalone output includes:
+#   - server.js: Minimal Node.js server
+#   - node_modules: Only production dependencies needed by the server
+#   - Required Next.js internal files
+# -----------------------------------------------------------------------------
+RUN npx next build --webpack
+
+
+# =============================================================================
+# STAGE 3: RUNNER (Production)
+# =============================================================================
+# Purpose: Minimal production image containing only what's needed to run
+# This is the final image that will be deployed.
+#
+# Size optimization:
+#   - Alpine base image (~50MB vs ~350MB for Debian)
+#   - Only standalone output copied (no full node_modules)
+#   - No build tools, devDependencies, or source TypeScript
+#
+# Security:
+#   - Runs as non-root user (nextjs)
+#   - Minimal attack surface
+#   - No unnecessary packages or tools
+# =============================================================================
+FROM node:22-alpine AS runner
+
+# -----------------------------------------------------------------------------
+# Set Working Directory
+# -----------------------------------------------------------------------------
+WORKDIR /app
+
+# -----------------------------------------------------------------------------
+# Environment Variables for Production
+# -----------------------------------------------------------------------------
+# NODE_ENV: production
+#   - Next.js uses this to enable production optimizations
+#   - Disables development-only features
+#
+# NEXT_TELEMETRY_DISABLED: Disable telemetry at runtime
+#   - No anonymous usage data sent to Vercel
+#
+# PORT: The port the server will listen on
+#   - Default 3000, can be overridden at runtime
+#   - HuggingFace Spaces may require specific ports (e.g., 7860)
+#
+# HOSTNAME: The hostname to bind to
+#   - 0.0.0.0 binds to all network interfaces
+#   - Required for Docker networking (localhost wouldn't be accessible)
+#
+# NODE_OPTIONS: Node.js runtime flags
+#   - --enable-source-maps: Better error stack traces in production
+#   - Note: Gzip compression is handled by Next.js automatically
+#     (via the compress option, which defaults to true)
+# -----------------------------------------------------------------------------
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV PORT=3000
+ENV HOSTNAME=0.0.0.0
+ENV NODE_OPTIONS="--enable-source-maps"
+
+# -----------------------------------------------------------------------------
+# Create Non-Root User
+# -----------------------------------------------------------------------------
+# Security best practice: Run applications as non-root user.
+# This limits the potential damage from security vulnerabilities.
+#
+# addgroup: Create a system group 'nodejs' with GID 1001
+# adduser:  Create a system user 'nextjs' with UID 1001
+#   - -S: Create a system user (no password, no home dir contents)
+#   - -G: Add to the nodejs group
+#   - -u: Set specific UID for consistency across environments
+#
+# Using UID/GID 1001 to avoid conflicts with existing system users.
+# -----------------------------------------------------------------------------
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 --ingroup nodejs nextjs
+
+# -----------------------------------------------------------------------------
+# Copy Public Directory
+# -----------------------------------------------------------------------------
+# Copy static files from the public directory.
+# These files are served directly by Next.js without processing.
+# Common contents: favicon.ico, robots.txt, static images, fonts
+#
+# --chown: Set ownership to nextjs user for proper permissions
+# -----------------------------------------------------------------------------
+COPY --from=builder --chown=nextjs:nodejs /app/public ./public
+
+# -----------------------------------------------------------------------------
+# Create .next Directory
+# -----------------------------------------------------------------------------
+# Create the .next directory with proper ownership.
+# Next.js writes cache and runtime files here.
+# Pre-creating with correct ownership prevents permission errors.
+# -----------------------------------------------------------------------------
+RUN mkdir -p .next && chown nextjs:nodejs .next
+
+# -----------------------------------------------------------------------------
+# Copy Standalone Server
+# -----------------------------------------------------------------------------
+# Copy the standalone output from the builder stage.
+# This is the minimal Node.js server with bundled dependencies.
+#
+# Structure of .next/standalone/:
+#   - server.js       : The entry point for the production server
+#   - node_modules/   : Only the dependencies required by server.js
+#   - .next/          : Compiled server components and routes
+#   - package.json    : Minimal package info
+#
+# The standalone output is significantly smaller than full node_modules
+# because it only includes the specific files needed for production.
+# -----------------------------------------------------------------------------
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+
+# -----------------------------------------------------------------------------
+# Copy Static Assets
+# -----------------------------------------------------------------------------
+# Copy the static assets directory to the standalone output.
+# These are the compiled JavaScript/CSS chunks and other static files.
+#
+# IMPORTANT: The standalone output does NOT automatically include .next/static
+# because these files should typically be served by a CDN. However, for
+# HuggingFace Spaces and simple deployments, we serve them from the same server.
+#
+# The static directory must be placed inside .next/ for Next.js to find it.
+# -----------------------------------------------------------------------------
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+# -----------------------------------------------------------------------------
+# Switch to Non-Root User
+# -----------------------------------------------------------------------------
+# All subsequent commands and the container runtime will use this user.
+# This is the final security measure before running the application.
+# -----------------------------------------------------------------------------
+USER nextjs
+
+# -----------------------------------------------------------------------------
+# Expose Port
+# -----------------------------------------------------------------------------
+# Document the port that the application listens on.
+# This is informational; actual port mapping is done at runtime with -p flag.
+# The PORT environment variable (default 3000) controls the actual binding.
+# -----------------------------------------------------------------------------
+EXPOSE 3000
+
+# -----------------------------------------------------------------------------
+# Health Check
+# -----------------------------------------------------------------------------
+# Docker health check to verify the container is running properly.
+# Used by orchestrators (Docker Compose, Kubernetes, HF Spaces) for:
+#   - Container lifecycle management
+#   - Load balancer health checks
+#   - Automatic container restarts on failure
+#
+# Options:
+#   --interval=30s    : Check every 30 seconds
+#   --timeout=10s     : Wait up to 10 seconds for response
+#   --start-period=30s: Grace period for application startup
+#   --retries=3       : Mark unhealthy after 3 consecutive failures
+#
+# Command:
+#   wget: Use wget instead of curl (curl not installed in alpine by default)
+#   --no-verbose: Reduce output noise
+#   --tries=1: Single attempt per check
+#   --spider: Don't download, just check availability
+#   http://localhost:3000/: The root page (or use a dedicated health endpoint)
+# -----------------------------------------------------------------------------
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1
+
+# -----------------------------------------------------------------------------
+# Start Command
+# -----------------------------------------------------------------------------
+# Start the Next.js production server using the standalone server.js file.
+#
+# The standalone server.js is a minimal Node.js server that:
+#   - Handles all Next.js routing (pages, API routes, etc.)
+#   - Serves static files from .next/static and public
+#   - Includes production optimizations (compression, caching headers)
+#   - Uses the HOSTNAME and PORT environment variables
+#
+# Using exec form (JSON array) ensures:
+#   - Proper signal handling (SIGTERM reaches Node.js directly)
+#   - No shell process overhead
+#   - Correct argument parsing
+#
+# Note: The server automatically enables gzip compression via Next.js
+# (compress: true is the default in production mode).
+# -----------------------------------------------------------------------------
+CMD ["node", "server.js"]

PROJECT_README.md

@@ -0,0 +1,250 @@
+# RAG Chatbot for pythermalcomfort
+
+> **Note**: For HuggingFace Space configuration and user documentation, see [README.md](README.md).
+
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)
+
+A Retrieval-Augmented Generation (RAG) chatbot for the pythermalcomfort library documentation. The chatbot uses hybrid retrieval (dense embeddings + BM25) to find relevant documentation chunks and streams responses via LLM providers.
+
+## Features
+
+- Hybrid retrieval combining dense embeddings (BGE) with BM25 keyword search
+- Multi-provider LLM support with automatic fallback (Gemini -> Groq -> DeepSeek)
+- Server-Sent Events (SSE) streaming for real-time responses
+- Structure-aware PDF chunking with heading inheritance
+- Async query logging to HuggingFace datasets
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11 or higher
+- [Poetry](https://python-poetry.org/docs/#installation) for dependency management
+
+### Environment Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/sadickam/pythermalcomfort-chat.git
+   cd pythermalcomfort-chat
+   ```
+
+2. Create and activate a virtual environment:
+   ```bash
+   python -m venv therm_venv
+   source therm_venv/bin/activate  # Linux/macOS
+   # or
+   therm_venv\Scripts\activate     # Windows
+   ```
+
+3. Install dependencies using one of the install modes below.
+
+### Install Modes
+
+The project uses Poetry dependency groups to support different deployment scenarios:
+
+```bash
+# Server only (BM25 retrieval) - lightweight, no GPU required
+poetry install --with serve
+
+# Server with dense retrieval - requires torch, optional GPU
+poetry install --with serve,dense
+
+# Full build pipeline (local) - for rebuilding embeddings and indexes
+poetry install --with build,dev
+```
+
+### Dependency Comparison
+
+| Dependency             | Core | Serve | Dense | Build |
+|------------------------|:----:|:-----:|:-----:|:-----:|
+| pydantic               |  x   |       |       |       |
+| pydantic-settings      |  x   |       |       |       |
+| numpy                  |  x   |       |       |       |
+| httpx                  |  x   |       |       |       |
+| tiktoken               |  x   |       |       |       |
+| rank-bm25              |  x   |       |       |       |
+| faiss-cpu              |  x   |       |       |       |
+| fastapi                |      |   x   |       |       |
+| uvicorn                |      |   x   |       |       |
+| sse-starlette          |      |   x   |       |       |
+| sentence-transformers  |      |       |   x   |   x   |
+| torch                  |      |       |   x   |   x   |
+| pymupdf4llm            |      |       |       |   x   |
+| pymupdf                |      |       |       |   x   |
+| pyarrow                |      |       |       |   x   |
+| datasets               |      |       |       |   x   |
+
+**Install mode explanations:**
+
+- **Core**: Always installed. Provides base functionality for retrieval and LLM communication.
+- **Serve** (`--with serve`): Adds FastAPI server for hosting the chatbot API. Suitable for CPU-only deployments using precomputed embeddings.
+- **Dense** (`--with dense`): Adds sentence-transformers and PyTorch for runtime embedding generation. Use when you need to embed queries with dense vectors.
+- **Build** (`--with build`): Full offline pipeline for processing PDFs, generating embeddings, and publishing indexes to HuggingFace.
+
+## Quick Start
+
+1. Set up environment variables:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your API keys
+   ```
+
+2. Start the server:
+   ```bash
+   poetry run uvicorn src.rag_chatbot.api.main:app --reload
+   ```
+
+3. The API will be available at `http://localhost:8000`
+
+## Project Structure
+
+```
+src/rag_chatbot/
+├── api/            # FastAPI endpoints and middleware
+├── chunking/       # Structure-aware document chunking
+├── config/         # Settings and configuration
+├── embeddings/     # BGE encoder and storage
+├── extraction/     # PDF to Markdown conversion
+├── llm/            # LLM provider registry (Gemini, Groq, DeepSeek)
+├── qlog/           # Async query logging to HuggingFace
+└── retrieval/      # Hybrid retriever (FAISS + BM25 with RRF fusion)
+```
+
+## Build Pipeline
+
+For rebuilding embeddings and indexes from source PDFs:
+
+```bash
+# Full rebuild: extract -> chunk -> embed -> index -> publish
+poetry run python scripts/rebuild.py data/raw/
+
+# Individual steps
+poetry run python scripts/extract.py data/raw/ data/processed/
+poetry run python scripts/chunk.py data/processed/ data/chunks/chunks.jsonl
+poetry run python scripts/embed.py data/chunks/chunks.jsonl data/embeddings/ --publish
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+poetry run pytest
+
+# Run unit tests only
+poetry run pytest tests/unit/
+
+# Run a single test file
+poetry run pytest tests/unit/test_foo.py
+
+# Run a single test by name
+poetry run pytest -k "test_name"
+
+# Generate coverage report
+poetry run pytest --cov=src --cov-report=html
+```
+
+### Code Quality
+
+```bash
+# Type checking (strict mode)
+poetry run mypy src/
+
+# Linting
+poetry run ruff check src/
+
+# Formatting
+poetry run ruff format src/
+```
+
+### Pre-commit Hooks
+
+Install pre-commit hooks to run checks automatically before each commit:
+
+```bash
+poetry run pre-commit install
+```
+
+## Environment Variables
+
+Required secrets for deployment:
+
+| Variable           | Description                    |
+|--------------------|--------------------------------|
+| `GEMINI_API_KEY`   | Google Gemini API key          |
+| `DEEPSEEK_API_KEY` | DeepSeek API key               |
+| `GROQ_API_KEY`     | Groq API key                   |
+| `HF_TOKEN`         | HuggingFace authentication     |
+
+Configuration options:
+
+| Variable              | Default | Description                          |
+|-----------------------|---------|--------------------------------------|
+| `USE_HYBRID`          | `true`  | Enable BM25 + dense retrieval        |
+| `USE_RERANKER`        | `false` | Enable cross-encoder reranking       |
+| `TOP_K`               | `6`     | Number of chunks to retrieve         |
+| `PROVIDER_TIMEOUT_MS` | `30000` | Timeout before provider fallback     |
+
+## Retrieval Configuration
+
+The retrieval system can be tuned via environment variables to balance latency and answer quality.
+
+### Available Settings
+
+| Setting | Default | Range | Description |
+|---------|---------|-------|-------------|
+| `TOP_K` | `6` | 1-20 | Number of chunks to retrieve. Higher values provide more context but increase latency. |
+| `USE_HYBRID` | `true` | boolean | Enable hybrid retrieval combining dense (FAISS) and sparse (BM25) search with RRF fusion. |
+| `USE_RERANKER` | `false` | boolean | Enable cross-encoder reranking for improved relevance. Adds ~200-500ms latency. |
+
+### Retriever Modes
+
+**Hybrid Mode (default):** Combines dense semantic search (FAISS with BGE embeddings) and sparse keyword search (BM25) using Reciprocal Rank Fusion. Best for mixed queries containing both technical terms and natural language.
+
+**Dense-Only Mode:** Uses only FAISS semantic search. Faster than hybrid mode and works well for purely semantic queries where exact keyword matching is less important.
+
+### Performance Tradeoffs
+
+| Setting | Default | Latency Impact | Quality Impact |
+|---------|---------|----------------|----------------|
+| `TOP_K` | 6 | +~5ms per chunk | More context = better answers |
+| `USE_HYBRID` | true | +~20-50ms | Better for mixed queries |
+| `USE_RERANKER` | false | +~200-500ms | Significantly improved relevance |
+
+### Recommended Configurations
+
+**Low-latency production (default):**
+```bash
+USE_HYBRID=true
+USE_RERANKER=false
+TOP_K=6
+```
+
+**High-precision answers:**
+```bash
+USE_HYBRID=true
+USE_RERANKER=true
+TOP_K=10
+```
+
+**Fastest responses:**
+```bash
+USE_HYBRID=false
+USE_RERANKER=false
+TOP_K=3
+```
+
+## HuggingFace Repositories
+
+| Repository                       | Purpose                              |
+|----------------------------------|--------------------------------------|
+| `sadickam/pytherm_index`         | Chunks, embeddings, FAISS/BM25 indexes |
+| `sadickam/Pytherm_Qlog`          | Query/answer logs (no PII)           |
+| `sadickam/Pythermalcomfort-Chat` | Deployment Space (Docker SDK)        |
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

README.md

@@ -1,198 +1,249 @@
-# RAG Chatbot for pythermalcomfort
+---
+title: Pythermalcomfort Chat
+emoji: 🌖
+colorFrom: yellow
+colorTo: red
+sdk: docker
+pinned: false
+license: mit
+---
 
-![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
-![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)
+<!-- Overview Section: Introduces the chatbot and its purpose -->
+# 🌡️ Pythermalcomfort RAG Chatbot
 
-A Retrieval-Augmented Generation (RAG) chatbot for the pythermalcomfort library documentation. The chatbot uses hybrid retrieval (dense embeddings + BM25) to find relevant documentation chunks and streams responses via LLM providers.
+Welcome to the **Pythermalcomfort Chat** — an AI-powered assistant designed to help you understand and use the [pythermalcomfort](https://github.com/CenterForTheBuiltEnvironment/pythermalcomfort) Python library for thermal comfort calculations.
 
-## Features
+## What is This?
 
-- Hybrid retrieval combining dense embeddings (BGE) with BM25 keyword search
-- Multi-provider LLM support with automatic fallback (Gemini -> Groq -> DeepSeek)
-- Server-Sent Events (SSE) streaming for real-time responses
-- Structure-aware PDF chunking with heading inheritance
-- Async query logging to HuggingFace datasets
+This chatbot uses **Retrieval-Augmented Generation (RAG)** to provide accurate, documentation-grounded answers about thermal comfort science and the pythermalcomfort library. Instead of relying solely on general AI knowledge, every response is backed by relevant excerpts from the official documentation, ensuring you get precise and reliable information.
 
-## Installation
+**Why use this chatbot?**
+- 📚 Get instant answers about thermal comfort standards (ASHRAE 55, ISO 7730, EN 16798)
+- 🔧 Learn how to use pythermalcomfort functions with practical examples
+- 🎯 Understand complex concepts like PMV/PPD, adaptive comfort, and more
+- 📖 Receive responses with source citations so you can dive deeper
 
-### Prerequisites
+---
 
-- Python 3.11 or higher
-- [Poetry](https://python-poetry.org/docs/#installation) for dependency management
+<!-- Example Questions Section: Shows users what they can ask -->
+## 💬 What You Can Ask
 
-### Environment Setup
+Here are some example questions to get you started:
 
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/sadickam/pythermalcomfort-chat.git
-   cd pythermalcomfort-chat
-   ```
+| Category | Example Questions |
+|----------|-------------------|
+| **Concepts** | "What is PMV and how is it calculated?" |
+| | "What is the difference between PMV and PPD?" |
+| | "How does adaptive thermal comfort work?" |
+| **Standards** | "What are the ASHRAE Standard 55 requirements?" |
+| | "What thermal comfort categories does ISO 7730 define?" |
+| | "What is the EN 16798 standard?" |
+| **Library Usage** | "What inputs does the pmv_ppd function need?" |
+| | "How do I calculate thermal comfort for an office?" |
+| | "How do I use the adaptive comfort model?" |
+| **Parameters** | "What is metabolic rate and how do I estimate it?" |
+| | "How do I measure clothing insulation?" |
+| | "What is operative temperature?" |
 
-2. Create and activate a virtual environment:
-   ```bash
-   python -m venv therm_venv
-   source therm_venv/bin/activate  # Linux/macOS
-   # or
-   therm_venv\Scripts\activate     # Windows
-   ```
+---
 
-3. Install dependencies using one of the install modes below.
+<!-- Technical Features Section: Details the chatbot's capabilities -->
+## ⚙️ Technical Features
 
-### Install Modes
+| Feature | Description |
+|---------|-------------|
+| **RAG-Powered Responses** | Every answer includes source citations from pythermalcomfort documentation |
+| **Hybrid Retrieval** | Combines dense embeddings (FAISS) + sparse retrieval (BM25) with Reciprocal Rank Fusion for accurate document search |
+| **Multi-Provider LLM** | Automatic fallback chain: Gemini → DeepSeek → Anthropic → Groq ensures high availability |
+| **Real-Time Streaming** | Responses stream via Server-Sent Events (SSE) for a responsive chat experience |
+| **Query Logging** | Anonymous query logging enables continuous improvement of retrieval quality |
 
-The project uses Poetry dependency groups to support different deployment scenarios:
+---
 
-```bash
-# Server only (BM25 retrieval) - lightweight, no GPU required
-poetry install --with serve
+## 🤖 Available LLM Models
 
-# Server with dense retrieval - requires torch, optional GPU
-poetry install --with serve,dense
+<!--
+  The chatbot uses multiple LLM providers with automatic fallback.
+  When one provider is rate-limited or unavailable, the system
+  automatically switches to the next available provider.
+-->
 
-# Full build pipeline (local) - for rebuilding embeddings and indexes
-poetry install --with build,dev
-```
+The chatbot leverages multiple LLM providers with intelligent fallback to ensure high availability:
+
+### Google Gemini (Primary Provider)
+
+| Model | Rate Limits (Free Tier) | Description |
+|-------|-------------------------|-------------|
+| `gemini-2.5-flash-lite` | 10 RPM, 250K TPM | Primary model - fastest response times |
+| `gemini-2.5-flash` | 5 RPM, 250K TPM | Secondary - balanced speed and quality |
+| `gemini-3-flash` | 5 RPM, 250K TPM | Tertiary - latest Gemini capabilities |
+| `gemma-3-27b-it` | 30 RPM, 15K TPM | Final fallback - open-weights model |
+
+### Groq (High-Speed Provider)
+
+| Model | Rate Limits (Free Tier) | Description |
+|-------|-------------------------|-------------|
+| `openai/gpt-oss-120b` | 30 RPM, 8K TPM | Primary - large model via Groq |
+| `llama-3.3-70b-versatile` | 30 RPM, 12K TPM | Secondary - Meta's Llama 3.3 |
+
+### DeepSeek (Fallback Provider)
 
-### Dependency Comparison
-
-| Dependency             | Core | Serve | Dense | Build |
-|------------------------|:----:|:-----:|:-----:|:-----:|
-| pydantic               |  x   |       |       |       |
-| pydantic-settings      |  x   |       |       |       |
-| numpy                  |  x   |       |       |       |
-| httpx                  |  x   |       |       |       |
-| tiktoken               |  x   |       |       |       |
-| rank-bm25              |  x   |       |       |       |
-| faiss-cpu              |  x   |       |       |       |
-| fastapi                |      |   x   |       |       |
-| uvicorn                |      |   x   |       |       |
-| sse-starlette          |      |   x   |       |       |
-| sentence-transformers  |      |       |   x   |   x   |
-| torch                  |      |       |   x   |   x   |
-| pymupdf4llm            |      |       |       |   x   |
-| pymupdf                |      |       |       |   x   |
-| pyarrow                |      |       |       |   x   |
-| datasets               |      |       |       |   x   |
-
-**Install mode explanations:**
-
-- **Core**: Always installed. Provides base functionality for retrieval and LLM communication.
-- **Serve** (`--with serve`): Adds FastAPI server for hosting the chatbot API. Suitable for CPU-only deployments using precomputed embeddings.
-- **Dense** (`--with dense`): Adds sentence-transformers and PyTorch for runtime embedding generation. Use when you need to embed queries with dense vectors.
-- **Build** (`--with build`): Full offline pipeline for processing PDFs, generating embeddings, and publishing indexes to HuggingFace.
-
-## Quick Start
-
-1. Set up environment variables:
-   ```bash
-   cp .env.example .env
-   # Edit .env with your API keys
-   ```
-
-2. Start the server:
-   ```bash
-   poetry run uvicorn src.rag_chatbot.api.main:app --reload
-   ```
-
-3. The API will be available at `http://localhost:8000`
-
-## Project Structure
+| Model | Description |
+|-------|-------------|
+| `deepseek-chat` | Cost-effective alternative with strong reasoning |
+
+### Provider Fallback Chain
 
 ```
-src/rag_chatbot/
-├── api/            # FastAPI endpoints and middleware
-├── chunking/       # Structure-aware document chunking
-├── config/         # Settings and configuration
-├── embeddings/     # BGE encoder and storage
-├── extraction/     # PDF to Markdown conversion
-├── llm/            # LLM provider registry (Gemini, Groq, DeepSeek)
-├── qlog/           # Async query logging to HuggingFace
-└── retrieval/      # Hybrid retriever (FAISS + BM25 with RRF fusion)
+Gemini → Groq → DeepSeek → Anthropic
+   ↓        ↓       ↓          ↓
+Primary  Fast   Budget    Premium
 ```
 
-## Build Pipeline
+When a provider hits rate limits or encounters errors:
+1. The system automatically tries the next provider in the chain
+2. Rate limit cooldowns are tracked per-model
+3. Responses indicate which provider was used
 
-For rebuilding embeddings and indexes from source PDFs:
+> **Note**: The fallback chain ensures maximum availability while staying within free tier limits.
 
-```bash
-# Full rebuild: extract -> chunk -> embed -> index -> publish
-poetry run python scripts/rebuild.py data/raw/
+---
 
-# Individual steps
-poetry run python scripts/extract.py data/raw/ data/processed/
-poetry run python scripts/chunk.py data/processed/ data/chunks/chunks.jsonl
-poetry run python scripts/embed.py data/chunks/chunks.jsonl data/embeddings/ --publish
-```
+<!-- About pythermalcomfort Section: Background on the library -->
+## 📖 About pythermalcomfort
 
-## Development
+**Thermal comfort** refers to the condition of mind that expresses satisfaction with the thermal environment. It's influenced by factors like air temperature, humidity, air velocity, radiant temperature, clothing, and metabolic rate.
 
-### Running Tests
+The **pythermalcomfort** library is an open-source Python package that implements thermal comfort models and indices according to international standards, including:
 
-```bash
-# Run all tests
-poetry run pytest
+- 🏛️ **ASHRAE Standard 55** — Thermal Environmental Conditions for Human Occupancy
+- 🌍 **ISO 7730** — Ergonomics of the thermal environment
+- 🇪🇺 **EN 16798** — Energy performance of buildings
+
+### Key Capabilities
+
+- Calculate **PMV (Predicted Mean Vote)** and **PPD (Predicted Percentage Dissatisfied)**
+- Evaluate **adaptive thermal comfort** for naturally ventilated buildings
+- Compute various thermal comfort indices (SET, UTCI, Cooling Effect, etc.)
+- Support for both SI and IP unit systems
+
+### Resources
+
+- 📦 **GitHub Repository**: [CenterForTheBuiltEnvironment/pythermalcomfort](https://github.com/CenterForTheBuiltEnvironment/pythermalcomfort)
+- 📚 **Documentation**: [pythermalcomfort.readthedocs.io](https://pythermalcomfort.readthedocs.io/)
+- 🐍 **PyPI**: [pythermalcomfort on PyPI](https://pypi.org/project/pythermalcomfort/)
 
-# Run unit tests only
-poetry run pytest tests/unit/
+---
 
-# Run a single test file
-poetry run pytest tests/unit/test_foo.py
+<!-- API Endpoints Section: Technical reference for developers -->
+## 🔌 API Endpoints
 
-# Run a single test by name
-poetry run pytest -k "test_name"
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/query` | POST | Submit a question and receive a streamed response |
+| `/api/providers` | GET | Check availability status of LLM providers |
+| `/health` | GET | Basic health check |
+| `/health/ready` | GET | Readiness probe (checks if indexes are loaded) |
 
-# Generate coverage report
-poetry run pytest --cov=src --cov-report=html
+### Query Request Format
+
+```json
+{
+  "question": "What is PMV?",
+  "provider": "gemini"
+}
 ```
 
-### Code Quality
+The `provider` field is optional. If omitted, the system automatically selects the best available provider.
 
-```bash
-# Type checking (strict mode)
-poetry run mypy src/
+---
 
-# Linting
-poetry run ruff check src/
+<!-- Architecture Section: High-level system overview -->
+## 🏗️ Architecture
 
-# Formatting
-poetry run ruff format src/
+This Space uses a multi-container architecture optimized for HuggingFace Spaces:
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Nginx     │────▶│  Next.js    │     │  FastAPI    │
+│  (Proxy)    │────▶│  Frontend   │────▶│  Backend    │
+└─────────────┘     └─────────────┘     └─────────────┘
+                                              │
+                                              ▼
+                                    ┌─────────────────┐
+                                    │  FAISS + BM25   │
+                                    │    Indexes      │
+                                    └─────────────────┘
 ```
 
-### Pre-commit Hooks
+- **Nginx** — Reverse proxy handling routing between frontend and backend
+- **Next.js** — React frontend with responsive chat interface
+- **FastAPI** — Python backend with RAG pipeline and LLM orchestration
+
+The backend downloads prebuilt FAISS indexes and BM25 vocabularies from the [`sadickam/pytherm_index`](https://huggingface.co/datasets/sadickam/pytherm_index) HuggingFace dataset at startup, enabling efficient hybrid retrieval without requiring GPU compute.
+
+---
+
+<!-- For Developers Section: Points to development resources -->
+## 👩‍💻 For Developers
+
+Interested in running this locally or contributing? See the **[PROJECT_README.md](PROJECT_README.md)** for detailed development setup instructions, including:
 
-Install pre-commit hooks to run checks automatically before each commit:
+- Local development without Docker
+- Building the retrieval indexes from scratch
+- Running tests and type checking
+- Contributing guidelines
+
+### Quick Start (Development)
 
 ```bash
-poetry run pre-commit install
+# Backend
+poetry install --with serve,dense
+poetry run uvicorn src.rag_chatbot.api.main:app --reload --port 7860
+
+# Frontend (in separate terminal)
+cd frontend
+npm install
+npm run dev
 ```
 
-## Environment Variables
+---
+
+<!-- Environment Variables Section: Deployment configuration -->
+## 🔐 Environment Variables (Deployment)
+
+The following secrets must be configured in HuggingFace Space settings for deployment:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GEMINI_API_KEY` | Yes | Google Gemini API key (primary provider) |
+| `DEEPSEEK_API_KEY` | No | DeepSeek API key (fallback provider) |
+| `ANTHROPIC_API_KEY` | No | Anthropic API key (fallback provider) |
+| `GROQ_API_KEY` | No | Groq API key (fallback provider) |
+| `HF_TOKEN` | Yes | HuggingFace token for accessing datasets and query logging |
+
+**Note:** At least one LLM provider key is required for the chatbot to function.
 
-Required secrets for deployment:
+---
 
-| Variable           | Description                    |
-|--------------------|--------------------------------|
-| `GEMINI_API_KEY`   | Google Gemini API key          |
-| `DEEPSEEK_API_KEY` | DeepSeek API key               |
-| `GROQ_API_KEY`     | Groq API key                   |
-| `HF_TOKEN`         | HuggingFace authentication     |
+<!-- Related Repositories Section: Links to associated resources -->
+## 🔗 Related Repositories
 
-Configuration options:
+| Repository | Description |
+|------------|-------------|
+| [pythermalcomfort](https://github.com/CenterForTheBuiltEnvironment/pythermalcomfort) | The Python library this chatbot documents |
+| [sadickam/pytherm_index](https://huggingface.co/datasets/sadickam/pytherm_index) | Prebuilt retrieval indexes (FAISS + BM25) |
+| [sadickam/Pytherm_Qlog](https://huggingface.co/datasets/sadickam/Pytherm_Qlog) | Anonymous query logs for improvement |
 
-| Variable              | Default | Description                          |
-|-----------------------|---------|--------------------------------------|
-| `USE_HYBRID`          | `true`  | Enable BM25 + dense retrieval        |
-| `TOP_K`               | `6`     | Number of chunks to retrieve         |
-| `PROVIDER_TIMEOUT_MS` | `30000` | Timeout before provider fallback     |
+---
 
-## HuggingFace Repositories
+<!-- License Section -->
+## 📄 License
 
-| Repository                       | Purpose                              |
-|----------------------------------|--------------------------------------|
-| `sadickam/pytherm_index`         | Chunks, embeddings, FAISS/BM25 indexes |
-| `sadickam/Pytherm_Qlog`          | Query/answer logs (no PII)           |
-| `sadickam/Pythermalcomfort-Chat` | Deployment Space (Docker SDK)        |
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
 
-## License
+---
 
-MIT License - see [LICENSE](LICENSE) for details.
+<p align="center">
+  Made with ❤️ for the thermal comfort research community
+</p>

commands

@@ -41,6 +41,10 @@ Verbose mode - Basic rebuild with detailed output showing each file being proces
 clear all artifacts, generate new artifacts and publish to HF
 
 
+## Commit to HF Space
+- git push space master --force   ( first time)
+- git push space master    (subsequent commits)
+
 ## CREATE AASBS2 and SDG Targets Database with Embeddings 
 
 
@@ -85,9 +89,8 @@ After your solution, rate your confidence (0-1) on:
 If any score < 0.9, refine your answer.
 [TASK]
 - Read the **## Overview** sections of **IMPLEMENTATION_PLAN.md** to understand the system, and context.
-- Review **Step 4.7: Implement Full Rebuild Script** step by step to understand all of its requirements and objectives.
-- Spawn specilaised agents and orchestrate them to succesfully complete all tasks for **Step 4.7: Implement Full Rebuild Script** based on defined details in the **@IMPLEMENTATION_PLAN.md**
-- Ensure normalisation includes correcting jumbled words and sentences, removing extra spaces, and ensuring proper capitalization.
+- Review **Step 9.5: Add Dataset Freshness Check on Startup** step by step to understand all of its requirements and objectives.
+- Spawn specilaised agents and orchestrate them to succesfully complete all tasks for **Step 9.5: Add Dataset Freshness Check on Startup** based on defined details in the **@IMPLEMENTATION_PLAN.md**
 - Spawn at most 2 specialised agents at a time
 - Ensure clean hands off between agents to avoid file write conflicts occurring between agents and potential data loss
 - It is critical to identify and fix potentially missing items that can affect production-readiness.

docs/HF_SPACE_CONFIG.md

@@ -0,0 +1,427 @@
+# HuggingFace Space Configuration Guide
+
+<!--
+  This documentation covers the manual configuration steps required to deploy
+  the pythermalcomfort RAG chatbot on HuggingFace Spaces. The Space uses the
+  Docker SDK for deployment, which means it builds and runs a Docker container
+  from the repository's Dockerfile.
+-->
+
+## Overview
+
+This guide explains how to configure the HuggingFace Space at **[sadickam/Pythermalcomfort-Chat](https://huggingface.co/spaces/sadickam/Pythermalcomfort-Chat)** for deployment.
+
+The Space uses the **Docker SDK**, which means:
+- HuggingFace builds a Docker image from the repository's `Dockerfile`
+- The container runs on HuggingFace's infrastructure
+- Environment variables and secrets are injected at runtime
+- The application serves both the Next.js frontend and FastAPI backend
+
+---
+
+## README File Structure
+
+<!--
+  The project maintains two separate README files for different purposes:
+  - README.md: HuggingFace Space configuration and user documentation (with YAML frontmatter)
+  - PROJECT_README.md: Main project documentation for developers
+-->
+
+The HuggingFace Space requires a `README.md` file with specific YAML frontmatter for configuration. This repository is structured so that `README.md` serves as the Space configuration file directly, eliminating the need for file renaming during deployment.
+
+### File Structure
+
+| File | Purpose |
+|------|---------|
+| `README.md` | HuggingFace Space configuration with YAML frontmatter, user-facing documentation |
+| `PROJECT_README.md` | Developer documentation, installation instructions, contribution guidelines |
+
+### YAML Frontmatter Requirements
+
+The `README.md` starts with this required frontmatter:
+
+```yaml
+---
+title: Pythermalcomfort Chat
+emoji: 🌖
+colorFrom: yellow
+colorTo: red
+sdk: docker
+pinned: false
+license: mit
+---
+```
+
+This tells HuggingFace how to build and display the Space.
+
+---
+
+## Required Secrets Configuration
+
+<!--
+  Secrets are sensitive credentials that should never be committed to the repository.
+  HuggingFace Spaces provides a secure way to inject these as environment variables
+  at runtime. The application uses these keys for LLM API calls and HuggingFace
+  dataset access.
+-->
+
+### Secret Reference Table
+
+| Secret Name | Required | Description |
+|-------------|----------|-------------|
+| `GEMINI_API_KEY` | **Required** | Google Gemini API key - Primary LLM provider for generating responses |
+| `HF_TOKEN` | **Required** | HuggingFace token for accessing the index dataset and query logging |
+| `DEEPSEEK_API_KEY` | Optional | DeepSeek API key - First fallback provider if Gemini fails |
+| `ANTHROPIC_API_KEY` | Optional | Anthropic Claude API key - Second fallback provider |
+| `GROQ_API_KEY` | Optional | Groq API key - Third fallback provider for fast inference |
+
+### Step-by-Step Configuration
+
+1. **Navigate to the Space Settings**
+   ```
+   https://huggingface.co/spaces/sadickam/Pythermalcomfort-Chat/settings
+   ```
+
+2. **Scroll to the "Repository secrets" section**
+   - This section is located under "Variables and secrets" in the Settings page
+
+3. **Add each secret**
+   - Click "New secret"
+   - Enter the secret name exactly as shown (e.g., `GEMINI_API_KEY`)
+   - Paste the API key value
+   - Click "Add"
+   - Repeat for each secret
+
+4. **Required secrets setup**
+
+   **GEMINI_API_KEY** (Required):
+   ```
+   # Obtain from: https://makersuite.google.com/app/apikey
+   # This is the primary LLM provider - the chatbot will not function without it
+   ```
+
+   **HF_TOKEN** (Required):
+   ```
+   # Obtain from: https://huggingface.co/settings/tokens
+   # Required permissions:
+   #   - Read access to sadickam/pytherm_index (prebuilt indexes)
+   #   - Write access to sadickam/Pytherm_Qlog (query logging)
+   ```
+
+5. **Optional fallback provider secrets**
+
+   <!--
+     The LLM provider registry implements automatic fallback. If the primary
+     provider (Gemini) fails or hits rate limits, it will try the next available
+     provider in order: DeepSeek -> Anthropic -> Groq
+   -->
+
+   **DEEPSEEK_API_KEY** (Optional):
+   ```
+   # Obtain from: https://platform.deepseek.com/
+   # First fallback if Gemini is unavailable
+   ```
+
+   **ANTHROPIC_API_KEY** (Optional):
+   ```
+   # Obtain from: https://console.anthropic.com/
+   # Second fallback provider
+   ```
+
+   **GROQ_API_KEY** (Optional):
+   ```
+   # Obtain from: https://console.groq.com/
+   # Third fallback - offers fast inference times
+   ```
+
+6. **Restart the Space**
+   - After adding all secrets, click "Restart" in the Space header
+   - The Space will rebuild and inject the new secrets
+
+---
+
+## Hardware Settings
+
+<!--
+  The application is optimized for CPU-only inference. All heavy computation
+  (embedding, indexing) is done offline during the build pipeline. At runtime,
+  the Space only performs:
+  - Vector similarity search (FAISS with prebuilt index)
+  - BM25 keyword search (prebuilt index)
+  - LLM API calls (external providers)
+-->
+
+### Recommended Configuration
+
+| Setting | Value | Reason |
+|---------|-------|--------|
+| **Hardware** | CPU Basic (Free) | No GPU required for inference |
+| **Sleep timeout** | Default (48 hours) | Adjust based on usage patterns |
+
+### Why CPU is Sufficient
+
+1. **Prebuilt Indexes**: The FAISS and BM25 indexes are built offline with GPU acceleration and published to `sadickam/pytherm_index`. At startup, the Space downloads these prebuilt artifacts.
+
+2. **No Local Embedding**: Query embedding uses the same BGE model but runs efficiently on CPU for single queries.
+
+3. **External LLM Providers**: Response generation is handled by external API providers (Gemini, DeepSeek, etc.), not local models.
+
+4. **Cost Optimization**: The free CPU tier is sufficient for the expected load and keeps operational costs at zero.
+
+### Configuring Hardware
+
+1. Navigate to: `https://huggingface.co/spaces/sadickam/Pythermalcomfort-Chat/settings`
+2. Find the "Space hardware" section
+3. Select "CPU basic" from the dropdown
+4. Click "Save" (the Space will restart automatically)
+
+---
+
+## Deployment Verification Checklist
+
+<!--
+  After configuring secrets and deploying, verify the Space is functioning
+  correctly by checking each component in order. The health endpoints provide
+  detailed status information about the application state.
+-->
+
+### Pre-flight Checks
+
+- [ ] All required secrets are configured (`GEMINI_API_KEY`, `HF_TOKEN`)
+- [ ] Hardware is set to "CPU Basic"
+- [ ] Space is set to "Public" or "Private" as needed
+
+### Build Verification
+
+- [ ] **Space builds successfully**
+  - Check the "Logs" tab for build output
+  - Build should complete without errors in 5-10 minutes
+  - Look for "Application startup complete" in logs
+
+### Health Endpoint Checks
+
+<!--
+  The application exposes multiple health endpoints for monitoring.
+  These should be checked in order as each depends on the previous.
+-->
+
+1. **Basic Health Check**
+   ```bash
+   curl https://sadickam-pythermalcomfort-chat.hf.space/health
+   ```
+   Expected response:
+   ```json
+   {"status": "healthy"}
+   ```
+   - [ ] Returns HTTP 200
+
+2. **Readiness Check**
+   ```bash
+   curl https://sadickam-pythermalcomfort-chat.hf.space/health/ready
+   ```
+   Expected response:
+   ```json
+   {
+     "status": "ready",
+     "indexes_loaded": true,
+     "chunks_count": <number>,
+     "faiss_index_size": <number>
+   }
+   ```
+   - [ ] Returns HTTP 200
+   - [ ] `indexes_loaded` is `true`
+   - [ ] `chunks_count` is greater than 0
+
+3. **Provider Availability**
+   ```bash
+   curl https://sadickam-pythermalcomfort-chat.hf.space/api/providers
+   ```
+   Expected response:
+   ```json
+   {
+     "available": ["gemini", ...],
+     "primary": "gemini"
+   }
+   ```
+   - [ ] Returns HTTP 200
+   - [ ] At least one provider in `available` list
+   - [ ] `primary` is set (typically "gemini")
+
+### Functional Test
+
+- [ ] **Test a sample query through the UI**
+  1. Open `https://sadickam-pythermalcomfort-chat.hf.space`
+  2. Wait for the interface to load
+  3. Enter a test question: "What is PMV?"
+  4. Verify:
+     - Response streams in real-time
+     - Response includes relevant information about PMV (Predicted Mean Vote)
+     - Source citations are included
+
+---
+
+## Troubleshooting
+
+<!--
+  Common issues encountered during deployment and their solutions.
+  Issues are organized by symptom for easy diagnosis.
+-->
+
+### Space Stuck in "Building"
+
+**Symptoms:**
+- Build process runs for more than 15 minutes
+- Build log shows no progress or loops
+
+**Solutions:**
+1. **Check Dockerfile syntax**
+   ```bash
+   # Validate locally before pushing
+   docker build -t test-build .
+   ```
+
+2. **Review build logs**
+   - Click "Logs" tab in the Space
+   - Look for error messages or failed commands
+   - Common issues: missing files, dependency conflicts
+
+3. **Clear build cache**
+   - Go to Settings > "Factory reboot"
+   - This clears cached layers and rebuilds from scratch
+
+### Health Check Failing
+
+**Symptoms:**
+- `/health` returns 500 or connection refused
+- Space shows as "Running" but endpoints don't respond
+
+**Solutions:**
+1. **Verify secrets are configured**
+   - Go to Settings > "Repository secrets"
+   - Confirm `GEMINI_API_KEY` and `HF_TOKEN` are present
+   - Note: You cannot see secret values, only that they exist
+
+2. **Check application logs**
+   ```
+   # Look for startup errors in the Logs tab
+   # Common messages:
+   #   - "Missing required environment variable"
+   #   - "Failed to initialize provider"
+   ```
+
+3. **Restart the Space**
+   - Click the three-dot menu > "Restart"
+   - Wait 2-3 minutes for full startup
+
+### No Providers Available
+
+**Symptoms:**
+- `/api/providers` returns `{"available": [], "primary": null}`
+- Chat interface shows "No providers available" error
+
+**Solutions:**
+1. **Verify API keys are correct**
+   - Regenerate the API key from the provider's console
+   - Update the secret in HuggingFace Space settings
+   - Restart the Space
+
+2. **Check provider status**
+   - Verify the provider's API is operational
+   - Check for rate limiting or account issues
+
+3. **Review provider logs**
+   ```
+   # Look for these patterns in logs:
+   #   - "API key invalid"
+   #   - "Rate limit exceeded"
+   #   - "Provider initialization failed"
+   ```
+
+### Index Loading Failures
+
+**Symptoms:**
+- `/health/ready` returns `{"indexes_loaded": false}`
+- Logs show "Failed to download artifacts"
+
+**Solutions:**
+1. **Verify HF_TOKEN permissions**
+   - Go to https://huggingface.co/settings/tokens
+   - Ensure the token has "Read" access to `sadickam/pytherm_index`
+   - If using a fine-grained token, add explicit repo access
+
+2. **Check dataset availability**
+   - Visit https://huggingface.co/datasets/sadickam/pytherm_index
+   - Verify the dataset exists and is accessible
+   - Check if the dataset is private and token has access
+
+3. **Manual verification**
+   ```bash
+   # Test token access locally
+   curl -H "Authorization: Bearer $HF_TOKEN" \
+     https://huggingface.co/api/datasets/sadickam/pytherm_index
+   ```
+
+4. **Check disk space**
+   - The index files require ~500MB of storage
+   - HuggingFace Spaces have limited ephemeral storage
+   - Consider reducing index size if this is an issue
+
+### Slow Response Times
+
+**Symptoms:**
+- Queries take more than 30 seconds
+- Responses time out frequently
+
+**Solutions:**
+1. **Check provider latency**
+   - The primary provider (Gemini) may be experiencing high load
+   - Fallback providers will be tried automatically
+
+2. **Verify hybrid retrieval settings**
+   ```
+   # In environment or settings:
+   USE_HYBRID=true   # Enable both FAISS and BM25
+   TOP_K=6           # Reduce if responses are slow
+   ```
+
+3. **Monitor Space resources**
+   - Check the "Metrics" tab for CPU/memory usage
+   - Consider upgrading hardware if consistently maxed out
+
+---
+
+## Environment Variables Reference
+
+<!--
+  Complete reference of all environment variables used by the application.
+  Secrets should be configured in HuggingFace Space settings, while non-sensitive
+  configuration can be set in the Dockerfile or as Space variables.
+-->
+
+### Secrets (Configure in Space Settings)
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GEMINI_API_KEY` | Yes | Google Gemini API key |
+| `HF_TOKEN` | Yes | HuggingFace access token |
+| `DEEPSEEK_API_KEY` | No | DeepSeek API key |
+| `ANTHROPIC_API_KEY` | No | Anthropic API key |
+| `GROQ_API_KEY` | No | Groq API key |
+
+### Configuration (Can be set in Dockerfile)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `USE_HYBRID` | `true` | Enable hybrid retrieval (FAISS + BM25) |
+| `TOP_K` | `6` | Number of chunks to retrieve |
+| `PROVIDER_TIMEOUT_MS` | `30000` | Timeout before trying fallback provider |
+| `LOG_LEVEL` | `INFO` | Application log level |
+
+---
+
+## Additional Resources
+
+- [HuggingFace Spaces Documentation](https://huggingface.co/docs/hub/spaces)
+- [Docker SDK Reference](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- [Space Secrets Documentation](https://huggingface.co/docs/hub/spaces-overview#managing-secrets)
+- [pythermalcomfort Library](https://pythermalcomfort.readthedocs.io/)

frontend/.dockerignore

@@ -0,0 +1,221 @@
+# =============================================================================
+# Docker Ignore File for Next.js Frontend
+# =============================================================================
+# This file specifies patterns for files and directories that should be
+# excluded from the Docker build context. Proper exclusions:
+# - Reduce build context size (faster docker build)
+# - Prevent unnecessary cache invalidation
+# - Avoid including sensitive or development-only files
+# - Keep the final image smaller and more secure
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Dependencies
+# -----------------------------------------------------------------------------
+# Exclude node_modules as dependencies are installed fresh during build.
+# This ensures consistent, reproducible builds and prevents platform-specific
+# native modules from causing issues (e.g., macOS binaries on Linux).
+node_modules/
+.pnp/
+.pnp.js
+
+# -----------------------------------------------------------------------------
+# Build Outputs
+# -----------------------------------------------------------------------------
+# Exclude local build artifacts. The Docker build process will generate
+# fresh build outputs. Including these would:
+# - Bloat the build context unnecessarily
+# - Potentially cause cache conflicts
+# - Include development build artifacts in production
+.next/
+out/
+build/
+dist/
+
+# -----------------------------------------------------------------------------
+# Version Control
+# -----------------------------------------------------------------------------
+# Git history and metadata are not needed in the container.
+# Excluding .git significantly reduces build context size.
+.git/
+.gitignore
+.gitattributes
+
+# -----------------------------------------------------------------------------
+# Test Files and Coverage
+# -----------------------------------------------------------------------------
+# Testing infrastructure is not needed in production images.
+# Exclude test files, coverage reports, and testing configurations.
+coverage/
+.nyc_output/
+*.test.ts
+*.test.tsx
+*.test.js
+*.test.jsx
+*.spec.ts
+*.spec.tsx
+*.spec.js
+*.spec.jsx
+__tests__/
+__mocks__/
+jest.config.*
+vitest.config.*
+playwright.config.*
+cypress/
+cypress.config.*
+
+# -----------------------------------------------------------------------------
+# Documentation
+# -----------------------------------------------------------------------------
+# Documentation files are not needed for runtime.
+# Keep the image focused on application code only.
+*.md
+!README.md
+docs/
+CHANGELOG*
+LICENSE*
+CONTRIBUTING*
+
+# -----------------------------------------------------------------------------
+# IDE and Editor Configurations
+# -----------------------------------------------------------------------------
+# Editor-specific files and directories should not be in the image.
+# These are developer-specific and vary between team members.
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.classpath
+.settings/
+*.sublime-*
+
+# -----------------------------------------------------------------------------
+# OS-Generated Files
+# -----------------------------------------------------------------------------
+# Operating system metadata files are never needed in containers.
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+
+# -----------------------------------------------------------------------------
+# Debug and Log Files
+# -----------------------------------------------------------------------------
+# Debug logs from package managers and build tools.
+# These can contain sensitive information and are not needed in production.
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# -----------------------------------------------------------------------------
+# Environment Files
+# -----------------------------------------------------------------------------
+# Local environment files often contain secrets.
+# Production secrets should be injected via Docker secrets or env vars.
+# IMPORTANT: Never include .env files with real credentials in images.
+.env
+.env.local
+.env.development
+.env.development.local
+.env.test
+.env.test.local
+.env.production.local
+
+# Note: .env.production is intentionally NOT excluded as it may contain
+# non-sensitive build-time configuration. Review before building.
+
+# -----------------------------------------------------------------------------
+# TypeScript Build Info
+# -----------------------------------------------------------------------------
+# TypeScript incremental compilation cache.
+# Not needed in the container; TypeScript compiles fresh during build.
+*.tsbuildinfo
+tsconfig.tsbuildinfo
+
+# -----------------------------------------------------------------------------
+# Package Manager Lock Files (Alternative)
+# -----------------------------------------------------------------------------
+# If using npm, exclude yarn/pnpm lock files and vice versa.
+# Uncomment the appropriate lines based on your package manager.
+# yarn.lock
+# pnpm-lock.yaml
+# package-lock.json
+
+# -----------------------------------------------------------------------------
+# Storybook
+# -----------------------------------------------------------------------------
+# Storybook is a development tool for UI component documentation.
+# Not needed in production runtime.
+.storybook/
+storybook-static/
+
+# -----------------------------------------------------------------------------
+# Docker Files
+# -----------------------------------------------------------------------------
+# Dockerfiles themselves don't need to be in the build context
+# (Docker reads them separately). Including them can leak build strategy info.
+Dockerfile*
+docker-compose*
+.dockerignore
+
+# -----------------------------------------------------------------------------
+# CI/CD Configuration
+# -----------------------------------------------------------------------------
+# Continuous integration configs are not needed in the runtime image.
+.github/
+.gitlab-ci.yml
+.travis.yml
+.circleci/
+azure-pipelines.yml
+Jenkinsfile
+.buildkite/
+
+# -----------------------------------------------------------------------------
+# Linting and Formatting Configs
+# -----------------------------------------------------------------------------
+# These are development tools; linting happens before build, not at runtime.
+.eslintrc*
+.eslintignore
+eslint.config.*
+.prettierrc*
+.prettierignore
+prettier.config.*
+.stylelintrc*
+.editorconfig
+
+# -----------------------------------------------------------------------------
+# Husky and Git Hooks
+# -----------------------------------------------------------------------------
+# Git hooks are for development workflow, not needed in containers.
+.husky/
+.git-hooks/
+
+# -----------------------------------------------------------------------------
+# Temporary Files
+# -----------------------------------------------------------------------------
+# Temporary files from various tools and processes.
+tmp/
+temp/
+*.tmp
+*.temp
+*.bak
+*.backup
+
+# -----------------------------------------------------------------------------
+# Miscellaneous
+# -----------------------------------------------------------------------------
+# Other files that don't belong in production images.
+Makefile
+*.log
+*.pid
+*.seed
+*.pid.lock

frontend/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

frontend/.prettierignore

@@ -0,0 +1,21 @@
+# Dependencies
+node_modules
+
+# Build output
+.next
+out
+
+# Coverage
+coverage
+
+# Cache
+.cache
+
+# Lock files
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# Generated files
+*.min.js
+*.min.css

frontend/README.md

@@ -1 +1,36 @@
-Next.js frontend - to be implemented in Phase 8
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

frontend/eslint.config.mjs

@@ -0,0 +1,120 @@
+/**
+ * ESLint Configuration for Next.js Frontend
+ *
+ * This configuration enforces strict TypeScript and React rules for
+ * production-quality code in the RAG Chatbot frontend.
+ *
+ * @see https://eslint.org/docs/latest/use/configure/configuration-files
+ */
+
+import { defineConfig, globalIgnores } from 'eslint/config';
+import nextVitals from 'eslint-config-next/core-web-vitals';
+import nextTs from 'eslint-config-next/typescript';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+const eslintConfig = defineConfig([
+  // Extend Next.js recommended configs
+  ...nextVitals,
+  ...nextTs,
+
+  // Prettier config to disable formatting rules that conflict
+  eslintConfigPrettier,
+
+  // Global configuration with strict rules for source files
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    rules: {
+      // =============================================
+      // TypeScript Strict Rules
+      // =============================================
+
+      // Enforce explicit return types on functions
+      '@typescript-eslint/explicit-function-return-type': [
+        'warn',
+        {
+          allowExpressions: true,
+          allowTypedFunctionExpressions: true,
+        },
+      ],
+
+      // Require explicit accessibility modifiers
+      '@typescript-eslint/explicit-member-accessibility': [
+        'error',
+        {
+          accessibility: 'explicit',
+          overrides: {
+            constructors: 'no-public',
+          },
+        },
+      ],
+
+      // Disallow 'any' type usage
+      '@typescript-eslint/no-explicit-any': 'error',
+
+      // Require consistent type assertions
+      '@typescript-eslint/consistent-type-assertions': [
+        'error',
+        {
+          assertionStyle: 'as',
+          objectLiteralTypeAssertions: 'never',
+        },
+      ],
+
+      // No unused variables (with underscore exception)
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+
+      // =============================================
+      // React & Next.js Rules
+      // =============================================
+
+      // Enforce hooks rules strictly
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn',
+
+      // Prevent missing key props in iterators
+      'react/jsx-key': ['error', { checkFragmentShorthand: true }],
+
+      // No array index as key
+      'react/no-array-index-key': 'warn',
+
+      // =============================================
+      // General Best Practices
+      // =============================================
+
+      // No console statements in production
+      'no-console': ['warn', { allow: ['warn', 'error'] }],
+
+      // Enforce strict equality
+      eqeqeq: ['error', 'always'],
+
+      // No debugger statements
+      'no-debugger': 'error',
+
+      // Prefer const over let when possible
+      'prefer-const': 'error',
+
+      // No var declarations
+      'no-var': 'error',
+    },
+  },
+
+  // Override default ignores of eslint-config-next
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    '.next/**',
+    'out/**',
+    'build/**',
+    'next-env.d.ts',
+    // Additional ignores
+    'node_modules/**',
+    'coverage/**',
+  ]),
+]);
+
+export default eslintConfig;

frontend/next.config.ts

@@ -0,0 +1,263 @@
+import type { NextConfig } from "next";
+
+/**
+ * Next.js Configuration for Production Docker Deployment
+ *
+ * This configuration is optimized for containerized deployments on platforms
+ * like HuggingFace Spaces, Vercel, or any Docker-based hosting.
+ *
+ * Key features:
+ * - Standalone output for minimal Docker image size
+ * - Security hardening (no x-powered-by header)
+ * - Optimized image handling with modern formats
+ * - Environment variable support for dynamic API configuration
+ */
+const nextConfig: NextConfig = {
+  /**
+   * Output Mode: Standalone
+   *
+   * Generates a standalone folder with only the necessary files for production.
+   * This dramatically reduces Docker image size by:
+   * - Including only required node_modules (not devDependencies)
+   * - Creating a minimal server.js that doesn't require the full Next.js installation
+   * - Copying only the files needed for production
+   *
+   * The standalone output is located at `.next/standalone/` after build.
+   * To run: `node .next/standalone/server.js`
+   *
+   * @see https://nextjs.org/docs/app/api-reference/config/next-config-js/output
+   */
+  output: "standalone",
+
+  /**
+   * React Strict Mode
+   *
+   * Enables React's Strict Mode for the entire application.
+   * Benefits:
+   * - Identifies components with unsafe lifecycles
+   * - Warns about deprecated API usage
+   * - Detects unexpected side effects by double-invoking certain functions
+   * - Ensures reusable state (important for React 18+ concurrent features)
+   *
+   * Note: This only affects development mode; production builds are not impacted.
+   *
+   * @see https://react.dev/reference/react/StrictMode
+   */
+  reactStrictMode: true,
+
+  /**
+   * Security: Disable x-powered-by Header
+   *
+   * Removes the "X-Powered-By: Next.js" HTTP response header.
+   * Security benefits:
+   * - Reduces information disclosure about the tech stack
+   * - Makes it slightly harder for attackers to target Next.js-specific vulnerabilities
+   * - Follows security best practice of minimizing fingerprinting
+   *
+   * @see https://nextjs.org/docs/app/api-reference/config/next-config-js/poweredByHeader
+   */
+  poweredByHeader: false,
+
+  /**
+   * Image Optimization Configuration
+   *
+   * Configures Next.js Image component optimization settings.
+   * This affects how images are processed, cached, and served.
+   */
+  images: {
+    /**
+     * Image Formats
+     *
+     * Specifies the output formats for optimized images, in order of preference.
+     * - AVIF: Best compression, ~50% smaller than JPEG, but slower to encode
+     * - WebP: Good compression, ~30% smaller than JPEG, widely supported
+     *
+     * The browser's Accept header determines which format is served.
+     * Modern browsers get AVIF/WebP; older browsers fall back to original format.
+     *
+     * Note: AVIF encoding is CPU-intensive; consider removing if build times are critical.
+     */
+    formats: ["image/avif", "image/webp"],
+
+    /**
+     * Remote Patterns
+     *
+     * Defines allowed external image sources for security.
+     * Only images from these patterns can be optimized by Next.js.
+     * Add patterns here if you need to serve images from external CDNs or APIs.
+     *
+     * Example:
+     * remotePatterns: [
+     *   { protocol: 'https', hostname: 'cdn.example.com', pathname: '/images/**' }
+     * ]
+     */
+    remotePatterns: [],
+
+    /**
+     * Unoptimized Mode
+     *
+     * When true, disables image optimization entirely.
+     * Set to true if:
+     * - Deploying to a platform without image optimization support
+     * - Using an external image CDN (Cloudinary, imgix, etc.)
+     * - Debugging image-related issues
+     *
+     * Default: false (optimization enabled)
+     */
+    unoptimized: false,
+  },
+
+  /**
+   * Environment Variables Configuration
+   *
+   * Exposes environment variables to the browser (client-side).
+   * Variables listed here are inlined at build time.
+   *
+   * IMPORTANT: Only expose non-sensitive values here.
+   * Never expose API keys, secrets, or credentials.
+   *
+   * For runtime configuration (not inlined at build), use:
+   * - NEXT_PUBLIC_* prefix for client-side runtime vars
+   * - Server-side API routes for sensitive operations
+   */
+  env: {
+    /**
+     * API Base URL
+     *
+     * The base URL for the backend API server.
+     * - Development: Usually http://localhost:8000
+     * - Production: The deployed backend URL or relative path
+     *
+     * Falls back to empty string for same-origin API calls (relative URLs).
+     * This allows the frontend to work with both:
+     * - Separate backend deployment (absolute URL)
+     * - Same-origin deployment (relative URL like /api)
+     */
+    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL || "",
+  },
+
+  /**
+   * Experimental Features
+   *
+   * Enable experimental Next.js features.
+   * Use with caution in production as these may change between versions.
+   */
+  experimental: {
+    /**
+     * Optimize Package Imports
+     *
+     * Enables automatic tree-shaking for specific packages.
+     * Reduces bundle size by only importing used exports.
+     * Particularly useful for large UI libraries.
+     *
+     * @see https://nextjs.org/docs/app/api-reference/config/next-config-js/optimizePackageImports
+     */
+    optimizePackageImports: ["lucide-react"],
+  },
+
+  /**
+   * Webpack Configuration Override
+   *
+   * Custom webpack configuration for advanced build customization.
+   * Use sparingly as it can complicate upgrades and debugging.
+   *
+   * @param config - The existing webpack configuration
+   * @param context - Build context including isServer, dev, etc.
+   * @returns Modified webpack configuration
+   */
+  webpack: (config, { isServer }) => {
+    /**
+     * Suppress Critical Dependency Warnings
+     *
+     * Some packages (especially those using dynamic requires) trigger
+     * webpack warnings that are not actionable. This filter suppresses
+     * known false-positive warnings to keep build output clean.
+     */
+    if (!isServer) {
+      // Client-side specific webpack modifications can go here
+      // Example: config.resolve.fallback = { fs: false, path: false };
+    }
+
+    return config;
+  },
+
+  /**
+   * HTTP Headers Configuration
+   *
+   * Custom HTTP headers for all routes.
+   * Used for security headers, caching policies, and CORS.
+   *
+   * @returns Array of header configurations
+   */
+  async headers() {
+    return [
+      {
+        // Apply to all routes
+        source: "/:path*",
+        headers: [
+          /**
+           * Content Security Policy
+           *
+           * Restricts resource loading to prevent XSS attacks.
+           * Customize based on your application's needs.
+           * Note: This is a basic policy; adjust for production.
+           */
+          // Uncomment and customize for production:
+          // {
+          //   key: 'Content-Security-Policy',
+          //   value: "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline';",
+          // },
+
+          /**
+           * X-Content-Type-Options
+           *
+           * Prevents MIME type sniffing attacks.
+           * Forces browser to respect declared Content-Type.
+           */
+          {
+            key: "X-Content-Type-Options",
+            value: "nosniff",
+          },
+
+          /**
+           * X-Frame-Options
+           *
+           * Prevents clickjacking by controlling iframe embedding.
+           * DENY: Cannot be embedded in any iframe
+           * SAMEORIGIN: Can only be embedded by same-origin pages
+           */
+          {
+            key: "X-Frame-Options",
+            value: "SAMEORIGIN",
+          },
+
+          /**
+           * X-XSS-Protection
+           *
+           * Enables browser's built-in XSS filtering.
+           * Note: Modern browsers rely more on CSP, but this provides
+           * additional protection for older browsers.
+           */
+          {
+            key: "X-XSS-Protection",
+            value: "1; mode=block",
+          },
+
+          /**
+           * Referrer-Policy
+           *
+           * Controls how much referrer information is sent with requests.
+           * strict-origin-when-cross-origin: Full path for same-origin,
+           * only origin for cross-origin, nothing for downgrade to HTTP.
+           */
+          {
+            key: "Referrer-Policy",
+            value: "strict-origin-when-cross-origin",
+          },
+        ],
+      },
+    ];
+  },
+};
+
+export default nextConfig;

frontend/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "frontend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "lint:fix": "next lint --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,css,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json,css,md}\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage"
+  },
+  "dependencies": {
+    "@tailwindcss/typography": "^0.5.19",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "framer-motion": "^12.26.2",
+    "lucide-react": "^0.562.0",
+    "next": "16.1.2",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-markdown": "^10.1.0",
+    "rehype-highlight": "^7.0.2",
+    "remark-gfm": "^4.0.1",
+    "tailwind-merge": "^3.4.0"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.3",
+    "@tailwindcss/postcss": "^4",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
+    "@vitejs/plugin-react": "^4.5.2",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9",
+    "eslint-config-next": "16.1.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "jsdom": "^26.1.0",
+    "prettier": "^3.8.0",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "tailwindcss": "^4",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  }
+}

frontend/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

frontend/prettier.config.js

@@ -0,0 +1,81 @@
+/**
+ * Prettier Configuration for Next.js Frontend
+ *
+ * This configuration ensures consistent code formatting across the
+ * RAG Chatbot frontend codebase.
+ *
+ * @see https://prettier.io/docs/en/configuration.html
+ */
+
+/** @type {import('prettier').Config} */
+const config = {
+  // =============================================
+  // Basic Formatting Rules
+  // =============================================
+
+  // Use single quotes for strings
+  singleQuote: true,
+
+  // Add semicolons at the end of statements
+  semi: true,
+
+  // Use 2 spaces for indentation
+  tabWidth: 2,
+
+  // Don't use tabs, use spaces
+  useTabs: false,
+
+  // Maximum line length before wrapping
+  printWidth: 80,
+
+  // =============================================
+  // Trailing Commas & Brackets
+  // =============================================
+
+  // Add trailing commas where valid in ES5 (objects, arrays, etc.)
+  trailingComma: 'es5',
+
+  // Put the > of a multi-line element at the end of the last line
+  bracketSameLine: false,
+
+  // Include parentheses around a sole arrow function parameter
+  arrowParens: 'always',
+
+  // =============================================
+  // JSX Formatting
+  // =============================================
+
+  // Use single quotes in JSX
+  jsxSingleQuote: false,
+
+  // =============================================
+  // Plugins
+  // =============================================
+
+  // Tailwind CSS class sorting plugin
+  plugins: ['prettier-plugin-tailwindcss'],
+
+  // =============================================
+  // File-specific Overrides
+  // =============================================
+
+  overrides: [
+    {
+      // JSON files should use 2-space indentation
+      files: '*.json',
+      options: {
+        tabWidth: 2,
+      },
+    },
+    {
+      // Markdown files have wider print width
+      files: '*.md',
+      options: {
+        printWidth: 100,
+        proseWrap: 'always',
+      },
+    },
+  ],
+};
+
+export default config;

frontend/src/app/globals.css

@@ -0,0 +1,438 @@
+/**
+ * Global Styles for RAG Chatbot Frontend
+ *
+ * This file contains global CSS variables, base styles, and
+ * utility classes that complement Tailwind CSS.
+ *
+ * Color Theme: Modern Purple AI-Assistant Aesthetic
+ * ================================================
+ * The purple color palette was chosen to convey intelligence, creativity,
+ * and technological sophistication - qualities often associated with AI assistants.
+ * Purple combines the stability of blue with the energy of red, creating a
+ * balanced, professional appearance suitable for a chatbot interface.
+ *
+ * @see https://tailwindcss.com/docs/adding-custom-styles
+ */
+
+@import 'tailwindcss';
+@plugin "@tailwindcss/typography";
+@import "highlight.js/styles/atom-one-dark.css";
+
+/**
+ * CSS Custom Properties (Design Tokens)
+ *
+ * These variables define the core design tokens for the application,
+ * enabling easy theming and dark mode support.
+ *
+ * Theme Selection Logic:
+ * - When `.dark` class is present on html -> dark mode (explicit override)
+ * - When `.light` class is present on html -> light mode (explicit override)
+ * - When neither class is present -> follow system preference
+ */
+
+/**
+ * Light Mode Theme (default or explicit via .light class)
+ *
+ * Applied by default and when the user explicitly selects light mode.
+ *
+ * Purple Palette Accessibility Notes:
+ * -----------------------------------
+ * - Primary 500 (#a855f7): Main brand purple, vibrant and modern
+ * - Primary 700 (#7c3aed): Used for text on white - achieves 5.0:1 contrast (WCAG AA)
+ * - Button text uses white (#ffffff) on purple-500 for 4.58:1 contrast (WCAG AA for large text)
+ * - For critical small text on purple backgrounds, use darker purple shades
+ */
+:root,
+:root.light {
+  /**
+   * Primary Brand Colors - Modern Purple Palette
+   *
+   * This gradient from light lavender (50) to deep purple (900) provides
+   * versatility for backgrounds, borders, text, and interactive states.
+   * The purple family evokes creativity, wisdom, and technological innovation.
+   */
+  --color-primary-50: #faf5ff;   /* Very light lavender - subtle backgrounds, hover states */
+  --color-primary-100: #f3e8ff;  /* Light lavender - secondary backgrounds */
+  --color-primary-200: #e9d5ff;  /* Soft purple - selection backgrounds in light mode */
+  --color-primary-300: #d8b4fe;  /* Medium-light purple - decorative elements */
+  --color-primary-400: #c084fc;  /* Medium purple - icons, secondary elements */
+  --color-primary-500: #a855f7;  /* Main purple - primary buttons, key accents */
+  --color-primary-600: #9333ea;  /* Rich purple - active states */
+  --color-primary-700: #7c3aed;  /* Dark purple - hover states, accessible text */
+  --color-primary-800: #6b21a8;  /* Deep purple - pressed states */
+  --color-primary-900: #581c87;  /* Darkest purple - text on light backgrounds */
+
+  /**
+   * Accessible Primary Text Color
+   *
+   * #7c3aed (purple-700) provides 5.0:1 contrast ratio on white (#ffffff),
+   * exceeding the WCAG AA requirement of 4.5:1 for normal text.
+   * This ensures readability for links, labels, and highlighted text
+   * while maintaining the purple brand identity.
+   *
+   * Contrast verification: https://webaim.org/resources/contrastchecker/
+   * - #7c3aed on #ffffff = 5.0:1 (passes WCAG AA for normal text)
+   * - #7c3aed on #f8fafc = 4.85:1 (passes WCAG AA for large text, AAA for UI components)
+   */
+  --color-primary-text: #7c3aed;
+  /* WCAG AA: 5.0:1 on white */
+
+  /**
+   * Primary Button Text Color
+   *
+   * White (#ffffff) text on purple-500 (#a855f7) background provides
+   * 4.58:1 contrast ratio. This passes WCAG AA for large text (18pt+)
+   * and UI components. For buttons with smaller text, consider using
+   * a darker purple background (600 or 700) to achieve higher contrast.
+   *
+   * Contrast verification:
+   * - #ffffff on #a855f7 = 4.58:1 (passes WCAG AA for large text/UI)
+   * - #ffffff on #9333ea = 5.69:1 (passes WCAG AA for all text sizes)
+   */
+  --color-primary-button-text: #ffffff;
+  /* WCAG AA: 4.58:1 on primary-500 (large text/UI), 5.69:1 on primary-600 */
+
+  /* Background colors */
+  --background: #ffffff;
+  --background-secondary: #f8fafc;
+  --background-tertiary: #f1f5f9;
+
+  /* Text colors */
+  --foreground: #0f172a;
+  --foreground-secondary: #475569;
+  --foreground-muted: #64748b;
+  /* WCAG AA: 4.76:1 on white, 4.55:1 on bg-secondary */
+
+  /**
+   * Border Colors
+   *
+   * --border: Decorative borders for visual separation (cards, dividers)
+   * --border-ui: Essential UI component borders (inputs, selects) - higher contrast
+   * --border-focus: Focus ring color using purple-500 for brand consistency
+   */
+  --border: #e2e8f0;
+  /* Decorative borders - use --border-ui for essential UI */
+  --border-ui: #767f8c;
+  /* WCAG AA: 4.05:1 on white for essential UI components */
+  --border-focus: #a855f7;
+  /* Purple-500: Visible focus indicator matching brand color */
+
+  /* Status colors */
+  --success: #22c55e;
+  --warning: #f59e0b;
+  --error: #ef4444;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+
+  /* Border radius */
+  --radius-sm: 0.375rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+  --radius-full: 9999px;
+
+  /* Transitions */
+  --transition-fast: 150ms ease;
+  --transition-normal: 200ms ease;
+  --transition-slow: 300ms ease;
+
+  /* Easing functions */
+  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --ease-in: cubic-bezier(0.4, 0, 1, 1);
+}
+
+/**
+ * Dark Mode Theme via System Preference
+ *
+ * Automatically activated when the user's OS prefers dark color scheme
+ * AND no explicit theme class (.light or .dark) is set on the html element.
+ * This respects system preference while allowing manual override.
+ *
+ * Dark Mode Purple Adjustments:
+ * -----------------------------
+ * - Focus border uses purple-400 (#c084fc) for better visibility on dark backgrounds
+ * - Lighter purple shades become more prominent to maintain visual hierarchy
+ * - Shadows are intensified for depth perception on dark surfaces
+ */
+@media (prefers-color-scheme: dark) {
+  :root:not(.light):not(.dark) {
+    --background: #0f172a;
+    --background-secondary: #1e293b;
+    --background-tertiary: #334155;
+
+    --foreground: #f8fafc;
+    --foreground-secondary: #cbd5e1;
+    --foreground-muted: #a3afc0;
+    /* WCAG AA: 8.03:1 on bg, 6.58:1 on bg-secondary, 4.66:1 on bg-tertiary */
+
+    --border: #334155;
+    /* Decorative borders - use --border-ui for essential UI */
+    --border-ui: #64748b;
+    /* WCAG AA: 3.75:1 on dark bg for essential UI components */
+    --border-focus: #c084fc;
+    /* Purple-400: Brighter purple for visibility on dark backgrounds */
+
+    --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.3);
+    --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.4);
+    --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.5);
+  }
+}
+
+/**
+ * Dark Mode Theme via Explicit Class
+ *
+ * Applied when the user explicitly selects dark mode via the theme toggle.
+ * This overrides the system preference, allowing users to choose dark mode
+ * even when their OS is set to light mode.
+ *
+ * Matches the system-preference dark mode settings for consistency.
+ */
+:root.dark {
+  --background: #0f172a;
+  --background-secondary: #1e293b;
+  --background-tertiary: #334155;
+
+  --foreground: #f8fafc;
+  --foreground-secondary: #cbd5e1;
+  --foreground-muted: #a3afc0;
+  /* WCAG AA: 8.03:1 on bg, 6.58:1 on bg-secondary, 4.66:1 on bg-tertiary */
+
+  --border: #334155;
+  /* Decorative borders - use --border-ui for essential UI */
+  --border-ui: #64748b;
+  /* WCAG AA: 3.75:1 on dark bg for essential UI components */
+  --border-focus: #c084fc;
+  /* Purple-400: Brighter purple for visibility on dark backgrounds */
+
+  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.3);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.4);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.5);
+}
+
+/**
+ * Base Element Styles
+ *
+ * Apply consistent base styles to HTML elements.
+ */
+html {
+  /* Smooth scrolling for anchor links */
+  scroll-behavior: smooth;
+}
+
+body {
+  /* Apply design tokens to body */
+  background-color: var(--background);
+  color: var(--foreground);
+
+  /* Optimize text rendering */
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/**
+ * Focus Styles
+ *
+ * Consistent focus ring for accessibility.
+ * Uses the purple brand color for cohesive visual identity
+ * while maintaining clear focus indication for keyboard navigation.
+ */
+:focus-visible {
+  outline: 2px solid var(--border-focus);
+  outline-offset: 2px;
+}
+
+/**
+ * Selection Styles
+ *
+ * Custom text selection colors using the purple palette.
+ *
+ * Light mode: Light purple background (#e9d5ff / primary-200) with dark purple text
+ * Dark mode: Dark purple background (#7c3aed / primary-700) with light lavender text
+ *
+ * These combinations ensure selected text remains readable while
+ * reinforcing the purple brand identity throughout the interface.
+ */
+::selection {
+  background-color: var(--color-primary-200);
+  /* #e9d5ff - soft purple selection background */
+  color: var(--color-primary-900);
+  /* #581c87 - dark purple text for contrast */
+}
+
+/**
+ * Dark mode selection styles via system preference
+ * Applied when no explicit theme class is set and system prefers dark mode
+ */
+@media (prefers-color-scheme: dark) {
+  :root:not(.light):not(.dark) ::selection {
+    background-color: var(--color-primary-700);
+    /* #7c3aed - rich purple background */
+    color: var(--color-primary-50);
+    /* #faf5ff - light lavender text */
+  }
+}
+
+/**
+ * Dark mode selection styles via explicit class
+ * Applied when .dark class is set on html element
+ */
+:root.dark ::selection {
+  background-color: var(--color-primary-700);
+  /* #7c3aed - rich purple background */
+  color: var(--color-primary-50);
+  /* #faf5ff - light lavender text */
+}
+
+/**
+ * Scrollbar Styles (Webkit)
+ *
+ * Custom scrollbar appearance for webkit browsers.
+ */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: var(--background-secondary);
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--foreground-muted);
+  border-radius: var(--radius-full);
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--foreground-secondary);
+}
+
+/**
+ * Custom Animation Keyframes
+ */
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes slideUp {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes pulse {
+
+  0%,
+  100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: 0.5;
+  }
+}
+
+/**
+ * Fade and slide in animation for staggered list items.
+ * Used by SourceCitations component for smooth entrance effects.
+ */
+@keyframes fadeSlideIn {
+  from {
+    opacity: 0;
+    transform: translateY(0.5rem);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/**
+ * Utility Classes
+ */
+.animate-fade-in {
+  animation: fadeIn var(--transition-normal) ease-out;
+}
+
+.animate-slide-up {
+  animation: slideUp var(--transition-slow) ease-out;
+}
+
+.animate-pulse-custom {
+  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+/**
+ * Thermal Comfort Illustration Animations
+ *
+ * Custom keyframes for the ThermalComfortIllustration component.
+ * These provide subtle, professional animations that enhance the
+ * visual appeal without being distracting.
+ */
+
+/**
+ * Gentle floating animation for the main illustration container.
+ * Creates a subtle up-and-down motion suggesting thermal air currents.
+ */
+@keyframes thermalFloat {
+
+  0%,
+  100% {
+    transform: translateY(0);
+  }
+
+  50% {
+    transform: translateY(-4px);
+  }
+}
+
+/**
+ * Soft pulse animation for comfort zone elements.
+ * Provides a gentle "breathing" effect to indicate active thermal monitoring.
+ */
+@keyframes thermalPulse {
+
+  0%,
+  100% {
+    opacity: 1;
+    transform: scale(1);
+  }
+
+  50% {
+    opacity: 0.7;
+    transform: scale(0.98);
+  }
+}
+
+/**
+ * Wave animation for air flow lines.
+ * Creates a gentle horizontal shift suggesting air movement.
+ */
+@keyframes thermalWave {
+
+  0%,
+  100% {
+    transform: translateX(0);
+    opacity: 0.6;
+  }
+
+  50% {
+    transform: translateX(3px);
+    opacity: 0.9;
+  }
+}

frontend/src/app/layout.tsx

@@ -0,0 +1,124 @@
+/**
+ * Root Layout Component
+ *
+ * This is the root layout for the Next.js App Router. It wraps all pages
+ * and provides the base HTML structure, fonts, and global styles.
+ *
+ * @see https://nextjs.org/docs/app/building-your-application/routing/layouts-and-templates
+ */
+
+import type { Metadata, Viewport } from 'next';
+import { Inter, JetBrains_Mono } from 'next/font/google';
+import './globals.css';
+import { Providers } from './providers';
+
+/**
+ * Inter font configuration.
+ *
+ * Inter is used as the primary sans-serif font for its excellent
+ * readability and modern appearance.
+ */
+const inter = Inter({
+  variable: '--font-inter',
+  subsets: ['latin'],
+  display: 'swap',
+});
+
+/**
+ * JetBrains Mono font configuration.
+ *
+ * Used for code blocks and monospace text to ensure
+ * consistent character widths.
+ */
+const jetbrainsMono = JetBrains_Mono({
+  variable: '--font-mono',
+  subsets: ['latin'],
+  display: 'swap',
+});
+
+/**
+ * Application metadata for SEO and social sharing.
+ */
+export const metadata: Metadata = {
+  title: {
+    default: 'pythermalcomfort Chat',
+    template: '%s | pythermalcomfort Chat',
+  },
+  description:
+    'Ask questions about thermal comfort standards and the pythermalcomfort Python library. Powered by RAG with multiple LLM providers.',
+  keywords: [
+    'thermal comfort',
+    'pythermalcomfort',
+    'ASHRAE',
+    'PMV',
+    'PPD',
+    'adaptive comfort',
+    'building science',
+    'HVAC',
+  ],
+  authors: [{ name: 'pythermalcomfort Team' }],
+  creator: 'pythermalcomfort',
+  openGraph: {
+    type: 'website',
+    locale: 'en_US',
+    title: 'pythermalcomfort Chat',
+    description:
+      'AI-powered assistant for thermal comfort standards and pythermalcomfort library.',
+    siteName: 'pythermalcomfort Chat',
+  },
+  robots: {
+    index: true,
+    follow: true,
+  },
+};
+
+/**
+ * Viewport configuration for responsive design.
+ */
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  themeColor: [
+    { media: '(prefers-color-scheme: light)', color: '#ffffff' },
+    { media: '(prefers-color-scheme: dark)', color: '#0f172a' },
+  ],
+};
+
+/**
+ * Root Layout Props
+ */
+interface RootLayoutProps {
+  /** Page content to render */
+  children: React.ReactNode;
+}
+
+/**
+ * Root Layout Component
+ *
+ * Provides the base HTML structure for all pages in the application.
+ * Includes font loading, global styles, and common meta tags.
+ *
+ * @param props - Component props containing children to render
+ * @returns The root HTML structure wrapping all page content
+ */
+export default function RootLayout({
+  children,
+}: RootLayoutProps): React.ReactElement {
+  return (
+    <html
+      lang="en"
+      className={`${inter.variable} ${jetbrainsMono.variable}`}
+      suppressHydrationWarning
+    >
+      <body className="min-h-screen bg-[var(--background)] font-sans text-[var(--foreground)] antialiased">
+        {/*
+          Main application content
+          The flex layout ensures footer stays at bottom
+        */}
+        <Providers>
+          <div className="flex min-h-screen flex-col">{children}</div>
+        </Providers>
+      </body>
+    </html>
+  );
+}

frontend/src/app/loading.tsx

@@ -0,0 +1,30 @@
+/**
+ * Loading Component
+ *
+ * This component is displayed while page content is loading.
+ * Next.js automatically shows this during navigation.
+ *
+ * @see https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming
+ */
+
+/**
+ * Loading Skeleton
+ *
+ * Displays a loading animation while the page content loads.
+ * Uses a pulsing skeleton pattern for visual feedback.
+ *
+ * @returns Loading state UI
+ */
+export default function Loading(): React.ReactElement {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <div className="flex flex-col items-center gap-4">
+        {/* Spinning loader */}
+        <div className="h-8 w-8 animate-spin rounded-full border-2 border-[var(--foreground-muted)] border-t-[var(--color-primary-500)]" />
+
+        {/* Loading text */}
+        <p className="text-sm text-[var(--foreground-muted)]">Loading...</p>
+      </div>
+    </div>
+  );
+}

frontend/src/app/page.tsx

@@ -0,0 +1,107 @@
+/**
+ * Home Page Component
+ *
+ * The main landing page for the pythermalcomfort RAG Chatbot.
+ * Displays the full chat interface for interacting with the
+ * AI assistant about thermal comfort standards.
+ *
+ * @see https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts
+ */
+
+'use client';
+
+import { MessageSquare } from 'lucide-react';
+import { ChatContainer, Sidebar } from '@/components/chat';
+
+/**
+ * Home Page
+ *
+ * Renders the complete chat interface for the pythermalcomfort
+ * RAG chatbot. The page uses a full-height layout with the
+ * ChatContainer taking up the entire viewport.
+ *
+ * @remarks
+ * ## Layout Structure
+ *
+ * The page uses a Gemini-style layout with:
+ * - App title fixed in the top-left corner (like "Gemini" branding)
+ * - Collapsible sidebar showing current provider/model
+ * - Chat container centered in the remaining space
+ * - Full viewport height
+ *
+ * ## Responsive Design
+ *
+ * - On mobile: Sidebar hidden, chat fills screen
+ * - On tablet/desktop: Sidebar visible, collapsible
+ *
+ * ## Chat Configuration
+ *
+ * The ChatContainer is configured with:
+ * - No internal header (title is at page level)
+ * - Empty initial messages (fresh conversation)
+ * - No persistence callback (can be added for localStorage support)
+ *
+ * @returns The home page with chat interface
+ */
+export default function HomePage(): React.ReactElement {
+  return (
+    <main
+      className={
+        /* Full viewport height layout */
+        'flex min-h-screen flex-col ' +
+        /* Background color from design tokens */
+        'bg-[var(--background-secondary)]'
+      }
+    >
+      {/*
+        Page Header - Gemini-style branding in top-left
+
+        Fixed position at top-left of the page, outside the chat area.
+        This mimics how Gemini shows its logo/name.
+      */}
+      <header className="shrink-0 px-4 py-3">
+        <div className="flex items-center gap-2">
+          <MessageSquare
+            className="h-5 w-5 text-[var(--color-primary-500)]"
+            strokeWidth={2}
+            aria-hidden="true"
+          />
+          <span className="text-base font-medium text-[var(--foreground)]">
+            pythermalcomfort Chat
+          </span>
+        </div>
+        <p className="text-[10px] text-gray-400 dark:text-gray-500 mt-0.5 ml-7">
+          AI-powered answers from scientific sources and official documentation
+        </p>
+      </header>
+
+      {/*
+        Main Content Area - Sidebar + Chat
+
+        Horizontal layout with collapsible sidebar on left
+        and chat container filling the remaining space.
+      */}
+      <div className="flex flex-1 overflow-hidden">
+        {/*
+          Left Sidebar - Provider/Model Info
+
+          Shows current LLM provider and model name.
+          Collapsible to icon-only mode.
+          Hidden on mobile for better space utilization.
+        */}
+        <Sidebar className="hidden sm:flex" />
+
+        {/*
+          ChatContainer - Main chat interface
+
+          Fills the remaining space after sidebar.
+          No internal header - the title is shown at page level above.
+        */}
+        <ChatContainer
+          showHeader={false}
+          className="flex-1 px-2 sm:px-4 md:px-6 lg:px-8 pb-0.5 sm:pb-1"
+        />
+      </div>
+    </main>
+  );
+}

frontend/src/app/providers.tsx

@@ -0,0 +1,28 @@
+/**
+ * Client-side Providers Wrapper
+ *
+ * Wraps children with all client-side context providers.
+ * This component is used by the root layout to provide
+ * shared state to all pages.
+ *
+ * @module app/providers
+ */
+
+'use client';
+
+import type { ReactNode } from 'react';
+import { ProviderProvider } from '@/contexts/provider-context';
+
+interface ProvidersProps {
+  children: ReactNode;
+}
+
+/**
+ * Providers Component
+ *
+ * Wraps the application with all necessary context providers.
+ * Add additional providers here as needed.
+ */
+export function Providers({ children }: ProvidersProps): React.ReactElement {
+  return <ProviderProvider>{children}</ProviderProvider>;
+}

frontend/src/components/chat/__tests__/__snapshots__/empty-state.test.tsx.snap

@@ -0,0 +1,368 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`EmptyState > snapshots > should render correctly (snapshot) 1`] = `
+<div
+  class="mx-auto w-full max-w-2xl px-4 py-8 animate-slide-up"
+>
+  <div
+    class="bg-[var(--background-secondary)]/80 backdrop-blur-sm border border-[var(--border)] rounded-2xl shadow-[var(--shadow-lg)] p-8"
+  >
+    <div
+      class="mb-6 flex justify-center"
+    >
+      <div
+        class="h-24 w-24 flex items-center justify-center"
+      >
+        <svg
+          aria-hidden="true"
+          class="h-20 w-20 motion-safe:animate-[thermalFloat_4s_ease-in-out_infinite]"
+          fill="none"
+          role="img"
+          viewBox="0 0 100 100"
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <defs>
+            <lineargradient
+              id="buildingGradient"
+              x1="0%"
+              x2="100%"
+              y1="0%"
+              y2="100%"
+            >
+              <stop
+                offset="0%"
+                stop-color="var(--color-primary-400)"
+              />
+              <stop
+                offset="100%"
+                stop-color="var(--color-primary-600)"
+              />
+            </lineargradient>
+            <radialgradient
+              cx="50%"
+              cy="50%"
+              fx="30%"
+              fy="30%"
+              id="comfortZoneGradient"
+              r="50%"
+            >
+              <stop
+                offset="0%"
+                stop-color="var(--color-primary-200)"
+                stop-opacity="0.8"
+              />
+              <stop
+                offset="70%"
+                stop-color="var(--color-primary-300)"
+                stop-opacity="0.4"
+              />
+              <stop
+                offset="100%"
+                stop-color="var(--color-primary-400)"
+                stop-opacity="0.1"
+              />
+            </radialgradient>
+            <lineargradient
+              id="thermoGradient"
+              x1="0%"
+              x2="0%"
+              y1="100%"
+              y2="0%"
+            >
+              <stop
+                offset="0%"
+                stop-color="var(--color-primary-300)"
+              />
+              <stop
+                offset="50%"
+                stop-color="var(--color-primary-500)"
+              />
+              <stop
+                offset="100%"
+                stop-color="var(--color-primary-600)"
+              />
+            </lineargradient>
+            <lineargradient
+              id="waveGradient"
+              x1="0%"
+              x2="100%"
+              y1="0%"
+              y2="0%"
+            >
+              <stop
+                offset="0%"
+                stop-color="var(--color-primary-300)"
+                stop-opacity="0.2"
+              />
+              <stop
+                offset="50%"
+                stop-color="var(--color-primary-400)"
+                stop-opacity="0.6"
+              />
+              <stop
+                offset="100%"
+                stop-color="var(--color-primary-300)"
+                stop-opacity="0.2"
+              />
+            </lineargradient>
+          </defs>
+          <circle
+            class="motion-safe:animate-[thermalPulse_3s_ease-in-out_infinite]"
+            cx="50"
+            cy="50"
+            fill="url(#comfortZoneGradient)"
+            r="42"
+          />
+          <g
+            transform="translate(25, 28)"
+          >
+            <path
+              d="M5 45 L5 18 L25 8 L45 18 L45 45 Z"
+              fill="url(#buildingGradient)"
+              stroke="var(--color-primary-700)"
+              stroke-linejoin="round"
+              stroke-width="1"
+            />
+            <path
+              d="M5 18 L25 8 L45 18"
+              fill="none"
+              stroke="var(--color-primary-700)"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              stroke-width="1.5"
+            />
+            <rect
+              fill="var(--color-primary-100)"
+              height="6"
+              opacity="0.9"
+              rx="1"
+              width="6"
+              x="10"
+              y="22"
+            />
+            <rect
+              fill="var(--color-primary-100)"
+              height="6"
+              opacity="0.9"
+              rx="1"
+              width="6"
+              x="10"
+              y="32"
+            />
+            <rect
+              fill="var(--color-primary-100)"
+              height="6"
+              opacity="0.9"
+              rx="1"
+              width="6"
+              x="34"
+              y="22"
+            />
+            <rect
+              fill="var(--color-primary-100)"
+              height="6"
+              opacity="0.9"
+              rx="1"
+              width="6"
+              x="34"
+              y="32"
+            />
+            <rect
+              fill="var(--color-primary-200)"
+              height="13"
+              rx="1"
+              width="10"
+              x="20"
+              y="32"
+            />
+            <circle
+              cx="27"
+              cy="39"
+              fill="var(--color-primary-600)"
+              r="1"
+            />
+          </g>
+          <g
+            transform="translate(72, 25)"
+          >
+            <path
+              d="M6 0 C2.7 0 0 2.7 0 6 L0 35 C-2 37 -3 40 -3 43 C-3 49 2 54 8 54 C14 54 19 49 19 43 C19 40 18 37 16 35 L16 6 C16 2.7 13.3 0 10 0 Z"
+              fill="var(--color-primary-100)"
+              stroke="var(--color-primary-400)"
+              stroke-width="1.5"
+            />
+            <path
+              class="motion-safe:animate-[thermalPulse_3s_ease-in-out_infinite_0.5s]"
+              d="M6 38 L6 10 C6 8 7 7 8 7 C9 7 10 8 10 10 L10 38 C12 39 14 41 14 43 C14 47 11 50 8 50 C5 50 2 47 2 43 C2 41 4 39 6 38 Z"
+              fill="url(#thermoGradient)"
+            />
+            <line
+              stroke="var(--color-primary-400)"
+              stroke-width="1"
+              x1="12"
+              x2="14"
+              y1="15"
+              y2="15"
+            />
+            <line
+              stroke="var(--color-primary-400)"
+              stroke-width="1"
+              x1="12"
+              x2="14"
+              y1="22"
+              y2="22"
+            />
+            <line
+              stroke="var(--color-primary-400)"
+              stroke-width="1"
+              x1="12"
+              x2="14"
+              y1="29"
+              y2="29"
+            />
+          </g>
+          <g
+            class="motion-safe:animate-[thermalWave_2s_ease-in-out_infinite]"
+          >
+            <path
+              d="M12 30 Q22 26 32 30 Q42 34 52 30"
+              fill="none"
+              opacity="0.7"
+              stroke="url(#waveGradient)"
+              stroke-linecap="round"
+              stroke-width="2"
+            />
+          </g>
+          <g
+            class="motion-safe:animate-[thermalWave_2s_ease-in-out_infinite_0.3s]"
+          >
+            <path
+              d="M8 42 Q18 38 28 42 Q38 46 48 42"
+              fill="none"
+              opacity="0.5"
+              stroke="url(#waveGradient)"
+              stroke-linecap="round"
+              stroke-width="2"
+            />
+          </g>
+          <g
+            class="motion-safe:animate-[thermalWave_2s_ease-in-out_infinite_0.6s]"
+          >
+            <path
+              d="M15 55 Q25 51 35 55 Q45 59 55 55"
+              fill="none"
+              opacity="0.6"
+              stroke="url(#waveGradient)"
+              stroke-linecap="round"
+              stroke-width="2"
+            />
+          </g>
+          <circle
+            class="motion-safe:animate-[thermalPulse_2s_ease-in-out_infinite_0.2s]"
+            cx="18"
+            cy="22"
+            fill="var(--color-primary-400)"
+            opacity="0.6"
+            r="2"
+          />
+          <circle
+            class="motion-safe:animate-[thermalPulse_2s_ease-in-out_infinite_0.8s]"
+            cx="82"
+            cy="72"
+            fill="var(--color-primary-300)"
+            opacity="0.5"
+            r="2.5"
+          />
+          <circle
+            class="motion-safe:animate-[thermalPulse_2s_ease-in-out_infinite_1.2s]"
+            cx="15"
+            cy="75"
+            fill="var(--color-primary-500)"
+            opacity="0.4"
+            r="1.5"
+          />
+        </svg>
+      </div>
+    </div>
+    <div
+      class="mb-8 text-center"
+    >
+      <h2
+        class="text-2xl font-bold text-[var(--foreground)] mb-2"
+      >
+        Ask about thermal comfort and pythermalcomfort
+      </h2>
+      <p
+        class="text-[var(--foreground-secondary)] text-sm leading-relaxed mx-auto max-w-md"
+      >
+        Get answers about thermal comfort models, concepts, standards and the pythermalcomfort library. Your questions are answered using scientific sources and official documentations.
+      </p>
+    </div>
+    <div
+      class="space-y-3"
+    >
+      <p
+        class="text-xs font-medium tracking-wide uppercase text-[var(--foreground-muted)] mb-3 px-1"
+      >
+        Try asking
+      </p>
+      <div
+        class="grid gap-3 sm:grid-cols-2"
+      >
+        <button
+          class="w-full text-left px-4 py-3 bg-[var(--background)] border border-[var(--border)] rounded-[var(--radius-lg)] shadow-[var(--shadow-sm)] text-sm text-[var(--foreground)] flex items-start gap-3 hover:border-[var(--color-primary-300)] hover:bg-[var(--background-secondary)] hover:shadow-[var(--shadow-md)] transition-all duration-[var(--transition-fast)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2 cursor-pointer"
+          type="button"
+        >
+          <span
+            aria-hidden="true"
+            class="mt-0.5 h-4 w-4 shrink-0 text-[var(--color-primary-500)]"
+            data-testid="message-square-icon"
+          />
+          <span>
+            What is the PMV model and how do I calculate it?
+          </span>
+        </button>
+        <button
+          class="w-full text-left px-4 py-3 bg-[var(--background)] border border-[var(--border)] rounded-[var(--radius-lg)] shadow-[var(--shadow-sm)] text-sm text-[var(--foreground)] flex items-start gap-3 hover:border-[var(--color-primary-300)] hover:bg-[var(--background-secondary)] hover:shadow-[var(--shadow-md)] transition-all duration-[var(--transition-fast)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2 cursor-pointer"
+          type="button"
+        >
+          <span
+            aria-hidden="true"
+            class="mt-0.5 h-4 w-4 shrink-0 text-[var(--color-primary-500)]"
+            data-testid="message-square-icon"
+          />
+          <span>
+            How do I use the adaptive comfort model in pythermalcomfort?
+          </span>
+        </button>
+        <button
+          class="w-full text-left px-4 py-3 bg-[var(--background)] border border-[var(--border)] rounded-[var(--radius-lg)] shadow-[var(--shadow-sm)] text-sm text-[var(--foreground)] flex items-start gap-3 hover:border-[var(--color-primary-300)] hover:bg-[var(--background-secondary)] hover:shadow-[var(--shadow-md)] transition-all duration-[var(--transition-fast)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2 cursor-pointer"
+          type="button"
+        >
+          <span
+            aria-hidden="true"
+            class="mt-0.5 h-4 w-4 shrink-0 text-[var(--color-primary-500)]"
+            data-testid="message-square-icon"
+          />
+          <span>
+            What are the inputs for calculating thermal comfort indices?
+          </span>
+        </button>
+        <button
+          class="w-full text-left px-4 py-3 bg-[var(--background)] border border-[var(--border)] rounded-[var(--radius-lg)] shadow-[var(--shadow-sm)] text-sm text-[var(--foreground)] flex items-start gap-3 hover:border-[var(--color-primary-300)] hover:bg-[var(--background-secondary)] hover:shadow-[var(--shadow-md)] transition-all duration-[var(--transition-fast)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2 cursor-pointer"
+          type="button"
+        >
+          <span
+            aria-hidden="true"
+            class="mt-0.5 h-4 w-4 shrink-0 text-[var(--color-primary-500)]"
+            data-testid="message-square-icon"
+          />
+          <span>
+            Explain the difference between SET and PMV thermal comfort models.
+          </span>
+        </button>
+      </div>
+    </div>
+  </div>
+</div>
+`;

frontend/src/components/chat/__tests__/__snapshots__/error-state.test.tsx.snap

@@ -0,0 +1,222 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ErrorState > snapshots > should render general type correctly (snapshot) 1`] = `
+<div
+  aria-live="assertive"
+  class="mx-auto w-full max-w-lg px-4 py-6 animate-slide-up"
+  role="alert"
+>
+  <div
+    class="bg-[var(--background-secondary)]/80 backdrop-blur-sm border border-red-300 rounded-2xl shadow-[var(--shadow-lg)] p-6 relative"
+  >
+    <button
+      aria-label="Dismiss error"
+      class="absolute top-3 right-3 h-8 w-8 rounded-full flex items-center justify-center text-[var(--foreground-muted)] hover:bg-[var(--background-tertiary)] hover:text-[var(--foreground-secondary)] transition-colors duration-[var(--transition-fast)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2"
+      type="button"
+    >
+      <span
+        aria-hidden="true"
+        class="h-4 w-4"
+        data-testid="x-icon"
+      />
+    </button>
+    <div
+      class="mb-4 flex justify-center"
+    >
+      <div
+        class="h-14 w-14 rounded-full bg-gradient-to-br from-red-100 to-red-200 flex items-center justify-center shadow-[var(--shadow-md)]"
+      >
+        <span
+          aria-hidden="true"
+          class="h-7 w-7 text-red-600"
+          data-testid="alert-triangle-icon"
+        />
+      </div>
+    </div>
+    <div
+      class="mb-4 text-center"
+    >
+      <h3
+        class="text-lg font-semibold text-[var(--foreground)] mb-2"
+      >
+        Oops! Something Went Wrong
+      </h3>
+      <p
+        class="text-[var(--foreground-secondary)] text-sm leading-relaxed mx-auto max-w-sm"
+      >
+        A custom error message for the snapshot test.
+      </p>
+    </div>
+    <div
+      class="flex justify-center"
+    >
+      <button
+        class="px-5 py-2.5 rounded-[var(--radius-lg)] text-sm font-medium inline-flex items-center gap-2 bg-red-500 text-white hover:bg-red-600 disabled:bg-red-200 disabled:text-red-400 shadow-[var(--shadow-sm)] transition-all duration-[var(--transition-fast)] hover:shadow-[var(--shadow-md)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:shadow-none"
+        type="button"
+      >
+        <span
+          aria-hidden="true"
+          class="h-4 w-4"
+          data-testid="refresh-icon"
+        />
+        <span>
+          Try Again
+        </span>
+      </button>
+    </div>
+  </div>
+</div>
+`;
+
+exports[`ErrorState > snapshots > should render network type correctly (snapshot) 1`] = `
+<div
+  aria-live="assertive"
+  class="mx-auto w-full max-w-lg px-4 py-6 animate-slide-up"
+  role="alert"
+>
+  <div
+    class="bg-[var(--background-secondary)]/80 backdrop-blur-sm border border-blue-300 rounded-2xl shadow-[var(--shadow-lg)] p-6 relative"
+  >
+    <button
+      aria-label="Dismiss error"
+      class="absolute top-3 right-3 h-8 w-8 rounded-full flex items-center justify-center text-[var(--foreground-muted)] hover:bg-[var(--background-tertiary)] hover:text-[var(--foreground-secondary)] transition-colors duration-[var(--transition-fast)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2"
+      type="button"
+    >
+      <span
+        aria-hidden="true"
+        class="h-4 w-4"
+        data-testid="x-icon"
+      />
+    </button>
+    <div
+      class="mb-4 flex justify-center"
+    >
+      <div
+        class="h-14 w-14 rounded-full bg-gradient-to-br from-blue-100 to-blue-200 flex items-center justify-center shadow-[var(--shadow-md)]"
+      >
+        <span
+          aria-hidden="true"
+          class="h-7 w-7 text-blue-600"
+          data-testid="wifi-off-icon"
+        />
+      </div>
+    </div>
+    <div
+      class="mb-4 text-center"
+    >
+      <h3
+        class="text-lg font-semibold text-[var(--foreground)] mb-2"
+      >
+        Connection Lost
+      </h3>
+      <p
+        class="text-[var(--foreground-secondary)] text-sm leading-relaxed mx-auto max-w-sm"
+      >
+        Unable to connect. Please check your internet connection.
+      </p>
+    </div>
+    <div
+      class="flex justify-center"
+    >
+      <button
+        class="px-5 py-2.5 rounded-[var(--radius-lg)] text-sm font-medium inline-flex items-center gap-2 bg-blue-500 text-white hover:bg-blue-600 disabled:bg-blue-200 disabled:text-blue-400 shadow-[var(--shadow-sm)] transition-all duration-[var(--transition-fast)] hover:shadow-[var(--shadow-md)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:shadow-none"
+        type="button"
+      >
+        <span
+          aria-hidden="true"
+          class="h-4 w-4"
+          data-testid="refresh-icon"
+        />
+        <span>
+          Try Again
+        </span>
+      </button>
+    </div>
+  </div>
+</div>
+`;
+
+exports[`ErrorState > snapshots > should render quota type correctly (snapshot) 1`] = `
+<div
+  aria-live="assertive"
+  class="mx-auto w-full max-w-lg px-4 py-6 animate-slide-up"
+  role="alert"
+>
+  <div
+    class="bg-[var(--background-secondary)]/80 backdrop-blur-sm border border-[var(--color-primary-300)] rounded-2xl shadow-[var(--shadow-lg)] p-6 relative"
+  >
+    <button
+      aria-label="Dismiss error"
+      class="absolute top-3 right-3 h-8 w-8 rounded-full flex items-center justify-center text-[var(--foreground-muted)] hover:bg-[var(--background-tertiary)] hover:text-[var(--foreground-secondary)] transition-colors duration-[var(--transition-fast)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2"
+      type="button"
+    >
+      <span
+        aria-hidden="true"
+        class="h-4 w-4"
+        data-testid="x-icon"
+      />
+    </button>
+    <div
+      class="mb-4 flex justify-center"
+    >
+      <div
+        class="h-14 w-14 rounded-full bg-gradient-to-br from-[var(--color-primary-100)] to-[var(--color-primary-200)] flex items-center justify-center shadow-[var(--shadow-md)]"
+      >
+        <span
+          aria-hidden="true"
+          class="h-7 w-7 text-[var(--color-primary-600)]"
+          data-testid="clock-icon"
+        />
+      </div>
+    </div>
+    <div
+      class="mb-4 text-center"
+    >
+      <h3
+        class="text-lg font-semibold text-[var(--foreground)] mb-2"
+      >
+        Service Temporarily Unavailable
+      </h3>
+      <p
+        class="text-[var(--foreground-secondary)] text-sm leading-relaxed mx-auto max-w-sm"
+      >
+        Our service is currently at capacity. Please wait a moment.
+      </p>
+    </div>
+    <div
+      aria-atomic="true"
+      aria-live="polite"
+      class="mb-4 mx-auto max-w-xs px-4 py-2 bg-[var(--color-primary-50)]/50 border border-[var(--color-primary-200)] rounded-[var(--radius-lg)] flex items-center justify-center gap-2 animate-fade-in"
+    >
+      <span
+        aria-hidden="true"
+        class="h-4 w-4 text-[var(--color-primary-500)]"
+        data-testid="clock-icon"
+      />
+      <span
+        class="text-sm font-medium text-[var(--color-primary-700)]"
+      >
+        Try again in 45s
+      </span>
+    </div>
+    <div
+      class="flex justify-center"
+    >
+      <button
+        class="px-5 py-2.5 rounded-[var(--radius-lg)] text-sm font-medium inline-flex items-center gap-2 bg-[var(--color-primary-500)] text-[var(--color-primary-button-text)] hover:bg-[var(--color-primary-600)] disabled:bg-[var(--color-primary-200)] disabled:text-[var(--foreground-muted)] shadow-[var(--shadow-sm)] transition-all duration-[var(--transition-fast)] hover:shadow-[var(--shadow-md)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:shadow-none"
+        disabled=""
+        type="button"
+      >
+        <span
+          aria-hidden="true"
+          class="h-4 w-4 animate-pulse-custom"
+          data-testid="refresh-icon"
+        />
+        <span>
+          Please wait...
+        </span>
+      </button>
+    </div>
+  </div>
+</div>
+`;

frontend/src/components/chat/__tests__/empty-state.test.tsx

@@ -0,0 +1,375 @@
+/**
+ * Unit Tests for EmptyState Component
+ *
+ * Comprehensive test coverage for the empty state welcome component.
+ * Tests rendering, example question interactions, accessibility features,
+ * and edge cases.
+ *
+ * @module components/chat/__tests__/empty-state.test
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { EmptyState } from '../empty-state';
+
+// ============================================================================
+// Mocks
+// ============================================================================
+
+/**
+ * Mock lucide-react icons for faster tests and to avoid lazy loading issues.
+ */
+vi.mock('lucide-react', () => ({
+  MessageSquare: ({
+    className,
+    'aria-hidden': ariaHidden,
+  }: {
+    className?: string;
+    'aria-hidden'?: boolean | 'true' | 'false';
+  }) => (
+    <span
+      data-testid="message-square-icon"
+      className={className}
+      aria-hidden={ariaHidden}
+    />
+  ),
+}));
+
+// ============================================================================
+// Test Fixtures
+// ============================================================================
+
+/**
+ * Example questions that should be displayed in the component.
+ */
+const EXPECTED_QUESTIONS = [
+  'What is the PMV model and how do I calculate it?',
+  'How do I use the adaptive comfort model in pythermalcomfort?',
+  'What are the inputs for calculating thermal comfort indices?',
+  'Explain the difference between SET and PMV thermal comfort models.',
+];
+
+// ============================================================================
+// Test Suite
+// ============================================================================
+
+describe('EmptyState', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  // ==========================================================================
+  // Rendering Tests
+  // ==========================================================================
+
+  describe('rendering', () => {
+    it('should render the main title', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      expect(
+        screen.getByText('Ask about thermal comfort and pythermalcomfort')
+      ).toBeInTheDocument();
+    });
+
+    it('should render the subtitle description', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      expect(
+        screen.getByText(/get answers about thermal comfort standards/i)
+      ).toBeInTheDocument();
+    });
+
+    it('should render "Try asking" label', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      expect(screen.getByText('Try asking')).toBeInTheDocument();
+    });
+
+    it('should render all example questions', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      EXPECTED_QUESTIONS.forEach((question) => {
+        expect(screen.getByText(question)).toBeInTheDocument();
+      });
+    });
+
+    it('should render MessageSquare icon for each question', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const icons = screen.getAllByTestId('message-square-icon');
+      expect(icons).toHaveLength(EXPECTED_QUESTIONS.length);
+    });
+
+    it('should render thermal comfort illustration (SVG)', () => {
+      const { container } = render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const svg = container.querySelector('svg');
+      expect(svg).toBeInTheDocument();
+    });
+
+    it('should hide illustration from screen readers', () => {
+      const { container } = render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const svg = container.querySelector('svg');
+      expect(svg).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('should render example questions as buttons', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const buttons = screen.getAllByRole('button');
+      expect(buttons).toHaveLength(EXPECTED_QUESTIONS.length);
+    });
+  });
+
+  // ==========================================================================
+  // Interaction Tests
+  // ==========================================================================
+
+  describe('interactions', () => {
+    it('should call onExampleClick when first question is clicked', () => {
+      const mockClick = vi.fn();
+
+      render(<EmptyState onExampleClick={mockClick} />);
+
+      fireEvent.click(screen.getByText(EXPECTED_QUESTIONS[0]));
+
+      expect(mockClick).toHaveBeenCalledTimes(1);
+      expect(mockClick).toHaveBeenCalledWith(EXPECTED_QUESTIONS[0]);
+    });
+
+    it('should call onExampleClick with correct question for each button', () => {
+      const mockClick = vi.fn();
+
+      render(<EmptyState onExampleClick={mockClick} />);
+
+      EXPECTED_QUESTIONS.forEach((question, index) => {
+        fireEvent.click(screen.getByText(question));
+        expect(mockClick).toHaveBeenNthCalledWith(index + 1, question);
+      });
+
+      expect(mockClick).toHaveBeenCalledTimes(EXPECTED_QUESTIONS.length);
+    });
+
+    it('should call onExampleClick multiple times when same question clicked repeatedly', () => {
+      const mockClick = vi.fn();
+
+      render(<EmptyState onExampleClick={mockClick} />);
+
+      const firstQuestion = screen.getByText(EXPECTED_QUESTIONS[0]);
+
+      fireEvent.click(firstQuestion);
+      fireEvent.click(firstQuestion);
+      fireEvent.click(firstQuestion);
+
+      expect(mockClick).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  // ==========================================================================
+  // Accessibility Tests
+  // ==========================================================================
+
+  describe('accessibility', () => {
+    it('should have semantic heading hierarchy with h2', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const heading = screen.getByRole('heading', { level: 2 });
+      expect(heading).toBeInTheDocument();
+      expect(heading).toHaveTextContent('Ask about thermal comfort and pythermalcomfort');
+    });
+
+    it('should have focusable question buttons', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const buttons = screen.getAllByRole('button');
+      buttons.forEach((button) => {
+        button.focus();
+        expect(button).toHaveFocus();
+      });
+    });
+
+    it('should have visible focus styles on buttons', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const buttons = screen.getAllByRole('button');
+      buttons.forEach((button) => {
+        expect(button.className).toMatch(/focus-visible:ring/);
+      });
+    });
+
+    it('should have icons with aria-hidden for decorative elements', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const icons = screen.getAllByTestId('message-square-icon');
+      icons.forEach((icon) => {
+        expect(icon).toHaveAttribute('aria-hidden', 'true');
+      });
+    });
+
+    it('should support keyboard Enter to activate question buttons', () => {
+      const mockClick = vi.fn();
+
+      render(<EmptyState onExampleClick={mockClick} />);
+
+      const firstButton = screen.getAllByRole('button')[0];
+      firstButton.focus();
+
+      // Simulate Enter key (buttons natively handle this)
+      fireEvent.keyDown(firstButton, { key: 'Enter', code: 'Enter' });
+      fireEvent.click(firstButton);
+
+      expect(mockClick).toHaveBeenCalled();
+    });
+
+    it('should support keyboard Space to activate question buttons', () => {
+      const mockClick = vi.fn();
+
+      render(<EmptyState onExampleClick={mockClick} />);
+
+      const firstButton = screen.getAllByRole('button')[0];
+      firstButton.focus();
+
+      // Simulate Space key (buttons natively handle this)
+      fireEvent.keyDown(firstButton, { key: ' ', code: 'Space' });
+      fireEvent.click(firstButton);
+
+      expect(mockClick).toHaveBeenCalled();
+    });
+  });
+
+  // ==========================================================================
+  // Styling Tests
+  // ==========================================================================
+
+  describe('styling', () => {
+    it('should apply custom className to container', () => {
+      const { container } = render(
+        <EmptyState onExampleClick={vi.fn()} className="custom-class mt-8" />
+      );
+
+      const outerDiv = container.firstChild;
+      expect(outerDiv).toHaveClass('custom-class', 'mt-8');
+    });
+
+    it('should have animation class for entrance effect', () => {
+      const { container } = render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const outerDiv = container.firstChild;
+      expect(outerDiv).toHaveClass('animate-slide-up');
+    });
+
+    it('should have glassmorphism styling on card', () => {
+      const { container } = render(<EmptyState onExampleClick={vi.fn()} />);
+
+      // Find the card container (child of outer div)
+      const card = container.querySelector('.backdrop-blur-sm');
+      expect(card).toBeInTheDocument();
+    });
+  });
+
+  // ==========================================================================
+  // Edge Cases Tests
+  // ==========================================================================
+
+  describe('edge cases', () => {
+    it('should render without crashing when onExampleClick is a no-op', () => {
+      render(<EmptyState onExampleClick={() => {}} />);
+
+      expect(
+        screen.getByText('Ask about thermal comfort and pythermalcomfort')
+      ).toBeInTheDocument();
+    });
+
+    it('should forward additional HTML attributes', () => {
+      render(
+        <EmptyState
+          onExampleClick={vi.fn()}
+          data-testid="empty-state"
+          title="Welcome state"
+        />
+      );
+
+      const container = screen.getByTestId('empty-state');
+      expect(container).toHaveAttribute('title', 'Welcome state');
+    });
+
+    it('should render questions in a grid layout', () => {
+      const { container } = render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const grid = container.querySelector('.grid');
+      expect(grid).toBeInTheDocument();
+      expect(grid).toHaveClass('sm:grid-cols-2');
+    });
+
+    it('should maintain button type as "button"', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      const buttons = screen.getAllByRole('button');
+      buttons.forEach((button) => {
+        expect(button).toHaveAttribute('type', 'button');
+      });
+    });
+  });
+
+  // ==========================================================================
+  // Snapshot Tests
+  // ==========================================================================
+
+  describe('snapshots', () => {
+    it('should render correctly (snapshot)', () => {
+      const { container } = render(<EmptyState onExampleClick={vi.fn()} />);
+
+      expect(container.firstChild).toMatchSnapshot();
+    });
+  });
+
+  // ==========================================================================
+  // Integration Tests
+  // ==========================================================================
+
+  describe('integration', () => {
+    it('should render complete empty state with all elements', () => {
+      render(<EmptyState onExampleClick={vi.fn()} />);
+
+      // Title and subtitle
+      expect(
+        screen.getByText('Ask about thermal comfort and pythermalcomfort')
+      ).toBeInTheDocument();
+      expect(
+        screen.getByText(/get answers about thermal comfort/i)
+      ).toBeInTheDocument();
+
+      // "Try asking" label
+      expect(screen.getByText('Try asking')).toBeInTheDocument();
+
+      // All questions as buttons
+      const buttons = screen.getAllByRole('button');
+      expect(buttons).toHaveLength(4);
+
+      // All icons
+      const icons = screen.getAllByTestId('message-square-icon');
+      expect(icons).toHaveLength(4);
+    });
+
+    it('should work correctly through a complete user interaction flow', () => {
+      const mockClick = vi.fn();
+
+      render(<EmptyState onExampleClick={mockClick} />);
+
+      // Verify initial state
+      expect(mockClick).not.toHaveBeenCalled();
+
+      // Click first question
+      fireEvent.click(screen.getByText(EXPECTED_QUESTIONS[0]));
+      expect(mockClick).toHaveBeenLastCalledWith(EXPECTED_QUESTIONS[0]);
+
+      // Click last question
+      fireEvent.click(screen.getByText(EXPECTED_QUESTIONS[3]));
+      expect(mockClick).toHaveBeenLastCalledWith(EXPECTED_QUESTIONS[3]);
+
+      // Total clicks
+      expect(mockClick).toHaveBeenCalledTimes(2);
+    });
+  });
+});

frontend/src/components/chat/__tests__/error-state.test.tsx

@@ -0,0 +1,797 @@
+/**
+ * Unit Tests for ErrorState Component
+ *
+ * Comprehensive test coverage for the error display component.
+ * Tests rendering states, countdown timer functionality, interactions,
+ * accessibility features, and visual/snapshot tests.
+ *
+ * @module components/chat/__tests__/error-state.test
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, act } from '@testing-library/react';
+import { ErrorState, type ErrorType } from '../error-state';
+
+// ============================================================================
+// Mocks
+// ============================================================================
+
+/**
+ * Mock lucide-react icons for faster tests and to avoid lazy loading issues.
+ * Each icon is replaced with a simple span containing a test ID and class.
+ */
+vi.mock('lucide-react', () => ({
+  AlertTriangle: ({
+    className,
+    'aria-hidden': ariaHidden,
+  }: {
+    className?: string;
+    'aria-hidden'?: boolean | 'true' | 'false';
+  }) => (
+    <span
+      data-testid="alert-triangle-icon"
+      className={className}
+      aria-hidden={ariaHidden}
+    />
+  ),
+  WifiOff: ({
+    className,
+    'aria-hidden': ariaHidden,
+  }: {
+    className?: string;
+    'aria-hidden'?: boolean | 'true' | 'false';
+  }) => (
+    <span
+      data-testid="wifi-off-icon"
+      className={className}
+      aria-hidden={ariaHidden}
+    />
+  ),
+  Clock: ({
+    className,
+    'aria-hidden': ariaHidden,
+  }: {
+    className?: string;
+    'aria-hidden'?: boolean | 'true' | 'false';
+  }) => (
+    <span
+      data-testid="clock-icon"
+      className={className}
+      aria-hidden={ariaHidden}
+    />
+  ),
+  RefreshCw: ({
+    className,
+    'aria-hidden': ariaHidden,
+  }: {
+    className?: string;
+    'aria-hidden'?: boolean | 'true' | 'false';
+  }) => (
+    <span
+      data-testid="refresh-icon"
+      className={className}
+      aria-hidden={ariaHidden}
+    />
+  ),
+  X: ({
+    className,
+    'aria-hidden': ariaHidden,
+  }: {
+    className?: string;
+    'aria-hidden'?: boolean | 'true' | 'false';
+  }) => (
+    <span
+      data-testid="x-icon"
+      className={className}
+      aria-hidden={ariaHidden}
+    />
+  ),
+}));
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+/**
+ * Default error messages for each error type.
+ */
+const DEFAULT_MESSAGES: Record<ErrorType, string> = {
+  quota: 'Our service is currently at capacity. Please wait a moment.',
+  network: 'Unable to connect. Please check your internet connection.',
+  general: 'Something went wrong. Please try again.',
+};
+
+/**
+ * Titles displayed for each error type.
+ */
+const ERROR_TITLES: Record<ErrorType, string> = {
+  quota: 'Service Temporarily Unavailable',
+  network: 'Connection Lost',
+  general: 'Oops! Something Went Wrong',
+};
+
+// ============================================================================
+// Test Suite
+// ============================================================================
+
+describe('ErrorState', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  // ==========================================================================
+  // Rendering Tests
+  // ==========================================================================
+
+  describe('rendering', () => {
+    it('should render quota error type correctly with Clock icon', () => {
+      render(<ErrorState type="quota" />);
+
+      // Should show quota-specific title
+      expect(
+        screen.getByText('Service Temporarily Unavailable')
+      ).toBeInTheDocument();
+
+      // Should show default quota message
+      expect(
+        screen.getByText(DEFAULT_MESSAGES.quota)
+      ).toBeInTheDocument();
+
+      // Clock icon should be used for quota type (main icon)
+      const clockIcons = screen.getAllByTestId('clock-icon');
+      expect(clockIcons.length).toBeGreaterThan(0);
+    });
+
+    it('should render network error type correctly with WifiOff icon', () => {
+      render(<ErrorState type="network" />);
+
+      // Should show network-specific title
+      expect(screen.getByText('Connection Lost')).toBeInTheDocument();
+
+      // Should show default network message
+      expect(
+        screen.getByText(DEFAULT_MESSAGES.network)
+      ).toBeInTheDocument();
+
+      // WifiOff icon should be present
+      expect(screen.getByTestId('wifi-off-icon')).toBeInTheDocument();
+    });
+
+    it('should render general error type correctly with AlertTriangle icon', () => {
+      render(<ErrorState type="general" />);
+
+      // Should show general-specific title
+      expect(
+        screen.getByText('Oops! Something Went Wrong')
+      ).toBeInTheDocument();
+
+      // Should show default general message
+      expect(
+        screen.getByText(DEFAULT_MESSAGES.general)
+      ).toBeInTheDocument();
+
+      // AlertTriangle icon should be present
+      expect(screen.getByTestId('alert-triangle-icon')).toBeInTheDocument();
+    });
+
+    it('should show default message when no custom message provided', () => {
+      render(<ErrorState type="quota" />);
+
+      expect(
+        screen.getByText(DEFAULT_MESSAGES.quota)
+      ).toBeInTheDocument();
+    });
+
+    it('should show custom message when provided', () => {
+      const customMessage = 'A custom error message for testing purposes.';
+
+      render(<ErrorState type="quota" message={customMessage} />);
+
+      expect(screen.getByText(customMessage)).toBeInTheDocument();
+      // Default message should not be present
+      expect(
+        screen.queryByText(DEFAULT_MESSAGES.quota)
+      ).not.toBeInTheDocument();
+    });
+
+    it('should show dismiss button when onDismiss callback provided', () => {
+      const mockDismiss = vi.fn();
+
+      render(<ErrorState type="general" onDismiss={mockDismiss} />);
+
+      const dismissButton = screen.getByLabelText('Dismiss error');
+      expect(dismissButton).toBeInTheDocument();
+      expect(screen.getByTestId('x-icon')).toBeInTheDocument();
+    });
+
+    it('should hide dismiss button when onDismiss not provided', () => {
+      render(<ErrorState type="general" />);
+
+      expect(screen.queryByLabelText('Dismiss error')).not.toBeInTheDocument();
+      expect(screen.queryByTestId('x-icon')).not.toBeInTheDocument();
+    });
+
+    it('should show retry button when onRetry callback provided', () => {
+      const mockRetry = vi.fn();
+
+      render(<ErrorState type="general" onRetry={mockRetry} />);
+
+      const retryButton = screen.getByRole('button', { name: /try again/i });
+      expect(retryButton).toBeInTheDocument();
+      expect(screen.getByTestId('refresh-icon')).toBeInTheDocument();
+    });
+
+    it('should hide retry button when onRetry not provided', () => {
+      render(<ErrorState type="general" />);
+
+      expect(
+        screen.queryByRole('button', { name: /try again/i })
+      ).not.toBeInTheDocument();
+      expect(screen.queryByTestId('refresh-icon')).not.toBeInTheDocument();
+    });
+  });
+
+  // ==========================================================================
+  // Countdown Timer Tests
+  // ==========================================================================
+
+  describe('countdown timer', () => {
+    beforeEach(() => {
+      vi.useFakeTimers({ shouldAdvanceTime: true });
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('should display countdown timer for quota errors with retryAfter', () => {
+      render(<ErrorState type="quota" retryAfter={60} onRetry={vi.fn()} />);
+
+      // Should show the countdown timer text
+      expect(screen.getByText(/try again in/i)).toBeInTheDocument();
+    });
+
+    it('should format countdown correctly for seconds (e.g., "45s")', () => {
+      render(<ErrorState type="quota" retryAfter={45} onRetry={vi.fn()} />);
+
+      expect(screen.getByText(/45s/)).toBeInTheDocument();
+    });
+
+    it('should format countdown correctly for minutes (e.g., "1:30")', () => {
+      render(<ErrorState type="quota" retryAfter={90} onRetry={vi.fn()} />);
+
+      expect(screen.getByText(/1:30/)).toBeInTheDocument();
+    });
+
+    it('should format countdown correctly for exact minutes (e.g., "2:00")', () => {
+      render(<ErrorState type="quota" retryAfter={120} onRetry={vi.fn()} />);
+
+      expect(screen.getByText(/2:00/)).toBeInTheDocument();
+    });
+
+    it('should decrement countdown every second', async () => {
+      render(<ErrorState type="quota" retryAfter={5} onRetry={vi.fn()} />);
+
+      // Initially shows 5s
+      expect(screen.getByText(/5s/)).toBeInTheDocument();
+
+      // Advance by 1 second
+      await act(async () => {
+        vi.advanceTimersByTime(1000);
+      });
+      expect(screen.getByText(/4s/)).toBeInTheDocument();
+
+      // Advance by another second
+      await act(async () => {
+        vi.advanceTimersByTime(1000);
+      });
+      expect(screen.getByText(/3s/)).toBeInTheDocument();
+
+      // Advance by another second
+      await act(async () => {
+        vi.advanceTimersByTime(1000);
+      });
+      expect(screen.getByText(/2s/)).toBeInTheDocument();
+    });
+
+    it('should disable retry button during countdown', () => {
+      const mockRetry = vi.fn();
+
+      render(<ErrorState type="quota" retryAfter={30} onRetry={mockRetry} />);
+
+      const retryButton = screen.getByRole('button', { name: /please wait/i });
+      expect(retryButton).toBeDisabled();
+    });
+
+    it('should enable retry button when countdown reaches zero', async () => {
+      const mockRetry = vi.fn();
+
+      render(<ErrorState type="quota" retryAfter={2} onRetry={mockRetry} />);
+
+      // Initially disabled
+      expect(
+        screen.getByRole('button', { name: /please wait/i })
+      ).toBeDisabled();
+
+      // Advance past countdown
+      await act(async () => {
+        vi.advanceTimersByTime(3000);
+      });
+
+      // Should now be enabled with "Try Again" text
+      const retryButton = screen.getByRole('button', { name: /try again/i });
+      expect(retryButton).not.toBeDisabled();
+    });
+
+    it('should show "Ready to retry" text when countdown reaches zero', async () => {
+      const mockRetry = vi.fn();
+
+      render(<ErrorState type="quota" retryAfter={2} onRetry={mockRetry} />);
+
+      // Advance past countdown
+      await act(async () => {
+        vi.advanceTimersByTime(3000);
+      });
+
+      expect(screen.getByText(/ready to retry/i)).toBeInTheDocument();
+    });
+
+    it('should not show countdown for network errors even with retryAfter', () => {
+      render(<ErrorState type="network" retryAfter={30} onRetry={vi.fn()} />);
+
+      // Network errors should not show countdown timer area
+      expect(screen.queryByText(/try again in/i)).not.toBeInTheDocument();
+    });
+
+    it('should not show countdown for general errors even with retryAfter', () => {
+      render(<ErrorState type="general" retryAfter={30} onRetry={vi.fn()} />);
+
+      // General errors should not show countdown timer area
+      expect(screen.queryByText(/try again in/i)).not.toBeInTheDocument();
+    });
+
+    it('should not disable retry button for network errors', () => {
+      const mockRetry = vi.fn();
+
+      render(<ErrorState type="network" retryAfter={30} onRetry={mockRetry} />);
+
+      // Network errors should have enabled retry button
+      const retryButton = screen.getByRole('button', { name: /try again/i });
+      expect(retryButton).not.toBeDisabled();
+    });
+  });
+
+  // ==========================================================================
+  // Interaction Tests
+  // ==========================================================================
+
+  describe('interactions', () => {
+    it('should call onRetry when retry button is clicked', () => {
+      const mockRetry = vi.fn();
+
+      render(<ErrorState type="general" onRetry={mockRetry} />);
+
+      const retryButton = screen.getByRole('button', { name: /try again/i });
+      fireEvent.click(retryButton);
+
+      expect(mockRetry).toHaveBeenCalledTimes(1);
+    });
+
+    it('should call onDismiss when dismiss button is clicked', () => {
+      const mockDismiss = vi.fn();
+
+      render(<ErrorState type="general" onDismiss={mockDismiss} />);
+
+      const dismissButton = screen.getByLabelText('Dismiss error');
+      fireEvent.click(dismissButton);
+
+      expect(mockDismiss).toHaveBeenCalledTimes(1);
+    });
+
+    it('should not call onRetry when retry is disabled during countdown', async () => {
+      vi.useFakeTimers({ shouldAdvanceTime: true });
+      const mockRetry = vi.fn();
+
+      render(<ErrorState type="quota" retryAfter={60} onRetry={mockRetry} />);
+
+      const retryButton = screen.getByRole('button', { name: /please wait/i });
+
+      // Try to click the disabled button
+      fireEvent.click(retryButton);
+
+      expect(mockRetry).not.toHaveBeenCalled();
+
+      vi.useRealTimers();
+    });
+
+    it('should call onRetry after countdown completes', async () => {
+      vi.useFakeTimers({ shouldAdvanceTime: true });
+      const mockRetry = vi.fn();
+
+      render(<ErrorState type="quota" retryAfter={2} onRetry={mockRetry} />);
+
+      // Wait for countdown to complete
+      await act(async () => {
+        vi.advanceTimersByTime(3000);
+      });
+
+      // Now click should work
+      const retryButton = screen.getByRole('button', { name: /try again/i });
+      fireEvent.click(retryButton);
+
+      expect(mockRetry).toHaveBeenCalledTimes(1);
+
+      vi.useRealTimers();
+    });
+  });
+
+  // ==========================================================================
+  // Accessibility Tests
+  // ==========================================================================
+
+  describe('accessibility', () => {
+    it('should have role="alert" attribute', () => {
+      render(<ErrorState type="general" />);
+
+      const alert = screen.getByRole('alert');
+      expect(alert).toBeInTheDocument();
+    });
+
+    it('should have aria-live="assertive" attribute', () => {
+      render(<ErrorState type="general" />);
+
+      const alert = screen.getByRole('alert');
+      expect(alert).toHaveAttribute('aria-live', 'assertive');
+    });
+
+    it('should have icons with aria-hidden="true"', () => {
+      render(
+        <ErrorState
+          type="general"
+          onRetry={vi.fn()}
+          onDismiss={vi.fn()}
+        />
+      );
+
+      // Main icon (AlertTriangle for general)
+      const alertIcon = screen.getByTestId('alert-triangle-icon');
+      expect(alertIcon).toHaveAttribute('aria-hidden', 'true');
+
+      // Refresh icon in retry button
+      const refreshIcon = screen.getByTestId('refresh-icon');
+      expect(refreshIcon).toHaveAttribute('aria-hidden', 'true');
+
+      // X icon in dismiss button
+      const xIcon = screen.getByTestId('x-icon');
+      expect(xIcon).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('should have countdown with aria-live="polite" for updates', () => {
+      render(<ErrorState type="quota" retryAfter={30} onRetry={vi.fn()} />);
+
+      // Find the countdown container - it should have aria-live="polite"
+      const countdownContainer = screen.getByText(/try again in/i).closest('div');
+      expect(countdownContainer).toHaveAttribute('aria-live', 'polite');
+    });
+
+    it('should have dismiss button with aria-label', () => {
+      render(<ErrorState type="general" onDismiss={vi.fn()} />);
+
+      const dismissButton = screen.getByLabelText('Dismiss error');
+      expect(dismissButton).toBeInTheDocument();
+      expect(dismissButton).toHaveAttribute('aria-label', 'Dismiss error');
+    });
+
+    it('should be keyboard navigable', () => {
+      const mockRetry = vi.fn();
+      const mockDismiss = vi.fn();
+
+      render(
+        <ErrorState
+          type="general"
+          onRetry={mockRetry}
+          onDismiss={mockDismiss}
+        />
+      );
+
+      // Dismiss button should be focusable
+      const dismissButton = screen.getByLabelText('Dismiss error');
+      dismissButton.focus();
+      expect(dismissButton).toHaveFocus();
+
+      // Retry button should be focusable
+      const retryButton = screen.getByRole('button', { name: /try again/i });
+      retryButton.focus();
+      expect(retryButton).toHaveFocus();
+
+      // Press Enter to activate retry (using keyboard event)
+      fireEvent.keyDown(retryButton, { key: 'Enter', code: 'Enter' });
+      fireEvent.keyUp(retryButton, { key: 'Enter', code: 'Enter' });
+      // Note: button click events are triggered by Enter key natively in tests,
+      // but we verify focus works correctly
+    });
+
+    it('should have visible focus styles on buttons', () => {
+      render(
+        <ErrorState
+          type="general"
+          onRetry={vi.fn()}
+          onDismiss={vi.fn()}
+        />
+      );
+
+      const retryButton = screen.getByRole('button', { name: /try again/i });
+      const dismissButton = screen.getByLabelText('Dismiss error');
+
+      // Check for focus-visible ring classes
+      expect(retryButton.className).toMatch(/focus-visible:ring/);
+      expect(dismissButton.className).toMatch(/focus-visible:ring/);
+    });
+  });
+
+  // ==========================================================================
+  // Snapshot/Visual Tests
+  // ==========================================================================
+
+  describe('snapshots', () => {
+    it('should render quota type correctly (snapshot)', () => {
+      const { container } = render(
+        <ErrorState
+          type="quota"
+          retryAfter={45}
+          onRetry={vi.fn()}
+          onDismiss={vi.fn()}
+        />
+      );
+
+      expect(container.firstChild).toMatchSnapshot();
+    });
+
+    it('should render network type correctly (snapshot)', () => {
+      const { container } = render(
+        <ErrorState
+          type="network"
+          onRetry={vi.fn()}
+          onDismiss={vi.fn()}
+        />
+      );
+
+      expect(container.firstChild).toMatchSnapshot();
+    });
+
+    it('should render general type correctly (snapshot)', () => {
+      const { container } = render(
+        <ErrorState
+          type="general"
+          message="A custom error message for the snapshot test."
+          onRetry={vi.fn()}
+          onDismiss={vi.fn()}
+        />
+      );
+
+      expect(container.firstChild).toMatchSnapshot();
+    });
+  });
+
+  // ==========================================================================
+  // Edge Cases Tests
+  // ==========================================================================
+
+  describe('edge cases', () => {
+    it('should handle retryAfter of 0 correctly', () => {
+      const mockRetry = vi.fn();
+
+      render(<ErrorState type="quota" retryAfter={0} onRetry={mockRetry} />);
+
+      // Retry button should be enabled immediately
+      const retryButton = screen.getByRole('button', { name: /try again/i });
+      expect(retryButton).not.toBeDisabled();
+    });
+
+    it('should handle undefined retryAfter correctly', () => {
+      const mockRetry = vi.fn();
+
+      render(<ErrorState type="quota" onRetry={mockRetry} />);
+
+      // Should not show countdown area when retryAfter is undefined
+      expect(screen.queryByText(/try again in/i)).not.toBeInTheDocument();
+    });
+
+    it('should apply custom className', () => {
+      render(<ErrorState type="general" className="custom-test-class mt-8" />);
+
+      const alert = screen.getByRole('alert');
+      expect(alert).toHaveClass('custom-test-class', 'mt-8');
+    });
+
+    it('should render both retry and dismiss buttons together', () => {
+      render(
+        <ErrorState
+          type="general"
+          onRetry={vi.fn()}
+          onDismiss={vi.fn()}
+        />
+      );
+
+      expect(
+        screen.getByRole('button', { name: /try again/i })
+      ).toBeInTheDocument();
+      expect(screen.getByLabelText('Dismiss error')).toBeInTheDocument();
+    });
+
+    it('should handle very large retryAfter values', () => {
+      render(<ErrorState type="quota" retryAfter={3600} onRetry={vi.fn()} />);
+
+      // Should format large values correctly (60:00 for 1 hour)
+      expect(screen.getByText(/60:00/)).toBeInTheDocument();
+    });
+
+    it('should handle countdown reset when retryAfter prop changes', async () => {
+      vi.useFakeTimers({ shouldAdvanceTime: true });
+
+      const { rerender } = render(
+        <ErrorState type="quota" retryAfter={10} onRetry={vi.fn()} />
+      );
+
+      expect(screen.getByText(/10s/)).toBeInTheDocument();
+
+      // Advance some time
+      await act(async () => {
+        vi.advanceTimersByTime(3000);
+      });
+      expect(screen.getByText(/7s/)).toBeInTheDocument();
+
+      // Change retryAfter prop
+      rerender(<ErrorState type="quota" retryAfter={20} onRetry={vi.fn()} />);
+
+      // Should reset to new value
+      expect(screen.getByText(/20s/)).toBeInTheDocument();
+
+      vi.useRealTimers();
+    });
+
+    it('should forward additional HTML attributes', () => {
+      render(
+        <ErrorState
+          type="general"
+          data-testid="custom-error"
+          title="Error notification"
+        />
+      );
+
+      const alert = screen.getByTestId('custom-error');
+      expect(alert).toHaveAttribute('title', 'Error notification');
+    });
+
+    it('should render with minimal props (just type)', () => {
+      render(<ErrorState type="general" />);
+
+      expect(screen.getByRole('alert')).toBeInTheDocument();
+      expect(
+        screen.getByText('Oops! Something Went Wrong')
+      ).toBeInTheDocument();
+    });
+  });
+
+  // ==========================================================================
+  // Integration Tests
+  // ==========================================================================
+
+  describe('integration', () => {
+    it('should render complete quota error with all features', () => {
+      const customMessage =
+        'Rate limit exceeded. Please wait before sending more requests.';
+
+      render(
+        <ErrorState
+          type="quota"
+          message={customMessage}
+          retryAfter={45}
+          onRetry={vi.fn()}
+          onDismiss={vi.fn()}
+        />
+      );
+
+      // Title
+      expect(
+        screen.getByText('Service Temporarily Unavailable')
+      ).toBeInTheDocument();
+
+      // Custom message
+      expect(screen.getByText(customMessage)).toBeInTheDocument();
+
+      // Countdown
+      expect(screen.getByText(/45s/)).toBeInTheDocument();
+
+      // Buttons
+      expect(
+        screen.getByRole('button', { name: /please wait/i })
+      ).toBeInTheDocument();
+      expect(screen.getByLabelText('Dismiss error')).toBeInTheDocument();
+
+      // Icons
+      const clockIcons = screen.getAllByTestId('clock-icon');
+      expect(clockIcons.length).toBeGreaterThan(0);
+    });
+
+    it('should render complete network error with all features', () => {
+      render(
+        <ErrorState
+          type="network"
+          onRetry={vi.fn()}
+          onDismiss={vi.fn()}
+        />
+      );
+
+      // Title
+      expect(screen.getByText('Connection Lost')).toBeInTheDocument();
+
+      // Default message
+      expect(
+        screen.getByText(DEFAULT_MESSAGES.network)
+      ).toBeInTheDocument();
+
+      // Buttons (not disabled for network type)
+      expect(
+        screen.getByRole('button', { name: /try again/i })
+      ).not.toBeDisabled();
+
+      // Icon
+      expect(screen.getByTestId('wifi-off-icon')).toBeInTheDocument();
+    });
+
+    it('should work correctly through a complete user flow', async () => {
+      vi.useFakeTimers({ shouldAdvanceTime: true });
+      const mockRetry = vi.fn();
+      const mockDismiss = vi.fn();
+
+      render(
+        <ErrorState
+          type="quota"
+          retryAfter={3}
+          onRetry={mockRetry}
+          onDismiss={mockDismiss}
+        />
+      );
+
+      // Initially button is disabled
+      expect(
+        screen.getByRole('button', { name: /please wait/i })
+      ).toBeDisabled();
+
+      // Wait for countdown
+      await act(async () => {
+        vi.advanceTimersByTime(1000);
+      });
+      expect(screen.getByText(/2s/)).toBeInTheDocument();
+
+      await act(async () => {
+        vi.advanceTimersByTime(1000);
+      });
+      expect(screen.getByText(/1s/)).toBeInTheDocument();
+
+      await act(async () => {
+        vi.advanceTimersByTime(1000);
+      });
+
+      // Now button should be enabled
+      const retryButton = screen.getByRole('button', { name: /try again/i });
+      expect(retryButton).not.toBeDisabled();
+
+      // Click retry
+      fireEvent.click(retryButton);
+      expect(mockRetry).toHaveBeenCalledTimes(1);
+
+      // Click dismiss
+      fireEvent.click(screen.getByLabelText('Dismiss error'));
+      expect(mockDismiss).toHaveBeenCalledTimes(1);
+
+      vi.useRealTimers();
+    });
+  });
+});

frontend/src/components/chat/__tests__/provider-toggle.test.tsx

@@ -0,0 +1,1376 @@
+/**
+ * Unit Tests for ProviderToggle Component
+ *
+ * Comprehensive test coverage for the provider selection component.
+ * Tests rendering states, provider pills, selection behavior,
+ * cooldown timers, accessibility, and compact mode.
+ *
+ * @module components/chat/__tests__/provider-toggle.test
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from 'vitest';
+import { render, screen, fireEvent, waitFor, within, act } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ProviderToggle } from '../provider-toggle';
+import { useProviders, type ProviderStatus } from '@/hooks';
+
+// ============================================================================
+// Mocks
+// ============================================================================
+
+vi.mock('@/hooks', () => ({
+  useProviders: vi.fn(),
+}));
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+/**
+ * Create a mock provider status object.
+ *
+ * @param overrides - Properties to override in the default provider
+ * @returns Mock provider status
+ */
+function createMockProvider(
+  overrides: Partial<ProviderStatus> = {}
+): ProviderStatus {
+  return {
+    id: 'gemini',
+    name: 'Gemini',
+    description: 'Gemini Flash / Gemma',
+    isAvailable: true,
+    cooldownSeconds: null,
+    totalRequestsRemaining: 10,
+    primaryModel: 'gemini-2.5-flash-lite',
+    allModels: ['gemini-2.5-flash-lite', 'gemini-2.5-flash', 'gemini-3-flash', 'gemma-3-27b-it'],
+    ...overrides,
+  };
+}
+
+/**
+ * Create default mock return value for useProviders hook.
+ *
+ * @param overrides - Properties to override in the default return value
+ * @returns Mock useProviders return value
+ */
+function createMockUseProvidersReturn(
+  overrides: Partial<ReturnType<typeof useProviders>> = {}
+): ReturnType<typeof useProviders> {
+  return {
+    providers: [],
+    selectedProvider: null,
+    selectProvider: vi.fn(),
+    isLoading: false,
+    error: null,
+    refresh: vi.fn(),
+    lastUpdated: new Date(),
+    ...overrides,
+  };
+}
+
+/**
+ * Set up the useProviders mock with the given return value.
+ *
+ * @param mockReturn - Mock return value for useProviders
+ */
+function setupMock(mockReturn: ReturnType<typeof useProviders>): void {
+  (useProviders as Mock).mockReturnValue(mockReturn);
+}
+
+// ============================================================================
+// Test Suite
+// ============================================================================
+
+describe('ProviderToggle', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  // ==========================================================================
+  // Rendering States Tests
+  // ==========================================================================
+
+  describe('rendering states', () => {
+    it('should render loading skeleton when isLoading is true', () => {
+      setupMock(
+        createMockUseProvidersReturn({
+          isLoading: true,
+          providers: [],
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      // Should have skeleton elements with aria-label for loading
+      const loadingGroup = screen.getByRole('group', {
+        name: /loading provider options/i,
+      });
+      expect(loadingGroup).toBeInTheDocument();
+
+      // Should have 3 skeleton pills (Auto + 2 providers)
+      const skeletons = loadingGroup.querySelectorAll('.animate-pulse');
+      expect(skeletons).toHaveLength(3);
+    });
+
+    it('should render error state with refresh button when error and no providers', () => {
+      const mockRefresh = vi.fn();
+      setupMock(
+        createMockUseProvidersReturn({
+          isLoading: false,
+          error: 'Failed to load providers',
+          providers: [],
+          refresh: mockRefresh,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      // Should show error alert
+      const alert = screen.getByRole('alert');
+      expect(alert).toBeInTheDocument();
+      expect(alert).toHaveTextContent('Failed to load providers');
+
+      // Should have retry button
+      const retryButton = screen.getByRole('button', {
+        name: /retry loading providers/i,
+      });
+      expect(retryButton).toBeInTheDocument();
+    });
+
+    it('should render provider pills when providers are available', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      // Should have radiogroup role
+      const radiogroup = screen.getByRole('radiogroup', {
+        name: /select llm provider/i,
+      });
+      expect(radiogroup).toBeInTheDocument();
+
+      // Should have provider pills (Auto + 2 providers)
+      const radios = screen.getAllByRole('radio');
+      expect(radios).toHaveLength(3);
+    });
+
+    it('should always render "Auto" option first', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const radios = screen.getAllByRole('radio');
+
+      // First radio should be Auto
+      expect(radios[0]).toHaveAccessibleName(/auto/i);
+    });
+
+    it('should show providers even when there is an error if providers exist', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          error: 'Refresh failed',
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      // Should show providers, not error
+      const radiogroup = screen.getByRole('radiogroup');
+      expect(radiogroup).toBeInTheDocument();
+
+      // Should not show error alert when providers exist
+      expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+    });
+  });
+
+  // ==========================================================================
+  // Provider Pills Tests
+  // ==========================================================================
+
+  describe('provider pills', () => {
+    it('should display provider name', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      expect(screen.getByText('Auto')).toBeInTheDocument();
+      expect(screen.getByText('Gemini')).toBeInTheDocument();
+      expect(screen.getByText('Groq')).toBeInTheDocument();
+    });
+
+    it('should show green status indicator for available providers', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'gemini',
+          name: 'Gemini',
+          isAvailable: true,
+          cooldownSeconds: null,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      const { container } = render(<ProviderToggle />);
+
+      // Find the Gemini button and check for green indicator
+      const geminiButton = screen.getByRole('radio', { name: /gemini/i });
+      const indicator = geminiButton.querySelector('.bg-\\[var\\(--success\\)\\]');
+      expect(indicator).toBeInTheDocument();
+    });
+
+    it('should show red status indicator for providers in cooldown', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 45,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      const { container } = render(<ProviderToggle />);
+
+      // Find the Groq button and check for red indicator
+      const groqButton = screen.getByRole('radio', { name: /groq/i });
+      const indicator = groqButton.querySelector('.bg-\\[var\\(--error\\)\\]');
+      expect(indicator).toBeInTheDocument();
+    });
+
+    it('should show gray status indicator for unavailable providers without cooldown', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'deepseek',
+          name: 'DeepSeek',
+          isAvailable: false,
+          cooldownSeconds: null,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      const { container } = render(<ProviderToggle />);
+
+      // Find the DeepSeek button and check for gray indicator
+      const deepseekButton = screen.getByRole('radio', { name: /deepseek/i });
+      const indicator = deepseekButton.querySelector(
+        '.bg-\\[var\\(--foreground-muted\\)\\]'
+      );
+      expect(indicator).toBeInTheDocument();
+    });
+
+    it('should mark selected provider with aria-checked true', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: 'gemini',
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const geminiButton = screen.getByRole('radio', { name: /gemini.*selected/i });
+      expect(geminiButton).toHaveAttribute('aria-checked', 'true');
+
+      const groqButton = screen.getByRole('radio', { name: /groq/i });
+      expect(groqButton).toHaveAttribute('aria-checked', 'false');
+
+      const autoButton = screen.getByRole('radio', { name: /auto/i });
+      expect(autoButton).toHaveAttribute('aria-checked', 'false');
+    });
+
+    it('should mark Auto as selected when selectedProvider is null', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: null,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const autoButton = screen.getByRole('radio', { name: /auto.*selected/i });
+      expect(autoButton).toHaveAttribute('aria-checked', 'true');
+    });
+  });
+
+  // ==========================================================================
+  // Provider Selection Tests
+  // ==========================================================================
+
+  describe('provider selection', () => {
+    it('should call selectProvider when a pill is clicked', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const geminiButton = screen.getByRole('radio', { name: /gemini/i });
+      await user.click(geminiButton);
+
+      expect(mockSelectProvider).toHaveBeenCalledTimes(1);
+      expect(mockSelectProvider).toHaveBeenCalledWith('gemini');
+    });
+
+    it('should update aria-checked attribute for selected provider', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: 'groq',
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const groqButton = screen.getByRole('radio', { name: /groq.*selected/i });
+      expect(groqButton).toHaveAttribute('aria-checked', 'true');
+
+      const geminiButton = screen.getByRole('radio', { name: /gemini/i });
+      expect(geminiButton).toHaveAttribute('aria-checked', 'false');
+    });
+
+    it('should allow selecting Auto (null) option', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: 'gemini',
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const autoButton = screen.getByRole('radio', { name: /auto/i });
+      await user.click(autoButton);
+
+      expect(mockSelectProvider).toHaveBeenCalledWith(null);
+    });
+
+    it('should allow selecting unavailable providers (user choice)', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 60,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const groqButton = screen.getByRole('radio', { name: /groq/i });
+      await user.click(groqButton);
+
+      // Should still allow selection even if unavailable
+      expect(mockSelectProvider).toHaveBeenCalledWith('groq');
+    });
+  });
+
+  // ==========================================================================
+  // Cooldown Timer Tests
+  // ==========================================================================
+
+  describe('cooldown timer', () => {
+    beforeEach(() => {
+      vi.useFakeTimers({ shouldAdvanceTime: true });
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('should display cooldown time for providers with cooldownSeconds', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 45,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      // Should display the countdown
+      expect(screen.getByText('45s')).toBeInTheDocument();
+    });
+
+    it('should format time as "Xm Ys" for times with minutes and seconds', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 130, // 2m 10s
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      expect(screen.getByText('2m 10s')).toBeInTheDocument();
+    });
+
+    it('should format time as "Xm" for exact minutes', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 120, // 2m 0s
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      expect(screen.getByText('2m')).toBeInTheDocument();
+    });
+
+    it('should format time as "Xs" for times under a minute', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 30,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      expect(screen.getByText('30s')).toBeInTheDocument();
+    });
+
+    it('should decrement countdown every second', async () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 5,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      expect(screen.getByText('5s')).toBeInTheDocument();
+
+      // Advance by 1 second using act to wrap the state update
+      await act(async () => {
+        vi.advanceTimersByTime(1000);
+      });
+      expect(screen.getByText('4s')).toBeInTheDocument();
+
+      // Advance by another second
+      await act(async () => {
+        vi.advanceTimersByTime(1000);
+      });
+      expect(screen.getByText('3s')).toBeInTheDocument();
+    });
+
+    it('should stop countdown and hide when reaching 0', async () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 2,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      expect(screen.getByText('2s')).toBeInTheDocument();
+
+      // Advance to 1s
+      await act(async () => {
+        vi.advanceTimersByTime(1000);
+      });
+      expect(screen.getByText('1s')).toBeInTheDocument();
+
+      // Advance past 0
+      await act(async () => {
+        vi.advanceTimersByTime(1000);
+      });
+
+      // Timer should be hidden
+      expect(screen.queryByText('0s')).not.toBeInTheDocument();
+      expect(screen.queryByText('1s')).not.toBeInTheDocument();
+    });
+
+    it('should not display timer when cooldownSeconds is null', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'gemini',
+          name: 'Gemini',
+          isAvailable: true,
+          cooldownSeconds: null,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      const { container } = render(<ProviderToggle />);
+
+      // Should not have any time elements in Gemini button
+      const geminiButton = screen.getByRole('radio', { name: /gemini/i });
+      expect(geminiButton.textContent).not.toMatch(/\d+s/);
+      expect(geminiButton.textContent).not.toMatch(/\d+m/);
+    });
+
+    it('should not display timer when cooldownSeconds is 0', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 0,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      const { container } = render(<ProviderToggle />);
+
+      // Should not display any countdown
+      const groqButton = screen.getByRole('radio', { name: /groq/i });
+      expect(groqButton.textContent).not.toMatch(/\d+s/);
+    });
+  });
+
+  // ==========================================================================
+  // Accessibility Tests
+  // ==========================================================================
+
+  describe('accessibility', () => {
+    it('should have radiogroup role on container', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const radiogroup = screen.getByRole('radiogroup', {
+        name: /select llm provider/i,
+      });
+      expect(radiogroup).toBeInTheDocument();
+    });
+
+    it('should have radio role on each pill', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const radios = screen.getAllByRole('radio');
+      expect(radios).toHaveLength(3); // Auto + 2 providers
+    });
+
+    it('should support keyboard navigation with arrow keys', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: null,
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      // Focus the first (Auto) button
+      const autoButton = screen.getByRole('radio', { name: /auto.*selected/i });
+      autoButton.focus();
+
+      // Press ArrowRight to move to next option
+      await user.keyboard('{ArrowRight}');
+
+      expect(mockSelectProvider).toHaveBeenCalledWith('gemini');
+    });
+
+    it('should support ArrowDown as alternative to ArrowRight', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: null,
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const autoButton = screen.getByRole('radio', { name: /auto.*selected/i });
+      autoButton.focus();
+
+      await user.keyboard('{ArrowDown}');
+
+      expect(mockSelectProvider).toHaveBeenCalledWith('gemini');
+    });
+
+    it('should support ArrowLeft/ArrowUp to move backwards', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: 'gemini',
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const geminiButton = screen.getByRole('radio', { name: /gemini.*selected/i });
+      geminiButton.focus();
+
+      // Press ArrowLeft to go back to Auto
+      await user.keyboard('{ArrowLeft}');
+
+      expect(mockSelectProvider).toHaveBeenCalledWith(null);
+    });
+
+    it('should support Home key to go to first option', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: 'groq',
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const groqButton = screen.getByRole('radio', { name: /groq.*selected/i });
+      groqButton.focus();
+
+      await user.keyboard('{Home}');
+
+      // Should select Auto (first option, id = null)
+      expect(mockSelectProvider).toHaveBeenCalledWith(null);
+    });
+
+    it('should support End key to go to last option', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: null,
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const autoButton = screen.getByRole('radio', { name: /auto.*selected/i });
+      autoButton.focus();
+
+      await user.keyboard('{End}');
+
+      // Should select last option (groq)
+      expect(mockSelectProvider).toHaveBeenCalledWith('groq');
+    });
+
+    it('should use roving tabindex pattern', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: 'gemini',
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const autoButton = screen.getByRole('radio', { name: /auto/i });
+      const geminiButton = screen.getByRole('radio', { name: /gemini.*selected/i });
+      const groqButton = screen.getByRole('radio', { name: /groq/i });
+
+      // Only the selected option should have tabindex=0
+      expect(geminiButton).toHaveAttribute('tabindex', '0');
+      expect(autoButton).toHaveAttribute('tabindex', '-1');
+      expect(groqButton).toHaveAttribute('tabindex', '-1');
+    });
+
+    it('should wrap around when navigating past the end', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: 'gemini',
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const geminiButton = screen.getByRole('radio', { name: /gemini.*selected/i });
+      geminiButton.focus();
+
+      // Press ArrowRight to wrap to Auto (first option)
+      await user.keyboard('{ArrowRight}');
+
+      expect(mockSelectProvider).toHaveBeenCalledWith(null);
+    });
+
+    it('should wrap around when navigating before the start', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: null,
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const autoButton = screen.getByRole('radio', { name: /auto.*selected/i });
+      autoButton.focus();
+
+      // Press ArrowLeft to wrap to last option (gemini)
+      await user.keyboard('{ArrowLeft}');
+
+      expect(mockSelectProvider).toHaveBeenCalledWith('gemini');
+    });
+
+    it('should have proper aria-label for unavailable providers', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: null,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const groqButton = screen.getByRole('radio', { name: /groq.*unavailable/i });
+      expect(groqButton).toBeInTheDocument();
+    });
+
+    it('should have proper aria-label for providers in cooldown', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 45,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const groqButton = screen.getByRole('radio', {
+        name: /groq.*cooling down/i,
+      });
+      expect(groqButton).toBeInTheDocument();
+    });
+  });
+
+  // ==========================================================================
+  // Refresh Button Tests
+  // ==========================================================================
+
+  describe('refresh button', () => {
+    it('should call refresh when refresh button is clicked', async () => {
+      const user = userEvent.setup();
+      const mockRefresh = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          refresh: mockRefresh,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const refreshButton = screen.getByRole('button', {
+        name: /refresh provider status/i,
+      });
+      await user.click(refreshButton);
+
+      expect(mockRefresh).toHaveBeenCalledTimes(1);
+    });
+
+    it('should be accessible with proper aria-label', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const refreshButton = screen.getByRole('button', {
+        name: /refresh provider status/i,
+      });
+      expect(refreshButton).toHaveAttribute('title', 'Refresh provider status');
+    });
+
+    it('should call refresh in error state', async () => {
+      const user = userEvent.setup();
+      const mockRefresh = vi.fn();
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: [],
+          error: 'Failed to load',
+          refresh: mockRefresh,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const retryButton = screen.getByRole('button', {
+        name: /retry loading providers/i,
+      });
+      await user.click(retryButton);
+
+      expect(mockRefresh).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ==========================================================================
+  // Compact Mode Tests
+  // ==========================================================================
+
+  describe('compact mode', () => {
+    it('should render with smaller sizes when compact prop is true', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      const { container } = render(<ProviderToggle compact />);
+
+      // Check that compact classes are applied
+      const radiogroup = screen.getByRole('radiogroup');
+
+      // Container should have smaller gap
+      expect(radiogroup).toHaveClass('gap-1.5');
+    });
+
+    it('should render smaller refresh button in compact mode', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle compact />);
+
+      const refreshButton = screen.getByRole('button', {
+        name: /refresh provider status/i,
+      });
+
+      // Compact refresh button should have smaller dimensions
+      expect(refreshButton).toHaveClass('h-6', 'w-6');
+    });
+
+    it('should render normal size without compact prop', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const refreshButton = screen.getByRole('button', {
+        name: /refresh provider status/i,
+      });
+
+      // Normal refresh button should have larger dimensions
+      expect(refreshButton).toHaveClass('h-7', 'w-7');
+    });
+
+    it('should render smaller skeleton in compact mode when loading', () => {
+      setupMock(
+        createMockUseProvidersReturn({
+          isLoading: true,
+          providers: [],
+        })
+      );
+
+      const { container } = render(<ProviderToggle compact />);
+
+      const skeletons = container.querySelectorAll('.animate-pulse');
+
+      // Check that skeletons have compact height
+      skeletons.forEach((skeleton) => {
+        expect(skeleton).toHaveClass('h-7');
+      });
+    });
+
+    it('should render smaller error state in compact mode', () => {
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: [],
+          error: 'Error message',
+        })
+      );
+
+      render(<ProviderToggle compact />);
+
+      const alert = screen.getByRole('alert');
+      expect(alert).toHaveClass('text-xs');
+    });
+
+    it('should apply custom className', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle className="custom-class mt-4" />);
+
+      const radiogroup = screen.getByRole('radiogroup');
+      expect(radiogroup).toHaveClass('custom-class', 'mt-4');
+    });
+  });
+
+  // ==========================================================================
+  // Edge Cases Tests
+  // ==========================================================================
+
+  describe('edge cases', () => {
+    it('should handle empty providers array', () => {
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: [],
+          isLoading: false,
+          error: null,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      // Should still render radiogroup with just Auto option
+      const radiogroup = screen.getByRole('radiogroup');
+      expect(radiogroup).toBeInTheDocument();
+
+      const radios = screen.getAllByRole('radio');
+      expect(radios).toHaveLength(1); // Just Auto
+    });
+
+    it('should handle provider with very long name', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'long-name-provider',
+          name: 'Very Long Provider Name That Might Overflow',
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      expect(
+        screen.getByText('Very Long Provider Name That Might Overflow')
+      ).toBeInTheDocument();
+    });
+
+    it('should handle multiple providers with mixed availability', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'gemini',
+          name: 'Gemini',
+          isAvailable: true,
+        }),
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          isAvailable: false,
+          cooldownSeconds: 30,
+        }),
+        createMockProvider({
+          id: 'deepseek',
+          name: 'DeepSeek',
+          isAvailable: false,
+          cooldownSeconds: null,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const radios = screen.getAllByRole('radio');
+      expect(radios).toHaveLength(4); // Auto + 3 providers
+
+      // Each should render correctly
+      expect(screen.getByText('Gemini')).toBeInTheDocument();
+      expect(screen.getByText('Groq')).toBeInTheDocument();
+      expect(screen.getByText('DeepSeek')).toBeInTheDocument();
+      expect(screen.getByText('30s')).toBeInTheDocument(); // Groq cooldown
+    });
+
+    it('should handle very long error message with truncation', () => {
+      const longError =
+        'This is a very long error message that should be truncated to prevent layout issues in the UI when displaying error states';
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: [],
+          error: longError,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const errorSpan = screen.getByText(longError);
+      expect(errorSpan).toHaveClass('truncate');
+      expect(errorSpan).toHaveAttribute('title', longError);
+    });
+
+    it('should maintain focus after keyboard navigation', async () => {
+      const user = userEvent.setup();
+      const mockSelectProvider = vi.fn();
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+        createMockProvider({ id: 'groq', name: 'Groq' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: null,
+          selectProvider: mockSelectProvider,
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      const autoButton = screen.getByRole('radio', { name: /auto.*selected/i });
+      autoButton.focus();
+
+      // Navigate to Gemini
+      await user.keyboard('{ArrowRight}');
+
+      // selectProvider should have been called
+      expect(mockSelectProvider).toHaveBeenCalledWith('gemini');
+    });
+  });
+
+  // ==========================================================================
+  // Integration Tests
+  // ==========================================================================
+
+  describe('integration', () => {
+    it('should work correctly with a complete provider list', () => {
+      const mockProviders = [
+        createMockProvider({
+          id: 'gemini',
+          name: 'Gemini',
+          description: 'Google Gemini Pro',
+          isAvailable: true,
+          cooldownSeconds: null,
+          totalRequestsRemaining: 10,
+        }),
+        createMockProvider({
+          id: 'groq',
+          name: 'Groq',
+          description: 'Groq LLM',
+          isAvailable: false,
+          cooldownSeconds: 45,
+          totalRequestsRemaining: 0,
+        }),
+        createMockProvider({
+          id: 'deepseek',
+          name: 'DeepSeek',
+          description: 'DeepSeek Chat',
+          isAvailable: true,
+          cooldownSeconds: null,
+          totalRequestsRemaining: 5,
+        }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+          selectedProvider: 'gemini',
+        })
+      );
+
+      render(<ProviderToggle />);
+
+      // All providers should be rendered
+      expect(screen.getByText('Auto')).toBeInTheDocument();
+      expect(screen.getByText('Gemini')).toBeInTheDocument();
+      expect(screen.getByText('Groq')).toBeInTheDocument();
+      expect(screen.getByText('DeepSeek')).toBeInTheDocument();
+
+      // Cooldown should be shown
+      expect(screen.getByText('45s')).toBeInTheDocument();
+
+      // Selection should be correct
+      const geminiButton = screen.getByRole('radio', { name: /gemini.*selected/i });
+      expect(geminiButton).toHaveAttribute('aria-checked', 'true');
+    });
+
+    it('should render all elements with correct structure', () => {
+      const mockProviders = [
+        createMockProvider({ id: 'gemini', name: 'Gemini' }),
+      ];
+
+      setupMock(
+        createMockUseProvidersReturn({
+          providers: mockProviders,
+        })
+      );
+
+      const { container } = render(<ProviderToggle />);
+
+      // Check structure
+      const radiogroup = screen.getByRole('radiogroup');
+      expect(radiogroup).toBeInTheDocument();
+
+      // Radio buttons should be inside the radiogroup
+      const radios = within(radiogroup).getAllByRole('radio');
+      expect(radios).toHaveLength(2);
+
+      // Refresh button should be present
+      const refreshButton = screen.getByRole('button', {
+        name: /refresh provider status/i,
+      });
+      expect(refreshButton).toBeInTheDocument();
+    });
+  });
+});

frontend/src/components/chat/__tests__/source-card.test.tsx

@@ -0,0 +1,805 @@
+/**
+ * Unit Tests for SourceCard Component
+ *
+ * Comprehensive test coverage for the source citation card component.
+ * Tests rendering, expand/collapse functionality, accessibility features,
+ * and edge cases for text truncation and special characters.
+ *
+ * @module components/chat/__tests__/source-card.test
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { SourceCard } from '../source-card';
+import type { Source } from '@/types';
+
+// ============================================================================
+// Mocks
+// ============================================================================
+
+/**
+ * Mock lucide-react icons for faster tests and to avoid lazy loading issues.
+ * Each icon is replaced with a simple span containing a test ID.
+ */
+vi.mock('lucide-react', () => ({
+  FileText: ({ className }: { className?: string }) => (
+    <span data-testid="file-icon" className={className} />
+  ),
+  ChevronDown: ({ className }: { className?: string }) => (
+    <span data-testid="chevron-down-icon" className={className} />
+  ),
+  ChevronUp: ({ className }: { className?: string }) => (
+    <span data-testid="chevron-up-icon" className={className} />
+  ),
+}));
+
+// ============================================================================
+// Test Fixtures
+// ============================================================================
+
+/**
+ * Create a mock source object for testing.
+ *
+ * @param overrides - Properties to override in the default source
+ * @returns Mock source object with sensible defaults
+ */
+function createMockSource(overrides: Partial<Source> = {}): Source {
+  return {
+    id: 'test-source-1',
+    headingPath: 'Chapter 1 > Section 2 > Subsection A',
+    page: 42,
+    text: 'This is the source text content from the pythermalcomfort documentation.',
+    score: 0.85,
+    ...overrides,
+  };
+}
+
+/**
+ * Long text fixture for testing truncation behavior.
+ * Contains more than 150 characters to trigger truncation.
+ */
+const LONG_TEXT =
+  'This is a very long text that exceeds the default truncation length of 150 characters. ' +
+  'It contains multiple sentences to test the word-boundary truncation behavior. ' +
+  'The truncation should happen at a word boundary to avoid cutting words in the middle. ' +
+  'This ensures a clean user experience when displaying source excerpts.';
+
+/**
+ * Short text fixture for testing non-truncation behavior.
+ * Contains fewer than 150 characters.
+ */
+const SHORT_TEXT = 'This is short text that fits within the truncation limit.';
+
+/**
+ * Text with special characters for edge case testing.
+ */
+const SPECIAL_CHARS_TEXT =
+  'Temperature formula: T = (a + b) / 2 where a > 0 & b < 100. Use <code>calc()</code> for computation.';
+
+// ============================================================================
+// Test Suite
+// ============================================================================
+
+describe('SourceCard', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  // ==========================================================================
+  // Rendering Tests
+  // ==========================================================================
+
+  describe('rendering', () => {
+    it('should render heading path correctly', () => {
+      // Test that the heading path is displayed with proper hierarchy
+      const source = createMockSource({
+        headingPath: 'Introduction > Thermal Comfort > PMV Model',
+      });
+
+      render(<SourceCard source={source} />);
+
+      expect(
+        screen.getByText('Introduction > Thermal Comfort > PMV Model')
+      ).toBeInTheDocument();
+    });
+
+    it('should render page number badge', () => {
+      // Test that page number is shown in a badge format
+      const source = createMockSource({ page: 78 });
+
+      render(<SourceCard source={source} />);
+
+      // Should show "Page X" format
+      expect(screen.getByText('Page 78')).toBeInTheDocument();
+    });
+
+    it('should render page badge with correct aria-label', () => {
+      // Test accessibility of page badge
+      const source = createMockSource({ page: 123 });
+
+      render(<SourceCard source={source} />);
+
+      const pageBadge = screen.getByLabelText('Page 123');
+      expect(pageBadge).toBeInTheDocument();
+    });
+
+    it('should render source text (truncated when long)', () => {
+      // Test that long text is truncated by default
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      // Should show truncated text with ellipsis
+      const textElement = screen.getByText(/This is a very long text/);
+      expect(textElement).toBeInTheDocument();
+      // Full text should not be visible
+      expect(screen.queryByText(LONG_TEXT)).not.toBeInTheDocument();
+    });
+
+    it('should render full text when short enough', () => {
+      // Test that short text is not truncated
+      const source = createMockSource({ text: SHORT_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.getByText(SHORT_TEXT)).toBeInTheDocument();
+    });
+
+    it('should render score badge when showScore is true', () => {
+      // Test score badge rendering with showScore prop
+      const source = createMockSource({ score: 0.85 });
+
+      render(<SourceCard source={source} showScore />);
+
+      // Score should be displayed as percentage
+      expect(screen.getByText('85%')).toBeInTheDocument();
+    });
+
+    it('should render score badge with correct aria-label', () => {
+      // Test accessibility of score badge
+      const source = createMockSource({ score: 0.92 });
+
+      render(<SourceCard source={source} showScore />);
+
+      expect(
+        screen.getByLabelText('Relevance score: 92 percent')
+      ).toBeInTheDocument();
+    });
+
+    it('should not render score badge when showScore is false', () => {
+      // Test that score is hidden by default
+      const source = createMockSource({ score: 0.75 });
+
+      render(<SourceCard source={source} showScore={false} />);
+
+      expect(screen.queryByText('75%')).not.toBeInTheDocument();
+    });
+
+    it('should not render score badge when showScore is true but score is undefined', () => {
+      // Test handling of undefined score
+      const source = createMockSource({ score: undefined });
+
+      render(<SourceCard source={source} showScore />);
+
+      // No percentage should be rendered
+      expect(screen.queryByText(/%/)).not.toBeInTheDocument();
+    });
+
+    it('should not render score badge by default (showScore defaults to false)', () => {
+      // Test default behavior
+      const source = createMockSource({ score: 0.88 });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.queryByText('88%')).not.toBeInTheDocument();
+    });
+
+    it('should render file icon in header', () => {
+      // Test that FileText icon is present
+      const source = createMockSource();
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.getByTestId('file-icon')).toBeInTheDocument();
+    });
+
+    it('should apply high score color styling (>= 80%)', () => {
+      // Test that high scores get success color
+      const source = createMockSource({ score: 0.85 });
+
+      render(<SourceCard source={source} showScore />);
+
+      const scoreBadge = screen.getByLabelText('Relevance score: 85 percent');
+      expect(scoreBadge.className).toMatch(/success/);
+    });
+
+    it('should apply medium score color styling (60-79%)', () => {
+      // Test that medium scores get primary color
+      const source = createMockSource({ score: 0.65 });
+
+      render(<SourceCard source={source} showScore />);
+
+      const scoreBadge = screen.getByLabelText('Relevance score: 65 percent');
+      expect(scoreBadge.className).toMatch(/primary/);
+    });
+
+    it('should apply low score color styling (< 60%)', () => {
+      // Test that low scores get muted color
+      const source = createMockSource({ score: 0.45 });
+
+      render(<SourceCard source={source} showScore />);
+
+      const scoreBadge = screen.getByLabelText('Relevance score: 45 percent');
+      expect(scoreBadge.className).toMatch(/foreground-muted|background-tertiary/);
+    });
+  });
+
+  // ==========================================================================
+  // Expand/Collapse Tests
+  // ==========================================================================
+
+  describe('expand/collapse', () => {
+    it('should start collapsed by default', () => {
+      // Test default collapsed state
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      // Should show "Show more" button indicating collapsed state
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+    });
+
+    it('should start expanded when defaultExpanded is true', () => {
+      // Test defaultExpanded prop
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} defaultExpanded />);
+
+      // Should show "Show less" button indicating expanded state
+      expect(screen.getByText('Show less')).toBeInTheDocument();
+      // Full text should be visible
+      expect(screen.getByText(LONG_TEXT)).toBeInTheDocument();
+    });
+
+    it('should toggle expand/collapse on button click', async () => {
+      // Test click interaction
+      const user = userEvent.setup();
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      // Initially collapsed
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+
+      // Click to expand
+      await user.click(screen.getByText('Show more'));
+
+      // Should now be expanded
+      expect(screen.getByText('Show less')).toBeInTheDocument();
+      expect(screen.getByText(LONG_TEXT)).toBeInTheDocument();
+
+      // Click to collapse
+      await user.click(screen.getByText('Show less'));
+
+      // Should be collapsed again
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+    });
+
+    it('should show full text when expanded', () => {
+      // Test that full text is visible when expanded
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} defaultExpanded />);
+
+      expect(screen.getByText(LONG_TEXT)).toBeInTheDocument();
+    });
+
+    it('should show truncated text when collapsed', () => {
+      // Test truncation in collapsed state
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      // Full text should not be present
+      expect(screen.queryByText(LONG_TEXT)).not.toBeInTheDocument();
+      // Truncated version should be present (with ellipsis)
+      expect(screen.getByText(/\.\.\./)).toBeInTheDocument();
+    });
+
+    it('should change button text from "Show more" to "Show less"', async () => {
+      // Test button label changes
+      const user = userEvent.setup();
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+      expect(screen.queryByText('Show less')).not.toBeInTheDocument();
+
+      await user.click(screen.getByText('Show more'));
+
+      expect(screen.queryByText('Show more')).not.toBeInTheDocument();
+      expect(screen.getByText('Show less')).toBeInTheDocument();
+    });
+
+    it('should show ChevronDown icon when collapsed', () => {
+      // Test chevron icon in collapsed state
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.getByTestId('chevron-down-icon')).toBeInTheDocument();
+    });
+
+    it('should show ChevronUp icon when expanded', () => {
+      // Test chevron icon in expanded state
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} defaultExpanded />);
+
+      expect(screen.getByTestId('chevron-up-icon')).toBeInTheDocument();
+    });
+
+    it('should not show expand button for short text', () => {
+      // Test that button is hidden when not needed
+      const source = createMockSource({ text: SHORT_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.queryByText('Show more')).not.toBeInTheDocument();
+      expect(screen.queryByText('Show less')).not.toBeInTheDocument();
+    });
+
+    it('should respect custom truncateLength prop', () => {
+      // Test custom truncation length
+      const source = createMockSource({ text: SHORT_TEXT });
+
+      // Set truncateLength shorter than the text
+      render(<SourceCard source={source} truncateLength={30} />);
+
+      // Should now show expand button since text exceeds custom limit
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+    });
+  });
+
+  // ==========================================================================
+  // Accessibility Tests
+  // ==========================================================================
+
+  describe('accessibility', () => {
+    it('should have correct aria-expanded attribute when collapsed', () => {
+      // Test aria-expanded state for collapsed
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      const button = screen.getByRole('button');
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('should have correct aria-expanded attribute when expanded', () => {
+      // Test aria-expanded state for expanded
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} defaultExpanded />);
+
+      const button = screen.getByRole('button');
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('should update aria-expanded attribute on toggle', async () => {
+      // Test aria-expanded updates dynamically
+      const user = userEvent.setup();
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      const button = screen.getByRole('button');
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+
+      await user.click(button);
+
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('should have aria-controls linking to text region', () => {
+      // Test aria-controls relationship
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      const button = screen.getByRole('button');
+      const controlsId = button.getAttribute('aria-controls');
+
+      expect(controlsId).toBe('source-text-region');
+      expect(document.getElementById('source-text-region')).toBeInTheDocument();
+    });
+
+    it('should respond to Enter key for toggle', async () => {
+      // Test keyboard navigation with Enter
+      const user = userEvent.setup();
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      const button = screen.getByRole('button');
+      button.focus();
+
+      // Press Enter to expand
+      await user.keyboard('{Enter}');
+
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('should respond to Space key for toggle', async () => {
+      // Test keyboard navigation with Space
+      const user = userEvent.setup();
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      const button = screen.getByRole('button');
+      button.focus();
+
+      // Press Space to expand
+      await user.keyboard(' ');
+
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('should have proper semantic structure with article element', () => {
+      // Test that card uses article element for semantic grouping
+      const source = createMockSource();
+
+      render(<SourceCard source={source} />);
+
+      const article = screen.getByRole('article');
+      expect(article).toBeInTheDocument();
+    });
+
+    it('should have header element for card header content', () => {
+      // Test semantic header structure
+      const source = createMockSource();
+
+      const { container } = render(<SourceCard source={source} />);
+
+      const header = container.querySelector('header');
+      expect(header).toBeInTheDocument();
+    });
+
+    it('should have descriptive aria-label on article element', () => {
+      // Test article has accessible name
+      const source = createMockSource({
+        headingPath: 'Thermal Comfort > PMV',
+        page: 15,
+      });
+
+      render(<SourceCard source={source} />);
+
+      const article = screen.getByRole('article');
+      expect(article).toHaveAttribute(
+        'aria-label',
+        'Source from Thermal Comfort > PMV, page 15'
+      );
+    });
+
+    it('should be keyboard focusable on expand button', () => {
+      // Test focus is possible
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      const button = screen.getByRole('button');
+      button.focus();
+
+      expect(document.activeElement).toBe(button);
+    });
+
+    it('should have visible focus styles', () => {
+      // Test that focus ring classes are present
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      const button = screen.getByRole('button');
+      expect(button.className).toMatch(/focus-visible:ring/);
+    });
+  });
+
+  // ==========================================================================
+  // Edge Cases Tests
+  // ==========================================================================
+
+  describe('edge cases', () => {
+    it('should handle very long text correctly', () => {
+      // Test with extremely long text
+      const veryLongText = 'A'.repeat(1000);
+      const source = createMockSource({ text: veryLongText });
+
+      render(<SourceCard source={source} />);
+
+      // Should truncate and show expand button
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+      // Full text should not be visible
+      expect(screen.queryByText(veryLongText)).not.toBeInTheDocument();
+    });
+
+    it('should handle short text (no truncation needed)', () => {
+      // Test that short text shows in full without button
+      const source = createMockSource({ text: 'Short.' });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.getByText('Short.')).toBeInTheDocument();
+      expect(screen.queryByText('Show more')).not.toBeInTheDocument();
+    });
+
+    it('should handle text at exact truncation boundary', () => {
+      // Test text that is exactly at the truncation limit
+      const exactLengthText = 'X'.repeat(150);
+      const source = createMockSource({ text: exactLengthText });
+
+      render(<SourceCard source={source} />);
+
+      // Should show full text since it's exactly at the limit
+      expect(screen.getByText(exactLengthText)).toBeInTheDocument();
+      expect(screen.queryByText('Show more')).not.toBeInTheDocument();
+    });
+
+    it('should handle text just over truncation boundary', () => {
+      // Test text that is just over the truncation limit
+      const overLimitText = 'X'.repeat(151);
+      const source = createMockSource({ text: overLimitText });
+
+      render(<SourceCard source={source} />);
+
+      // Should be truncated
+      expect(screen.queryByText(overLimitText)).not.toBeInTheDocument();
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+    });
+
+    it('should handle special characters in heading path', () => {
+      // Test special characters in heading path
+      const source = createMockSource({
+        headingPath: 'Chapter <1> & Section "2" > Sub\'section',
+      });
+
+      render(<SourceCard source={source} />);
+
+      expect(
+        screen.getByText('Chapter <1> & Section "2" > Sub\'section')
+      ).toBeInTheDocument();
+    });
+
+    it('should handle special characters in text content', () => {
+      // Test special characters in text
+      const source = createMockSource({ text: SPECIAL_CHARS_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.getByText(SPECIAL_CHARS_TEXT)).toBeInTheDocument();
+    });
+
+    it('should handle empty heading path', () => {
+      // Test empty heading path edge case
+      const source = createMockSource({ headingPath: '' });
+
+      render(<SourceCard source={source} />);
+
+      // Should still render without crashing
+      expect(screen.getByRole('article')).toBeInTheDocument();
+    });
+
+    it('should handle zero score correctly', () => {
+      // Test zero score display
+      const source = createMockSource({ score: 0 });
+
+      render(<SourceCard source={source} showScore />);
+
+      expect(screen.getByText('0%')).toBeInTheDocument();
+    });
+
+    it('should handle perfect score (1.0) correctly', () => {
+      // Test maximum score display
+      const source = createMockSource({ score: 1 });
+
+      render(<SourceCard source={source} showScore />);
+
+      expect(screen.getByText('100%')).toBeInTheDocument();
+    });
+
+    it('should round score to nearest integer', () => {
+      // Test score rounding
+      const source = createMockSource({ score: 0.876 });
+
+      render(<SourceCard source={source} showScore />);
+
+      expect(screen.getByText('88%')).toBeInTheDocument();
+    });
+
+    it('should handle page number 0', () => {
+      // Test edge case of page 0
+      const source = createMockSource({ page: 0 });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.getByText('Page 0')).toBeInTheDocument();
+    });
+
+    it('should handle very large page numbers', () => {
+      // Test large page number display
+      const source = createMockSource({ page: 99999 });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.getByText('Page 99999')).toBeInTheDocument();
+    });
+
+    it('should apply custom className to article element', () => {
+      // Test className prop is passed through
+      const source = createMockSource();
+
+      render(<SourceCard source={source} className="custom-class mt-4" />);
+
+      const article = screen.getByRole('article');
+      expect(article).toHaveClass('custom-class', 'mt-4');
+    });
+
+    it('should forward ref to article element', () => {
+      // Test ref forwarding
+      const source = createMockSource();
+      const ref = vi.fn();
+
+      render(<SourceCard source={source} ref={ref} />);
+
+      expect(ref).toHaveBeenCalled();
+      expect(ref.mock.calls[0][0]).toBeInstanceOf(HTMLElement);
+    });
+
+    it('should preserve whitespace in text content', () => {
+      // Test that whitespace is preserved
+      const textWithSpaces = 'Line 1\n\nLine 2\n  Indented line';
+      const source = createMockSource({ text: textWithSpaces });
+
+      const { container } = render(
+        <SourceCard source={source} defaultExpanded />
+      );
+
+      // Check whitespace-pre-wrap class is applied
+      const textElement = container.querySelector('p');
+      expect(textElement).toHaveClass('whitespace-pre-wrap');
+    });
+
+    it('should handle Unicode characters correctly', () => {
+      // Test Unicode text content
+      const unicodeText =
+        'Temperature: 25\u00B0C, PMV: \u00B10.5, Humidity: 50%';
+      const source = createMockSource({ text: unicodeText });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.getByText(unicodeText)).toBeInTheDocument();
+    });
+
+    it('should handle multi-byte characters in heading path', () => {
+      // Test international characters
+      const source = createMockSource({
+        headingPath: '\u65E5\u672C\u8A9E > \u7B2C1\u7AE0',
+      });
+
+      render(<SourceCard source={source} />);
+
+      expect(
+        screen.getByText('\u65E5\u672C\u8A9E > \u7B2C1\u7AE0')
+      ).toBeInTheDocument();
+    });
+  });
+
+  // ==========================================================================
+  // Props Tests
+  // ==========================================================================
+
+  describe('props', () => {
+    it('should use default truncateLength of 150', () => {
+      // Test default truncation behavior
+      const text149 = 'A'.repeat(149);
+      const text151 = 'A'.repeat(151);
+
+      const source149 = createMockSource({ text: text149 });
+      const source151 = createMockSource({ text: text151 });
+
+      const { rerender } = render(<SourceCard source={source149} />);
+      expect(screen.queryByText('Show more')).not.toBeInTheDocument();
+
+      rerender(<SourceCard source={source151} />);
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+    });
+
+    it('should accept custom truncateLength', () => {
+      // Test custom truncation length
+      const text = 'A'.repeat(100);
+      const source = createMockSource({ text });
+
+      render(<SourceCard source={source} truncateLength={50} />);
+
+      // Should be truncated with custom length
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+    });
+
+    it('should pass additional HTML attributes to article', () => {
+      // Test that other props are spread to article
+      const source = createMockSource();
+
+      render(
+        <SourceCard source={source} data-testid="custom-card" title="Test" />
+      );
+
+      const article = screen.getByTestId('custom-card');
+      expect(article).toHaveAttribute('title', 'Test');
+    });
+  });
+
+  // ==========================================================================
+  // Integration Tests
+  // ==========================================================================
+
+  describe('integration', () => {
+    it('should render complete source card with all elements', () => {
+      // Test full rendering with all features
+      const source = createMockSource({
+        id: 'complete-source',
+        headingPath: 'Documentation > API Reference > Functions',
+        page: 42,
+        text: LONG_TEXT,
+        score: 0.92,
+      });
+
+      render(<SourceCard source={source} showScore defaultExpanded />);
+
+      // All elements should be present
+      expect(
+        screen.getByText('Documentation > API Reference > Functions')
+      ).toBeInTheDocument();
+      expect(screen.getByText('Page 42')).toBeInTheDocument();
+      expect(screen.getByText('92%')).toBeInTheDocument();
+      expect(screen.getByText(LONG_TEXT)).toBeInTheDocument();
+      expect(screen.getByText('Show less')).toBeInTheDocument();
+      expect(screen.getByTestId('file-icon')).toBeInTheDocument();
+      expect(screen.getByTestId('chevron-up-icon')).toBeInTheDocument();
+    });
+
+    it('should maintain state across multiple expand/collapse cycles', async () => {
+      // Test state persistence
+      const user = userEvent.setup();
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      // Initial state
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+
+      // Cycle through states
+      for (let i = 0; i < 3; i++) {
+        await user.click(screen.getByRole('button'));
+        expect(screen.getByText('Show less')).toBeInTheDocument();
+
+        await user.click(screen.getByRole('button'));
+        expect(screen.getByText('Show more')).toBeInTheDocument();
+      }
+    });
+
+    it('should work with fireEvent as alternative to userEvent', () => {
+      // Test with fireEvent for synchronous testing
+      const source = createMockSource({ text: LONG_TEXT });
+
+      render(<SourceCard source={source} />);
+
+      expect(screen.getByText('Show more')).toBeInTheDocument();
+
+      fireEvent.click(screen.getByRole('button'));
+
+      expect(screen.getByText('Show less')).toBeInTheDocument();
+    });
+  });
+});

frontend/src/components/chat/__tests__/source-citations.test.tsx

@@ -0,0 +1,852 @@
+/**
+ * Unit Tests for SourceCitations Component
+ *
+ * Comprehensive test coverage for the collapsible source citations container.
+ * Tests rendering states, expand/collapse animations, accessibility features,
+ * and integration with SourceCard components.
+ *
+ * @module components/chat/__tests__/source-citations.test
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { SourceCitations } from '../source-citations';
+import type { Source } from '@/types';
+
+// ============================================================================
+// Test Fixtures
+// ============================================================================
+
+/**
+ * Create a mock source object for testing.
+ *
+ * @param overrides - Properties to override in the default source
+ * @returns Mock source object with sensible defaults
+ */
+function createMockSource(overrides: Partial<Source> = {}): Source {
+  return {
+    id: `source-${Math.random().toString(36).substring(7)}`,
+    headingPath: 'Chapter 1 > Section 2',
+    page: 10,
+    text: 'Sample source text for testing purposes.',
+    score: 0.8,
+    ...overrides,
+  };
+}
+
+/**
+ * Create an array of mock sources for testing.
+ *
+ * @param count - Number of sources to create
+ * @returns Array of mock source objects
+ */
+function createMockSources(count: number): Source[] {
+  return Array.from({ length: count }, (_, index) =>
+    createMockSource({
+      id: `source-${index + 1}`,
+      headingPath: `Chapter ${index + 1} > Section ${index + 1}`,
+      page: (index + 1) * 10,
+      text: `This is the text content for source ${index + 1}.`,
+      score: 0.9 - index * 0.1,
+    })
+  );
+}
+
+// ============================================================================
+// Test Suite
+// ============================================================================
+
+describe('SourceCitations', () => {
+  // ==========================================================================
+  // Rendering Tests
+  // ==========================================================================
+
+  describe('rendering', () => {
+    it('should render correct source count', () => {
+      // Test that source count is displayed correctly
+      const sources = createMockSources(5);
+
+      render(<SourceCitations sources={sources} />);
+
+      expect(screen.getByText('5 Sources')).toBeInTheDocument();
+    });
+
+    it('should render singular "Source" when count is 1', () => {
+      // Test singular grammar
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      expect(screen.getByText('1 Source')).toBeInTheDocument();
+    });
+
+    it('should render plural "Sources" when count > 1', () => {
+      // Test plural grammar
+      const sources = createMockSources(2);
+
+      render(<SourceCitations sources={sources} />);
+
+      expect(screen.getByText('2 Sources')).toBeInTheDocument();
+    });
+
+    it('should render plural "Sources" for large count', () => {
+      // Test plural grammar with larger numbers
+      const sources = createMockSources(10);
+
+      render(<SourceCitations sources={sources} />);
+
+      expect(screen.getByText('10 Sources')).toBeInTheDocument();
+    });
+
+    it('should not render when sources array is empty', () => {
+      // Test that component returns null for empty sources
+      const { container } = render(<SourceCitations sources={[]} />);
+
+      // Container should be empty (only the root div from render)
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('should not render when sources is an empty array', () => {
+      // Explicitly test empty array
+      const sources: Source[] = [];
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('should render all SourceCard components when expanded', () => {
+      // Test that all source cards are rendered
+      const sources = createMockSources(3);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      // Each source should have its heading path rendered
+      expect(screen.getByText('Chapter 1 > Section 1')).toBeInTheDocument();
+      expect(screen.getByText('Chapter 2 > Section 2')).toBeInTheDocument();
+      expect(screen.getByText('Chapter 3 > Section 3')).toBeInTheDocument();
+    });
+
+    it('should render toggle button in header', () => {
+      // Test toggle button presence
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      expect(screen.getByRole('button')).toBeInTheDocument();
+    });
+
+    it('should render source count in toggle button', () => {
+      // Test source count in button
+      const sources = createMockSources(3);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      expect(button).toHaveTextContent('3 Sources');
+    });
+  });
+
+  // ==========================================================================
+  // Expand/Collapse Tests
+  // ==========================================================================
+
+  describe('expand/collapse', () => {
+    it('should start collapsed by default', () => {
+      // Test default collapsed state
+      const sources = createMockSources(3);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      // Content region should be hidden (use container query since aria-hidden elements are not accessible)
+      const region = container.querySelector('[role="region"]');
+      expect(region).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('should start expanded when defaultExpanded is true', () => {
+      // Test defaultExpanded prop
+      const sources = createMockSources(3);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      // Content region should be visible (accessible when expanded)
+      const region = screen.getByRole('region');
+      expect(region).toHaveAttribute('aria-hidden', 'false');
+    });
+
+    it('should toggle on button click', async () => {
+      // Test click interaction
+      const user = userEvent.setup();
+      const sources = createMockSources(2);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      const region = container.querySelector('[role="region"]');
+
+      // Initially collapsed
+      expect(region).toHaveAttribute('aria-hidden', 'true');
+
+      // Click to expand
+      await user.click(button);
+      expect(region).toHaveAttribute('aria-hidden', 'false');
+
+      // Click to collapse
+      await user.click(button);
+      expect(region).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('should apply rotation class to chevron when expanded', () => {
+      // Test chevron rotation class - check the button contains rotated element
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      const button = screen.getByRole('button');
+      // The rotated element should have rotate-180 class when expanded
+      const rotatedElement = button.querySelector('.rotate-180');
+      expect(rotatedElement).toBeInTheDocument();
+    });
+
+    it('should not have rotation class when collapsed', () => {
+      // Test chevron not rotated when collapsed
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      // Should not have rotate-180 when collapsed
+      const rotatedElement = button.querySelector('.rotate-180');
+      expect(rotatedElement).toBeNull();
+    });
+
+    it('should apply grid-rows-[0fr] when collapsed', () => {
+      // Test CSS grid animation class for collapsed state
+      const sources = createMockSources(1);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      const region = container.querySelector('[role="region"]');
+      expect(region?.className).toMatch(/grid-rows-\[0fr\]/);
+    });
+
+    it('should apply grid-rows-[1fr] when expanded', () => {
+      // Test CSS grid animation class for expanded state
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      const region = screen.getByRole('region');
+      expect(region.className).toMatch(/grid-rows-\[1fr\]/);
+    });
+
+    it('should hide content when collapsed', () => {
+      // Test that content is hidden in collapsed state
+      const sources = createMockSources(1);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      const region = container.querySelector('[role="region"]');
+      expect(region).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('should show content when expanded', () => {
+      // Test that content is visible in expanded state
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      const region = screen.getByRole('region');
+      expect(region).toHaveAttribute('aria-hidden', 'false');
+      // Source text should be visible
+      expect(
+        screen.getByText('This is the text content for source 1.')
+      ).toBeInTheDocument();
+    });
+  });
+
+  // ==========================================================================
+  // Accessibility Tests
+  // ==========================================================================
+
+  describe('accessibility', () => {
+    it('should have correct aria-expanded attribute when collapsed', () => {
+      // Test aria-expanded in collapsed state
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('should have correct aria-expanded attribute when expanded', () => {
+      // Test aria-expanded in expanded state
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      const button = screen.getByRole('button');
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('should update aria-expanded on toggle', async () => {
+      // Test dynamic aria-expanded updates
+      const user = userEvent.setup();
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+
+      await user.click(button);
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+
+      await user.click(button);
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('should have aria-controls linking to content region', () => {
+      // Test aria-controls relationship
+      const sources = createMockSources(1);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      const region = container.querySelector('[role="region"]');
+
+      const controlsId = button.getAttribute('aria-controls');
+      expect(controlsId).toBeTruthy();
+      expect(region).toHaveAttribute('id', controlsId);
+    });
+
+    it('should have content region with role="region"', () => {
+      // Test region role on content
+      const sources = createMockSources(1);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      const region = container.querySelector('[role="region"]');
+      expect(region).toBeInTheDocument();
+    });
+
+    it('should have region with aria-labelledby pointing to button', () => {
+      // Test aria-labelledby relationship
+      const sources = createMockSources(1);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      const region = container.querySelector('[role="region"]');
+
+      const buttonId = button.getAttribute('id');
+      expect(buttonId).toBeTruthy();
+      expect(region).toHaveAttribute('aria-labelledby', buttonId);
+    });
+
+    it('should have descriptive aria-label on toggle button', () => {
+      // Test button has accessible name
+      const sources = createMockSources(3);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      const ariaLabel = button.getAttribute('aria-label');
+
+      expect(ariaLabel).toMatch(/3 Sources/);
+      expect(ariaLabel).toMatch(/Expand/);
+    });
+
+    it('should update aria-label when expanded', () => {
+      // Test aria-label changes based on state
+      const sources = createMockSources(3);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      const button = screen.getByRole('button');
+      const ariaLabel = button.getAttribute('aria-label');
+
+      expect(ariaLabel).toMatch(/3 Sources/);
+      expect(ariaLabel).toMatch(/Collapse/);
+    });
+
+    it('should respond to Enter key for toggle', async () => {
+      // Test keyboard navigation with Enter
+      const user = userEvent.setup();
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      button.focus();
+
+      await user.keyboard('{Enter}');
+
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('should respond to Space key for toggle', async () => {
+      // Test keyboard navigation with Space
+      const user = userEvent.setup();
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      button.focus();
+
+      await user.keyboard(' ');
+
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('should be keyboard focusable on toggle button', () => {
+      // Test focus is possible on button
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      button.focus();
+
+      expect(document.activeElement).toBe(button);
+    });
+
+    it('should have visible focus styles', () => {
+      // Test focus ring classes are present
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      expect(button.className).toMatch(/focus-visible:ring/);
+    });
+
+    it('should have unique IDs for multiple instances', () => {
+      // Test that multiple instances have unique IDs (using useId)
+      const sources1 = createMockSources(1);
+      const sources2 = createMockSources(2);
+
+      const { container } = render(
+        <>
+          <SourceCitations sources={sources1} />
+          <SourceCitations sources={sources2} />
+        </>
+      );
+
+      const buttons = screen.getAllByRole('button');
+      const regions = container.querySelectorAll('[role="region"]');
+
+      // IDs should be unique
+      expect(buttons[0].id).not.toBe(buttons[1].id);
+      expect(regions[0].id).not.toBe(regions[1].id);
+    });
+  });
+
+  // ==========================================================================
+  // Props Tests
+  // ==========================================================================
+
+  describe('props', () => {
+    it('should pass showScores prop to SourceCards', () => {
+      // Test that showScores propagates to child components
+      const sources = createMockSources(1);
+      sources[0].score = 0.95;
+
+      render(<SourceCitations sources={sources} showScores defaultExpanded />);
+
+      // Score should be visible on the source card
+      expect(screen.getByText('95%')).toBeInTheDocument();
+    });
+
+    it('should not show scores when showScores is false', () => {
+      // Test default behavior (showScores = false)
+      const sources = createMockSources(1);
+      sources[0].score = 0.95;
+
+      render(
+        <SourceCitations sources={sources} showScores={false} defaultExpanded />
+      );
+
+      // Score should not be visible
+      expect(screen.queryByText('95%')).not.toBeInTheDocument();
+    });
+
+    it('should not show scores by default', () => {
+      // Test that showScores defaults to false
+      const sources = createMockSources(1);
+      sources[0].score = 0.85;
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      expect(screen.queryByText('85%')).not.toBeInTheDocument();
+    });
+
+    it('should apply className prop to container', () => {
+      // Test className is applied
+      const sources = createMockSources(1);
+
+      const { container } = render(
+        <SourceCitations sources={sources} className="custom-class mt-8" />
+      );
+
+      const mainContainer = container.firstChild as HTMLElement;
+      expect(mainContainer).toHaveClass('custom-class', 'mt-8');
+    });
+
+    it('should apply defaultExpanded prop correctly', () => {
+      // Test defaultExpanded initial state
+      // Note: defaultExpanded only sets the initial state, it does not update when changed
+      // We need to test two separate renders
+      const sources = createMockSources(1);
+
+      // Test collapsed by default
+      const { unmount } = render(<SourceCitations sources={sources} />);
+      let button = screen.getByRole('button');
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+      unmount();
+
+      // Test expanded by default
+      render(<SourceCitations sources={sources} defaultExpanded />);
+      button = screen.getByRole('button');
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('should pass additional HTML attributes to container', () => {
+      // Test that other props spread to container div
+      const sources = createMockSources(1);
+
+      render(
+        <SourceCitations
+          sources={sources}
+          data-testid="citations-container"
+          title="Source citations"
+        />
+      );
+
+      const container = screen.getByTestId('citations-container');
+      expect(container).toHaveAttribute('title', 'Source citations');
+    });
+  });
+
+  // ==========================================================================
+  // Edge Cases Tests
+  // ==========================================================================
+
+  describe('edge cases', () => {
+    it('should handle single source correctly', () => {
+      // Test with exactly one source
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      expect(screen.getByText('1 Source')).toBeInTheDocument();
+      expect(screen.getByText('Chapter 1 > Section 1')).toBeInTheDocument();
+    });
+
+    it('should handle many sources correctly', () => {
+      // Test with large number of sources
+      const sources = createMockSources(20);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      expect(screen.getByText('20 Sources')).toBeInTheDocument();
+    });
+
+    it('should preserve source order', () => {
+      // Test that sources are rendered in provided order
+      const sources = [
+        createMockSource({ id: '1', headingPath: 'First Source' }),
+        createMockSource({ id: '2', headingPath: 'Second Source' }),
+        createMockSource({ id: '3', headingPath: 'Third Source' }),
+      ];
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      const articles = screen.getAllByRole('article');
+
+      // Check order is preserved
+      expect(articles[0]).toHaveAttribute(
+        'aria-label',
+        expect.stringContaining('First Source')
+      );
+      expect(articles[1]).toHaveAttribute(
+        'aria-label',
+        expect.stringContaining('Second Source')
+      );
+      expect(articles[2]).toHaveAttribute(
+        'aria-label',
+        expect.stringContaining('Third Source')
+      );
+    });
+
+    it('should handle sources with missing optional fields', () => {
+      // Test sources without score
+      const sources = [
+        createMockSource({ id: '1', score: undefined }),
+        createMockSource({ id: '2', score: undefined }),
+      ];
+
+      render(
+        <SourceCitations sources={sources} showScores defaultExpanded />
+      );
+
+      // Should render without crashing
+      expect(screen.getByText('2 Sources')).toBeInTheDocument();
+      // No percentages should be visible
+      expect(screen.queryByText(/%/)).not.toBeInTheDocument();
+    });
+
+    it('should handle sources with special characters', () => {
+      // Test sources with special characters in text
+      const sources = [
+        createMockSource({
+          id: '1',
+          headingPath: 'Chapter <1> & Section "2"',
+          text: 'Formula: T = (a + b) / 2 where a > 0 & b < 100',
+        }),
+      ];
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      expect(screen.getByText('Chapter <1> & Section "2"')).toBeInTheDocument();
+    });
+
+    it('should apply staggered animation delays to source cards', () => {
+      // Test animation delay styles
+      const sources = createMockSources(3);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      const articles = screen.getAllByRole('article');
+
+      // Check animation delays are applied (0ms, 50ms, 100ms)
+      expect(articles[0]).toHaveStyle({ animationDelay: '0ms' });
+      expect(articles[1]).toHaveStyle({ animationDelay: '50ms' });
+      expect(articles[2]).toHaveStyle({ animationDelay: '100ms' });
+    });
+
+    it('should cap animation delay at 200ms', () => {
+      // Test animation delay cap for many sources
+      const sources = createMockSources(10);
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      const articles = screen.getAllByRole('article');
+
+      // Fifth and later sources should have 200ms delay (index 4+ = 200ms)
+      expect(articles[4]).toHaveStyle({ animationDelay: '200ms' });
+      expect(articles[9]).toHaveStyle({ animationDelay: '200ms' });
+    });
+
+    it('should not apply animation styles when collapsed', () => {
+      // Test that animation is disabled when collapsed
+      const sources = createMockSources(3);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      // When collapsed, articles are inside aria-hidden region so we need to query directly
+      const articles = container.querySelectorAll('article');
+
+      // Animation should be none when collapsed
+      articles.forEach((article) => {
+        expect(article.className).toMatch(/animate-none/);
+      });
+    });
+
+    it('should handle undefined sources gracefully', () => {
+      // Test with undefined-like values (empty array)
+      // Note: TypeScript prevents passing undefined, but empty array is allowed
+      const { container } = render(<SourceCitations sources={[]} />);
+
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('should use unique keys for source cards', () => {
+      // Test that source IDs are used as keys (no key warnings in console)
+      const sources = createMockSources(3);
+
+      // This should not produce any React key warnings
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      expect(screen.getAllByRole('article')).toHaveLength(3);
+    });
+  });
+
+  // ==========================================================================
+  // Integration Tests
+  // ==========================================================================
+
+  describe('integration', () => {
+    it('should render complete component with all features enabled', () => {
+      // Test full rendering with all props
+      const sources = createMockSources(3);
+
+      render(
+        <SourceCitations
+          sources={sources}
+          defaultExpanded
+          showScores
+          className="test-class"
+        />
+      );
+
+      // Count label
+      expect(screen.getByText('3 Sources')).toBeInTheDocument();
+
+      // All source cards
+      expect(screen.getAllByRole('article')).toHaveLength(3);
+
+      // Scores should be visible
+      expect(screen.getByText('90%')).toBeInTheDocument();
+    });
+
+    it('should maintain state across multiple expand/collapse cycles', async () => {
+      // Test state persistence
+      const user = userEvent.setup();
+      const sources = createMockSources(2);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+
+      // Cycle through states multiple times
+      for (let i = 0; i < 3; i++) {
+        expect(button).toHaveAttribute('aria-expanded', 'false');
+
+        await user.click(button);
+        expect(button).toHaveAttribute('aria-expanded', 'true');
+
+        await user.click(button);
+        expect(button).toHaveAttribute('aria-expanded', 'false');
+      }
+    });
+
+    it('should work with fireEvent as alternative to userEvent', () => {
+      // Test with synchronous fireEvent
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+
+      fireEvent.click(button);
+
+      expect(button).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('should correctly toggle aria-hidden on content region', async () => {
+      // Test aria-hidden updates on content
+      const user = userEvent.setup();
+      const sources = createMockSources(1);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      const region = container.querySelector('[role="region"]');
+
+      expect(region).toHaveAttribute('aria-hidden', 'true');
+
+      await user.click(screen.getByRole('button'));
+      expect(region).toHaveAttribute('aria-hidden', 'false');
+
+      await user.click(screen.getByRole('button'));
+      expect(region).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('should render source cards that are individually expandable', async () => {
+      // Test that nested SourceCards work correctly
+      const sources = [
+        createMockSource({
+          id: '1',
+          text: 'A'.repeat(200), // Long enough to need truncation
+        }),
+      ];
+
+      render(<SourceCitations sources={sources} defaultExpanded />);
+
+      // SourceCard should have its own expand button
+      const buttons = screen.getAllByRole('button');
+      // One for SourceCitations, one for SourceCard
+      expect(buttons.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('should handle rapid toggle clicks', async () => {
+      // Test rapid clicking doesn't break state
+      const user = userEvent.setup();
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+
+      // Rapid clicks
+      await user.click(button);
+      await user.click(button);
+      await user.click(button);
+      await user.click(button);
+
+      // Should be in stable state (4 clicks = collapsed)
+      expect(button).toHaveAttribute('aria-expanded', 'false');
+    });
+  });
+
+  // ==========================================================================
+  // Visual Tests
+  // ==========================================================================
+
+  describe('visual styling', () => {
+    it('should have top border separator', () => {
+      // Test border styling
+      const sources = createMockSources(1);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      const mainContainer = container.firstChild as HTMLElement;
+      expect(mainContainer.className).toMatch(/border-t/);
+    });
+
+    it('should have proper padding and margin', () => {
+      // Test spacing classes
+      const sources = createMockSources(1);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      const mainContainer = container.firstChild as HTMLElement;
+      expect(mainContainer.className).toMatch(/mt-4/);
+      expect(mainContainer.className).toMatch(/pt-4/);
+    });
+
+    it('should have hover styles on toggle button', () => {
+      // Test hover classes are present
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      expect(button.className).toMatch(/hover:/);
+    });
+
+    it('should have transition classes for smooth animations', () => {
+      // Test transition classes are present
+      const sources = createMockSources(1);
+
+      const { container } = render(<SourceCitations sources={sources} />);
+
+      const region = container.querySelector('[role="region"]');
+      expect(region?.className).toMatch(/transition/);
+    });
+
+    it('should have group class for coordinated hover states', () => {
+      // Test group class on button for child hover coordination
+      const sources = createMockSources(1);
+
+      render(<SourceCitations sources={sources} />);
+
+      const button = screen.getByRole('button');
+      expect(button.className).toMatch(/group/);
+    });
+  });
+});

frontend/src/components/chat/chat-container.tsx

@@ -0,0 +1,905 @@
+/**
+ * ChatContainer Component
+ *
+ * The main orchestrating component for the chat interface following a
+ * true Claude-style minimal design philosophy. This component achieves
+ * a seamless, boundary-free aesthetic where the chat interface feels
+ * like a natural extension of the page itself rather than a contained widget.
+ *
+ * @module components/chat/chat-container
+ * @since 1.0.0
+ *
+ * @design
+ * ## Design Philosophy
+ *
+ * This component follows Claude's true minimal design principles:
+ * - **No visible boundaries**: No borders, shadows, or rounded corners on the main container
+ * - **Seamless integration**: Chat interface blends directly into the page background
+ * - **Minimal chrome**: Headers and inputs use subtle separation, not heavy styling
+ * - **Content-first**: Messages flow naturally on the page without visual containment
+ * - **Restrained color**: Purple accent color used sparingly for emphasis
+ * - **Flat design**: Zero shadows for a completely uncluttered feel
+ *
+ * @example
+ * // Basic usage in a page
+ * <ChatContainer />
+ *
+ * @example
+ * // With custom styling
+ * <ChatContainer className="h-screen" />
+ *
+ * @example
+ * // With initial messages (for session restoration)
+ * <ChatContainer initialMessages={savedMessages} />
+ */
+
+'use client';
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type HTMLAttributes,
+} from 'react';
+import { MessageSquare, AlertCircle, X } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { useChat, useSSE, useProviders } from '@/hooks';
+import type { SSEDoneResult, SSEError } from '@/hooks';
+import {
+  MemoizedChatMessage,
+  ChatInput,
+} from '@/components/chat';
+import type { ChatInputHandle } from '@/components/chat';
+import { EmptyState } from './empty-state';
+import { ErrorState } from './error-state';
+import type { ErrorType } from './error-state';
+import { Button } from '@/components/ui/button';
+import { Spinner } from '@/components/ui/spinner';
+import type { HistoryMessage, Message } from '@/types';
+import { CHAT_CONFIG } from '@/config/constants';
+
+/**
+ * Props for the ChatContainer component.
+ *
+ * Extends standard HTML div attributes for flexibility in styling
+ * and event handling, while providing chat-specific configuration.
+ */
+export interface ChatContainerProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'title'
+> {
+  /**
+   * Title displayed in the chat header.
+   * Defaults to "pythermalcomfort Chat".
+   *
+   * @default "pythermalcomfort Chat"
+   */
+  title?: string;
+
+  /**
+   * Whether to show the internal chat header.
+   * Set to false when the title is rendered at the page level.
+   *
+   * @default true
+   */
+  showHeader?: boolean;
+
+  /**
+   * Initial messages to populate the chat.
+   * Useful for restoring conversation state from localStorage or URL params.
+   *
+   * @default []
+   */
+  initialMessages?: Message[];
+
+  /**
+   * Callback fired when messages change.
+   * Useful for persisting conversation to localStorage.
+   *
+   * @param messages - The updated messages array
+   */
+  onMessagesChange?: (messages: Message[]) => void;
+}
+
+/**
+ * ChatHeader Component
+ *
+ * Renders a minimal, unobtrusive header section that stays out of the way.
+ * Follows Claude-style design where the header is subtle and doesn't
+ * distract from the main chat content.
+ *
+ * Note: Provider selection has been moved to the input area (ChatInput)
+ * to match Claude's UI pattern where the model selector is near the
+ * send button.
+ *
+ * @design
+ * - Small icon and text size to minimize visual weight
+ * - Muted colors so it doesn't compete with chat content
+ * - Very subtle bottom separator (minimal opacity)
+ * - Left-aligned, compact layout
+ *
+ * @param title - The main title text
+ *
+ * @internal
+ */
+function ChatHeader({
+  title,
+}: {
+  title: string;
+}): React.ReactElement {
+  return (
+    <header
+      className={cn(
+        /* Fixed header positioning - prevents shrinking */
+        'shrink-0',
+        /* Minimal padding - positioned far left */
+        'px-2 py-2',
+        /*
+         * Very subtle bottom border - minimal opacity for seamless design.
+         * This provides just enough visual separation without creating
+         * a heavy boundary. The low opacity makes it almost invisible
+         * while still providing structure.
+         */
+        'border-b border-[var(--border)]/10',
+        /* Flex layout with centered alignment */
+        'flex items-center gap-2'
+      )}
+    >
+      {/*
+       * Icon in purple - matches brand color.
+       */}
+      <MessageSquare
+        className="h-5 w-5 text-[var(--color-primary-500)]"
+        strokeWidth={2}
+        aria-hidden="true"
+      />
+
+      {/* Title - original size, positioned far left */}
+      <h1 className="text-base font-medium text-[var(--foreground)]">
+        {title}
+      </h1>
+    </header>
+  );
+}
+
+/**
+ * ErrorBanner Component
+ *
+ * Displays a subtle error message that doesn't dominate the interface.
+ * Uses a lighter error styling with reduced opacity backgrounds and
+ * softer colors for a less alarming appearance.
+ *
+ * @design
+ * - Light error background (reduced opacity) for subtle presence
+ * - No border for cleaner appearance
+ * - Smaller, less intrusive icon
+ * - Gentle dismiss button
+ *
+ * @param message - The error message to display
+ * @param onDismiss - Callback fired when the dismiss button is clicked
+ *
+ * @internal
+ */
+function ErrorBanner({
+  message,
+  onDismiss,
+}: {
+  message: string;
+  onDismiss: () => void;
+}): React.ReactElement {
+  return (
+    <div
+      role="alert"
+      className={cn(
+        /* Horizontal margin for alignment with content */
+        'mx-6 mb-4',
+        /* Compact padding for minimal footprint */
+        'px-3 py-2',
+        /* Very light error background - subtle, not alarming */
+        'bg-[var(--error)]/5',
+        /* Rounded corners matching the minimal design system */
+        'rounded-[var(--radius)]',
+        /* Flex layout for icon, message, and dismiss button */
+        'flex items-center gap-2',
+        /* Fade-in animation for smooth appearance */
+        'animate-fade-in'
+      )}
+    >
+      {/* Small error icon - less prominent for minimal design */}
+      <AlertCircle
+        className="h-4 w-4 shrink-0 text-[var(--error)]/80"
+        strokeWidth={1.5}
+        aria-hidden="true"
+      />
+
+      {/* Error message with softer color */}
+      <p className="flex-1 text-sm text-[var(--error)]/90">{message}</p>
+
+      {/* Minimal dismiss button */}
+      <Button
+        variant="ghost"
+        size="icon"
+        onClick={onDismiss}
+        aria-label="Dismiss error"
+        className={cn(
+          'h-5 w-5',
+          'text-[var(--error)]/60',
+          'hover:text-[var(--error)]',
+          'hover:bg-[var(--error)]/5'
+        )}
+      >
+        <X className="h-3 w-3" />
+      </Button>
+    </div>
+  );
+}
+
+/**
+ * LoadingOverlay Component
+ *
+ * A minimal loading indicator using the purple accent color.
+ * Designed to be subtle and unobtrusive while still communicating
+ * that a response is being generated.
+ *
+ * @design
+ * - Purple spinner to match the brand color
+ * - Muted text for the loading message
+ * - Compact layout that doesn't disrupt the message flow
+ * - Fade-in animation for smooth appearance
+ *
+ * @internal
+ */
+function LoadingOverlay(): React.ReactElement {
+  return (
+    <div
+      className={cn(
+        /* Generous horizontal padding to align with messages */
+        'px-6 py-4',
+        /* Flex layout for spinner and text */
+        'flex items-center gap-3',
+        /* Smooth fade-in animation */
+        'animate-fade-in'
+      )}
+      aria-live="polite"
+      aria-label="Generating response..."
+    >
+      {/* Purple spinner - matches the minimal design accent color */}
+      <Spinner
+        size="sm"
+        color="primary"
+        spinnerStyle="ring"
+        label="Thinking..."
+      />
+      {/* Subtle loading text - doesn't demand attention */}
+      <span className="text-sm text-[var(--foreground-muted)]">
+        Generating response...
+      </span>
+    </div>
+  );
+}
+
+/**
+ * Parsed error information for determining display type and retry behavior.
+ *
+ * @internal
+ */
+interface ParsedError {
+  /** The type of error for visual differentiation */
+  type: ErrorType;
+  /** Seconds to wait before retrying (for quota errors) */
+  retryAfterSeconds?: number;
+}
+
+/**
+ * Parse an SSE error to determine its type and retry information.
+ *
+ * Maps SSE error properties to ErrorState types:
+ * - Network errors (TypeError, fetch failures) -> 'network'
+ * - Errors with retryAfter (503 quota exceeded) -> 'quota'
+ * - Other errors -> 'general'
+ *
+ * @param error - The SSE error to parse
+ * @returns Parsed error with type and optional retry delay
+ *
+ * @internal
+ */
+function parseErrorType(error: SSEError): ParsedError {
+  // Network errors get special styling
+  if (error.isNetworkError) {
+    return { type: 'network' };
+  }
+
+  // Errors with retryAfter are quota/rate limit errors (HTTP 503)
+  if (error.retryAfter !== undefined && error.retryAfter > 0) {
+    return {
+      type: 'quota',
+      // Convert milliseconds to seconds for display
+      retryAfterSeconds: Math.ceil(error.retryAfter / 1000),
+    };
+  }
+
+  // Default to general error
+  return { type: 'general' };
+}
+
+/**
+ * ChatContainer Component
+ *
+ * The main chat interface component following true Claude-style minimal design.
+ * This component orchestrates all chat functionality while achieving a seamless,
+ * boundary-free aesthetic where messages flow naturally on the page background.
+ *
+ * @remarks
+ * ## Architecture
+ *
+ * The ChatContainer is composed of several sub-components:
+ *
+ * 1. **ChatHeader**: Minimal header with icon, title, and provider toggle (very subtle border)
+ * 2. **Message List**: Spacious scrollable area with generous message spacing
+ * 3. **EmptyState**: Clean welcome state with example questions
+ * 4. **ChatInput**: Minimal input area with very subtle top separator
+ * 5. **ErrorBanner**: Unobtrusive error display above the input
+ * 6. **LoadingOverlay**: Purple-themed loading indicator
+ *
+ * ## Design Philosophy
+ *
+ * This component implements true Claude-style minimal design:
+ *
+ * - **No visible boundaries**: Main container has no borders, shadows, or rounded corners
+ * - **Seamless integration**: Chat interface blends directly into the page background
+ * - **Minimal chrome**: Headers and inputs use very subtle separators (20% opacity borders)
+ * - **Content-first**: Messages flow naturally without visual containment
+ * - **Zero shadows**: Completely flat design with no elevation effects
+ * - **Generous spacing**: gap-6 between messages for content breathing room
+ * - **Purple accents**: Brand color used sparingly for icons and spinners
+ *
+ * ## State Management
+ *
+ * Uses the `useChat` hook for all state management:
+ * - `messages`: Array of all chat messages
+ * - `isLoading`: Whether a response is being generated
+ * - `error`: Current error message (if any)
+ *
+ * ## Auto-Scroll Behavior
+ *
+ * The message list automatically scrolls to the bottom when:
+ * - A new message is added
+ * - The assistant response is updated (streaming)
+ *
+ * Smooth scroll behavior is used for a polished feel. The scroll
+ * is triggered via a `useEffect` that watches the messages array.
+ *
+ * ## SSE Streaming Integration
+ *
+ * The submit handler uses the useSSE hook to stream responses from the
+ * backend. Tokens are appended to the assistant message in real-time,
+ * and the final response includes source citations from RAG retrieval.
+ *
+ * ## Performance Optimizations
+ *
+ * - Uses `MemoizedChatMessage` to prevent unnecessary re-renders
+ * - Callbacks are memoized with `useCallback`
+ * - Refs are used for direct DOM manipulation (auto-scroll)
+ * - Lazy loading patterns preserved for heavy dependencies
+ *
+ * ## Accessibility
+ *
+ * - Main region is marked with `role="region"` and proper aria-label
+ * - Error messages use `role="alert"` for screen reader announcements
+ * - Loading state is announced via `aria-live` region
+ * - All interactive elements are keyboard accessible
+ *
+ * ## Responsive Design
+ *
+ * The chat container is designed to work across all screen sizes:
+ * - Full viewport height on mobile
+ * - Constrained max-width on larger screens
+ * - Proper padding and spacing at all breakpoints
+ *
+ * @param props - ChatContainer component props
+ * @returns React element containing the complete chat interface
+ *
+ * @see {@link ChatContainerProps} for full prop documentation
+ * @see {@link useChat} for state management details
+ */
+const ChatContainer = forwardRef<HTMLDivElement, ChatContainerProps>(
+  (
+    {
+      title = 'pythermalcomfort Chat',
+      showHeader = true,
+      initialMessages = [],
+      onMessagesChange,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    /**
+     * Initialize the useChat hook for state management.
+     *
+     * This hook provides all message state and actions needed
+     * for the complete chat functionality.
+     */
+    const {
+      messages,
+      isLoading,
+      error,
+      addMessage,
+      updateLastMessage,
+      setIsLoading,
+      setError,
+      clearError,
+    } = useChat({
+      initialMessages,
+      onMessagesChange,
+    });
+
+    /**
+     * Initialize the useProviders hook for provider selection.
+     *
+     * This hook provides the selected provider to pass to the SSE stream.
+     * When selectedProvider is null, auto mode is active and the backend
+     * will select the best available provider.
+     */
+    const { selectedProvider } = useProviders();
+
+    /**
+     * Error type state for determining which error UI to show.
+     *
+     * - 'quota': HTTP 503 errors with retry-after header
+     * - 'network': Connection/fetch failures
+     * - 'general': All other errors
+     *
+     * Used to show appropriate ErrorState styling and behavior.
+     */
+    const [errorType, setErrorType] = useState<ErrorType | null>(null);
+
+    /**
+     * Seconds until retry is allowed (for quota errors).
+     *
+     * Populated when the server returns a 503 with Retry-After header.
+     * The ErrorState component uses this to show a countdown timer.
+     */
+    const [retryAfterSeconds, setRetryAfterSeconds] = useState<number | null>(
+      null
+    );
+
+    /**
+     * Ref to track if the user manually aborted the stream.
+     * Used to distinguish user cancellation from error states.
+     */
+    const userAbortedRef = useRef<boolean>(false);
+
+    /**
+     * Ref to store the last submitted query for retry functionality.
+     *
+     * When an error occurs and the user clicks retry, we need to re-submit
+     * the same query. This ref preserves the query across renders.
+     */
+    const lastQueryRef = useRef<string | null>(null);
+
+    /**
+     * Initialize the useSSE hook for streaming responses.
+     *
+     * Callbacks are wired to update the chat state as tokens
+     * arrive and when the stream completes or errors.
+     */
+    const { startStream, abort, isStreaming } = useSSE({
+      /**
+       * Handle incoming tokens during streaming.
+       * Appends each token to the last message content.
+       */
+      onToken: useCallback(
+        (content: string) => {
+          updateLastMessage((prev) => prev + content);
+        },
+        [updateLastMessage]
+      ),
+
+      /**
+       * Handle successful stream completion.
+       * Updates the message with the final response and sources.
+       */
+      onDone: useCallback(
+        (result: SSEDoneResult) => {
+          updateLastMessage(result.response, {
+            isStreaming: false,
+            sources: result.sources,
+          });
+          setIsLoading(false);
+        },
+        [updateLastMessage, setIsLoading]
+      ),
+
+      /**
+       * Handle stream errors.
+       *
+       * This callback processes errors from the SSE stream and updates the UI
+       * appropriately based on the error type:
+       *
+       * 1. If user manually aborted, skip error handling entirely
+       * 2. Parse the error to determine type (network, quota, or general)
+       * 3. Update error state (type, message, retry delay)
+       * 4. If there are existing messages, update the last assistant message
+       *    to show an error occurred. The ErrorBanner will handle display.
+       * 5. If no messages exist, the ErrorState component will be shown
+       *    in place of the EmptyState (handled in render logic)
+       */
+      onError: useCallback(
+        (error: SSEError) => {
+          // Don't show error if user manually aborted
+          if (userAbortedRef.current) {
+            userAbortedRef.current = false;
+            return;
+          }
+
+          // Parse the error to determine type and retry behavior
+          const parsed = parseErrorType(error);
+
+          // Update error state for UI rendering decisions
+          setErrorType(parsed.type);
+          setRetryAfterSeconds(parsed.retryAfterSeconds ?? null);
+          setError(error.message);
+          setIsLoading(false);
+
+          // Only update the assistant message if we have messages in the chat.
+          // For empty state errors, we show the full ErrorState component instead.
+          if (messages.length > 0) {
+            updateLastMessage(
+              'Sorry, I encountered an error. Please try again.',
+              {
+                isStreaming: false,
+              }
+            );
+          }
+        },
+        [setError, setIsLoading, updateLastMessage, messages.length]
+      ),
+    });
+
+    /**
+     * Ref to the messages container for auto-scroll functionality.
+     * We scroll this container to the bottom when new messages arrive.
+     */
+    const messagesContainerRef = useRef<HTMLDivElement>(null);
+
+    /**
+     * Ref to the ChatInput component for programmatic control.
+     * Used to populate the input when example questions are clicked.
+     */
+    const chatInputRef = useRef<ChatInputHandle>(null);
+
+    /**
+     * Ref to track the end of the messages list.
+     * Used as the target for scroll-into-view behavior.
+     */
+    const messagesEndRef = useRef<HTMLDivElement>(null);
+
+    /**
+     * Auto-scroll effect that triggers when messages change.
+     *
+     * Scrolls the message list to the bottom with smooth behavior
+     * whenever the messages array is updated. This ensures users
+     * always see the latest message without manual scrolling.
+     *
+     * Implementation note: We use a slight delay to ensure the DOM
+     * has updated before scrolling. This prevents scroll jitter
+     * during rapid streaming updates.
+     */
+    useEffect(() => {
+      // Only scroll if there are messages
+      if (messages.length === 0) return;
+
+      // Use requestAnimationFrame for smooth scroll after DOM update
+      const timeoutId = requestAnimationFrame(() => {
+        messagesEndRef.current?.scrollIntoView({
+          behavior: 'smooth',
+          block: 'end',
+        });
+      });
+
+      return () => cancelAnimationFrame(timeoutId);
+    }, [messages]);
+
+    /**
+     * Handle example question clicks from EmptyState.
+     *
+     * Populates the chat input with the clicked question,
+     * allowing users to submit it or modify before sending.
+     */
+    const handleExampleClick = useCallback((question: string) => {
+      chatInputRef.current?.setValue(question);
+      chatInputRef.current?.focus();
+    }, []);
+
+    /**
+     * Clear all error state including type and retry information.
+     *
+     * This is an enhanced version of clearError that also resets
+     * the errorType and retryAfterSeconds state. Used when:
+     * - User dismisses an error
+     * - A new query is submitted
+     * - Retry is initiated
+     */
+    const handleClearError = useCallback(() => {
+      clearError();
+      setErrorType(null);
+      setRetryAfterSeconds(null);
+    }, [clearError]);
+
+    /**
+     * Handle aborting the current stream.
+     *
+     * Called when the user wants to cancel an in-progress response.
+     * Marks the abort as user-initiated to prevent error display.
+     *
+     * Note: This function is available for future use when a cancel button
+     * is added to the UI. Currently prefixed with underscore to satisfy
+     * the linter, but the functionality is fully implemented.
+     *
+     * @example
+     * // Usage with a cancel button:
+     * <Button onClick={_handleAbort}>Cancel</Button>
+     */
+    const _handleAbort = useCallback(() => {
+      userAbortedRef.current = true;
+      abort();
+      setIsLoading(false);
+      // Update the last message to show it was cancelled
+      updateLastMessage((prev) => prev || 'Response cancelled.', {
+        isStreaming: false,
+      });
+    }, [abort, setIsLoading, updateLastMessage]);
+
+    /**
+     * Handle message submission from ChatInput.
+     *
+     * Initiates an SSE stream to the backend:
+     * 1. Clears any existing errors (including type and retry info)
+     * 2. Stores the query for potential retry
+     * 3. Aborts any in-progress stream
+     * 4. Adds the user message to the conversation
+     * 5. Creates a placeholder assistant message
+     * 6. Starts the SSE stream with the selected provider
+     *
+     * @param content - The user's message content
+     */
+    const handleSubmit = useCallback(
+      (content: string) => {
+        // Guard against empty submissions
+        if (!content.trim()) return;
+
+        // Clear any existing errors (including error type and retry info)
+        handleClearError();
+
+        // Store the query for retry functionality
+        // This allows us to re-submit the same query if an error occurs
+        lastQueryRef.current = content;
+
+        // If already streaming, abort the previous stream
+        if (isStreaming) {
+          userAbortedRef.current = true;
+          abort();
+        }
+
+        // =====================================================================
+        // Build conversation history for multi-turn context
+        // =====================================================================
+        // Extract the most recent messages (before adding the new user message)
+        // Filter out incomplete streaming messages and limit to maxHistoryForAPI
+        // This provides context to the LLM for follow-up questions
+        const history: HistoryMessage[] = messages
+          .filter((msg) => !msg.isStreaming && msg.content.trim())
+          .slice(-CHAT_CONFIG.maxHistoryForAPI)
+          .map((msg) => ({
+            role: msg.role,
+            content: msg.content,
+          }));
+
+        // Add the user's message to the conversation
+        addMessage('user', content);
+
+        // Add a placeholder for the assistant's response
+        // Mark it as streaming so it shows the loading cursor
+        addMessage('assistant', '', { isStreaming: true });
+
+        // Set loading state
+        setIsLoading(true);
+
+        // Reset the abort flag before starting new stream
+        userAbortedRef.current = false;
+
+        // Start the SSE stream with the selected provider and conversation history
+        // Pass undefined instead of null for auto mode
+        startStream(content, selectedProvider ?? undefined, history);
+      },
+      [
+        addMessage,
+        setIsLoading,
+        handleClearError,
+        isStreaming,
+        abort,
+        startStream,
+        selectedProvider,
+        messages,
+      ]
+    );
+
+    /**
+     * Handle retry after an error occurs.
+     *
+     * Clears the error state and re-submits the last query.
+     * For empty state errors (no messages), this will submit the query fresh.
+     * For mid-conversation errors, this will add a new message pair.
+     *
+     * Note: For network errors where the query never reached the server,
+     * this effectively gives the user a second chance to submit.
+     */
+    const handleRetry = useCallback(() => {
+      handleClearError();
+      if (lastQueryRef.current) {
+        handleSubmit(lastQueryRef.current);
+      }
+    }, [handleClearError, handleSubmit]);
+
+    /**
+     * Determine if we should show the empty state.
+     * Only show when there are no messages in the conversation.
+     */
+    const showEmptyState = messages.length === 0;
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          /* Full height flex layout - fills available space */
+          'flex flex-col',
+          'h-full',
+          /* Container constraints - max-width for readability on large screens */
+          'mx-auto w-full max-w-4xl',
+          /*
+           * TRUE CLAUDE-STYLE MINIMAL DESIGN:
+           * No borders, no shadows, no rounded corners.
+           * The chat interface blends seamlessly into the page background.
+           * Messages flow naturally without visual containment.
+           * This creates a sense that the chat is part of the page itself,
+           * not a separate contained widget.
+           */
+          /* Overflow handling for scroll containment */
+          'overflow-hidden',
+          className
+        )}
+        role="region"
+        aria-label="Chat interface"
+        {...props}
+      >
+        {/* Optional internal header - can be hidden when title is at page level */}
+        {showHeader && <ChatHeader title={title} />}
+
+        {/*
+         * Messages Area - Scrollable container with generous spacing.
+         * Increased padding and gap for content breathing room.
+         */}
+        <div
+          ref={messagesContainerRef}
+          className={cn(
+            /* Flex grow to fill available space */
+            'flex-1',
+            /* Scroll behavior for overflow content */
+            'overflow-y-auto',
+            /*
+             * Generous padding - increased from px-4 py-4 to px-6 py-6.
+             * This provides more breathing room around the content,
+             * making the interface feel more spacious and open.
+             */
+            'px-6 py-6',
+            /* Flex column for vertical message layout */
+            'flex flex-col',
+            /*
+             * Increased gap between messages - gap-6 instead of gap-4.
+             * This gives each message more vertical breathing room,
+             * improving readability and reducing visual clutter.
+             * For empty/error states, use justify-center for vertical centering.
+             */
+            showEmptyState ? 'justify-center' : 'gap-6'
+          )}
+        >
+          {/*
+           * Content rendering logic:
+           *
+           * 1. Empty state WITH error -> Show full-page ErrorState component
+           *    This provides a prominent error display when the user hasn't
+           *    started a conversation yet (e.g., first query fails).
+           *
+           * 2. Empty state WITHOUT error -> Show EmptyState with examples
+           *    The normal welcome state with example questions.
+           *
+           * 3. Messages exist -> Show message list
+           *    The ErrorBanner handles errors during conversation.
+           */}
+          {showEmptyState && error ? (
+            /* Full-page error state for empty chat with error */
+            <ErrorState
+              type={errorType || 'general'}
+              message={error}
+              retryAfter={retryAfterSeconds ?? undefined}
+              onRetry={handleRetry}
+              onDismiss={handleClearError}
+            />
+          ) : showEmptyState ? (
+            /* Normal empty state with example questions */
+            <EmptyState onExampleClick={handleExampleClick} />
+          ) : (
+            <>
+              {/* Render all messages with increased spacing (gap-6) */}
+              {messages.map((message) => (
+                <MemoizedChatMessage
+                  key={message.id}
+                  message={message}
+                  showTimestamp={!message.isStreaming}
+                />
+              ))}
+
+              {/* Minimal loading indicator with purple spinner */}
+              {isLoading && <LoadingOverlay />}
+
+              {/* Scroll anchor - used for auto-scroll functionality */}
+              <div ref={messagesEndRef} aria-hidden="true" />
+            </>
+          )}
+        </div>
+
+        {/*
+         * Error Banner - Shown above input for mid-conversation errors.
+         *
+         * Only display the ErrorBanner when:
+         * - There IS an error
+         * - There ARE messages in the chat (not empty state)
+         *
+         * For empty state errors, we show the full ErrorState component
+         * instead (handled above), so we hide the banner in that case.
+         */}
+        {error && !showEmptyState && (
+          <ErrorBanner message={error} onDismiss={handleClearError} />
+        )}
+
+        {/*
+         * Input Area - Fixed at bottom with minimal visual separation.
+         * True Claude-style: very subtle top border, no heavy containers.
+         * The input blends naturally into the page.
+         */}
+        <div
+          className={cn(
+            /* Fixed positioning - prevents shrinking */
+            'shrink-0',
+            /*
+             * Generous padding - provides breathing room without
+             * relying on heavy borders or backgrounds.
+             */
+            'px-6 pt-4 pb-4',
+            /*
+             * Very subtle top border - minimal opacity for seamless design.
+             * Just enough visual separation to indicate the input area
+             * without creating a heavy boundary.
+             */
+            'border-t border-[var(--border)]/20'
+          )}
+        >
+          <ChatInput
+            ref={chatInputRef}
+            onSubmit={handleSubmit}
+            isLoading={isLoading}
+            autoFocus={true}
+          />
+        </div>
+      </div>
+    );
+  }
+);
+
+/* Display name for React DevTools debugging */
+ChatContainer.displayName = 'ChatContainer';
+
+export { ChatContainer };

frontend/src/components/chat/chat-input.tsx

@@ -0,0 +1,721 @@
+/**
+ * ChatInput Component
+ *
+ * A refined, modern chat input component inspired by Claude's design language.
+ * Features a clean, minimal aesthetic with subtle purple accents and smooth
+ * transitions for a premium user experience.
+ *
+ * @module components/chat/chat-input
+ * @since 1.0.0
+ *
+ * ## Design Philosophy
+ *
+ * This component follows Claude's design principles:
+ * - **Minimal and clean**: Reduced visual noise with purposeful whitespace
+ * - **Subtle interactions**: Gentle hover states and smooth transitions
+ * - **Focus on content**: The user's input is the hero, not the UI chrome
+ * - **Accessible by default**: High contrast ratios and clear focus states
+ *
+ * ## Visual Design Details
+ *
+ * ### Container
+ * - Clean white background with subtle border
+ * - Rounded corners (12px) for a friendly, modern feel
+ * - Soft shadow on focus for depth without being distracting
+ * - Purple glow effect on focus using box-shadow (not ring)
+ *
+ * ### Textarea
+ * - Borderless design that blends with the container
+ * - Muted placeholder text for visual hierarchy
+ * - Smooth auto-grow behavior without jarring size changes
+ *
+ * ### Send Button
+ * - Circular shape for visual distinction
+ * - Purple gradient background matching brand colors
+ * - Subtle scale animation on hover for tactile feedback
+ * - Clear disabled state without being visually jarring
+ *
+ * ### Supporting Elements
+ * - Character counter in subtle, smaller text
+ * - Keyboard hints in lighter color, smaller size
+ * - All supporting text uses muted colors to not compete with main input
+ *
+ * @example
+ * // Basic usage
+ * <ChatInput onSubmit={(message) => handleSubmit(message)} />
+ *
+ * @example
+ * // With loading state
+ * <ChatInput
+ *   onSubmit={handleSubmit}
+ *   isLoading={isProcessing}
+ *   disabled={!isConnected}
+ * />
+ *
+ * @example
+ * // Custom placeholder and max length
+ * <ChatInput
+ *   onSubmit={handleSubmit}
+ *   placeholder="Type your question here..."
+ *   maxLength={500}
+ * />
+ */
+
+'use client';
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+  type FormEvent,
+  type KeyboardEvent,
+  type ChangeEvent,
+} from 'react';
+import { Send } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { Spinner } from '@/components/ui/spinner';
+import { ProviderSelector } from './provider-selector';
+
+/**
+ * Maximum height for the auto-growing textarea in pixels.
+ * After reaching this height, the textarea becomes scrollable.
+ * This value ensures the input doesn't dominate the viewport.
+ */
+const MAX_TEXTAREA_HEIGHT = 200;
+
+/**
+ * Minimum height for the textarea in pixels.
+ * Ensures consistent appearance even with empty content.
+ * Matches standard single-line input height for visual consistency.
+ */
+const MIN_TEXTAREA_HEIGHT = 56;
+
+/**
+ * Default character limit for messages.
+ * Can be overridden via the maxLength prop.
+ * 1000 characters balances detailed questions with API limits.
+ */
+const DEFAULT_MAX_LENGTH = 1000;
+
+/**
+ * Default placeholder text for the input.
+ * Encourages users to ask questions in a friendly tone.
+ */
+const DEFAULT_PLACEHOLDER = 'Ask your question...';
+
+/**
+ * Ref handle exposed by ChatInput for imperative control.
+ *
+ * Allows parent components to programmatically control the input,
+ * useful for accessibility features or external form management.
+ */
+export interface ChatInputHandle {
+  /** Focus the textarea input */
+  focus: () => void;
+  /** Clear the input value */
+  clear: () => void;
+  /** Get the current input value */
+  getValue: () => string;
+  /** Set the input value programmatically */
+  setValue: (value: string) => void;
+}
+
+/**
+ * Props for the ChatInput component.
+ *
+ * Designed for flexibility with sensible defaults, supporting
+ * both controlled and uncontrolled usage patterns.
+ */
+export interface ChatInputProps {
+  /**
+   * Callback fired when the user submits a message.
+   * Called with the trimmed message content.
+   * The input is automatically cleared after submission.
+   *
+   * @param message - The trimmed message text
+   */
+  onSubmit: (message: string) => void;
+
+  /**
+   * Whether the input is in a loading/processing state.
+   * Disables the input and shows a loading spinner in the submit button.
+   *
+   * @default false
+   */
+  isLoading?: boolean;
+
+  /**
+   * Whether the input is disabled.
+   * Separate from isLoading to allow disabling without loading indicator.
+   *
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Placeholder text for the textarea.
+   *
+   * @default "Ask a question about pythermalcomfort..."
+   */
+  placeholder?: string;
+
+  /**
+   * Maximum character length for the input.
+   * Shows a character counter when approaching the limit.
+   *
+   * @default 1000
+   */
+  maxLength?: number;
+
+  /**
+   * Whether to show the character count indicator.
+   * Shows when the user has typed more than 80% of maxLength.
+   *
+   * @default true
+   */
+  showCharacterCount?: boolean;
+
+  /**
+   * Whether to auto-focus the input on mount.
+   * Useful for immediate input availability.
+   *
+   * @default true
+   */
+  autoFocus?: boolean;
+
+  /**
+   * Additional CSS classes for the container.
+   */
+  className?: string;
+
+  /**
+   * Additional CSS classes for the textarea element.
+   */
+  textareaClassName?: string;
+}
+
+/**
+ * ChatInput Component
+ *
+ * A feature-rich chat input component optimized for conversational interfaces
+ * with a refined, Claude-inspired visual design.
+ *
+ * @remarks
+ * ## Features
+ *
+ * ### Auto-Growing Textarea
+ * The textarea automatically grows as the user types, up to a maximum height
+ * of 200px. After reaching the max height, the content becomes scrollable.
+ * This provides a seamless typing experience without manual resizing.
+ *
+ * ### Keyboard Support
+ * - **Enter**: Submits the message (when not empty and not loading)
+ * - **Shift+Enter**: Inserts a new line (for multi-line messages)
+ * - Submission is blocked when the input is empty or whitespace-only
+ *
+ * ### Character Limit
+ * - Configurable maximum character limit (default: 1000)
+ * - Visual counter appears when approaching the limit (>80%)
+ * - Counter turns red when at or over the limit
+ * - Submission is blocked when over the limit
+ *
+ * ### Loading State
+ * - When isLoading is true, the textarea and button are disabled
+ * - The submit button shows a loading spinner instead of the send icon
+ * - Prevents accidental double-submission
+ *
+ * ### Accessibility
+ * - Proper labeling via aria-label on the textarea
+ * - Submit button has aria-label for screen readers
+ * - Disabled state is communicated via aria-disabled
+ * - Character counter is announced to screen readers
+ *
+ * ## Performance
+ * - Uses requestAnimationFrame for smooth height calculations
+ * - Memoized callbacks to prevent unnecessary re-renders
+ * - Auto-focus uses useEffect to avoid hydration mismatches
+ *
+ * @param props - ChatInput component props
+ * @returns React element containing the chat input form
+ *
+ * @see {@link ChatInputProps} for full prop documentation
+ * @see {@link ChatInputHandle} for imperative API
+ */
+const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
+  (
+    {
+      onSubmit,
+      isLoading = false,
+      disabled = false,
+      placeholder = DEFAULT_PLACEHOLDER,
+      maxLength = DEFAULT_MAX_LENGTH,
+      showCharacterCount = true,
+      autoFocus = true,
+      className,
+      textareaClassName,
+    },
+    ref
+  ) => {
+    /**
+     * Internal state for the input value.
+     * Controlled internally with external access via ref handle.
+     */
+    const [value, setValue] = useState('');
+
+    /**
+     * Track focus state for container styling.
+     * Used to apply the purple glow effect on focus.
+     */
+    const [isFocused, setIsFocused] = useState(false);
+
+    /**
+     * Ref to the textarea element for height calculations and focus.
+     */
+    const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+    /**
+     * Computed values for UI state
+     */
+    const characterCount = value.length;
+    const isOverLimit = characterCount > maxLength;
+    const isNearLimit = characterCount > maxLength * 0.8;
+    const isEmpty = value.trim().length === 0;
+    const isDisabled = disabled || isLoading;
+    const canSubmit = !isEmpty && !isOverLimit && !isDisabled;
+
+    /**
+     * Reset textarea height to minimum.
+     * Called after submission or clearing.
+     *
+     * Declared before useImperativeHandle since it's used in the handle.
+     */
+    const resetTextareaHeight = useCallback(() => {
+      if (textareaRef.current) {
+        textareaRef.current.style.height = `${MIN_TEXTAREA_HEIGHT}px`;
+      }
+    }, []);
+
+    /**
+     * Adjust textarea height based on content.
+     *
+     * Algorithm:
+     * 1. Reset height to auto to get accurate scrollHeight
+     * 2. Set height to scrollHeight, clamped to min/max bounds
+     *
+     * Uses direct style manipulation for performance (avoids re-render).
+     * Declared before useImperativeHandle since it's used in the handle.
+     */
+    const adjustTextareaHeight = useCallback(() => {
+      const textarea = textareaRef.current;
+      if (!textarea) return;
+
+      // Reset height to recalculate scrollHeight accurately
+      textarea.style.height = 'auto';
+
+      // Calculate new height within bounds
+      const newHeight = Math.min(
+        Math.max(textarea.scrollHeight, MIN_TEXTAREA_HEIGHT),
+        MAX_TEXTAREA_HEIGHT
+      );
+
+      textarea.style.height = `${newHeight}px`;
+    }, []);
+
+    /**
+     * Expose imperative handle for parent component control.
+     *
+     * This allows parent components to:
+     * - Focus the input (e.g., after closing a modal)
+     * - Clear the input (e.g., on conversation reset)
+     * - Get/set value (e.g., for draft restoration)
+     */
+    useImperativeHandle(
+      ref,
+      () => ({
+        focus: () => {
+          textareaRef.current?.focus();
+        },
+        clear: () => {
+          setValue('');
+          resetTextareaHeight();
+        },
+        getValue: () => value,
+        setValue: (newValue: string) => {
+          setValue(newValue);
+          // Defer height calculation to after state update
+          requestAnimationFrame(adjustTextareaHeight);
+        },
+      }),
+      [value, resetTextareaHeight, adjustTextareaHeight]
+    );
+
+    /**
+     * Handle input value changes.
+     * Updates state and adjusts textarea height.
+     */
+    const handleChange = useCallback(
+      (event: ChangeEvent<HTMLTextAreaElement>) => {
+        setValue(event.target.value);
+        // Defer to next frame for accurate height calculation
+        requestAnimationFrame(adjustTextareaHeight);
+      },
+      [adjustTextareaHeight]
+    );
+
+    /**
+     * Handle form submission.
+     * Validates input, calls onSubmit, and clears the input.
+     */
+    const handleSubmit = useCallback(
+      (event?: FormEvent) => {
+        event?.preventDefault();
+
+        // Validate submission conditions
+        if (!canSubmit) return;
+
+        // Get trimmed value for submission
+        const trimmedValue = value.trim();
+
+        // Call parent callback
+        onSubmit(trimmedValue);
+
+        // Clear input and reset height
+        setValue('');
+        resetTextareaHeight();
+
+        // Refocus textarea for continued conversation
+        requestAnimationFrame(() => {
+          textareaRef.current?.focus();
+        });
+      },
+      [canSubmit, value, onSubmit, resetTextareaHeight]
+    );
+
+    /**
+     * Handle keyboard events for submission.
+     *
+     * - Enter without Shift: Submit the message
+     * - Shift+Enter: Insert new line (default behavior)
+     */
+    const handleKeyDown = useCallback(
+      (event: KeyboardEvent<HTMLTextAreaElement>) => {
+        // Only handle Enter key
+        if (event.key !== 'Enter') return;
+
+        // Shift+Enter: Allow default new line behavior
+        if (event.shiftKey) return;
+
+        // Prevent default to avoid new line insertion
+        event.preventDefault();
+
+        // Submit if conditions are met
+        handleSubmit();
+      },
+      [handleSubmit]
+    );
+
+    /**
+     * Auto-focus effect on mount.
+     * Wrapped in useEffect to avoid hydration mismatches
+     * and respect the autoFocus prop.
+     */
+    useEffect(() => {
+      if (autoFocus && textareaRef.current) {
+        // Small delay to ensure DOM is ready
+        const timeoutId = setTimeout(() => {
+          textareaRef.current?.focus();
+        }, 100);
+
+        return () => clearTimeout(timeoutId);
+      }
+    }, [autoFocus]);
+
+    /**
+     * Calculate character count display text.
+     * Only shown when approaching or exceeding the limit.
+     */
+    const characterCountText = `${characterCount}/${maxLength}`;
+
+    return (
+      <form
+        onSubmit={handleSubmit}
+        className={cn(
+          /* Container styling - vertical stack with tight spacing */
+          'flex flex-col gap-1.5',
+          className
+        )}
+      >
+        {/*
+         * Main Input Container
+         *
+         * Design: A prominent, refined container that serves as the visual
+         * anchor for the input area. Uses subtle rounded borders and
+         * a clean background that elevates slightly on focus.
+         *
+         * Focus State: Instead of the typical focus ring, we use a soft
+         * purple glow effect via box-shadow. This creates a more refined,
+         * less jarring focus indicator that feels premium.
+         */}
+        <div
+          className={cn(
+            /* Base layout - flex with bottom alignment for button */
+            'flex items-end gap-3',
+            /* Padding - comfortable internal spacing */
+            'p-3',
+            /* Background - clean white/background color */
+            'bg-white dark:bg-[var(--background)]',
+            /* Border - subtle rounded border */
+            'border border-gray-200 dark:border-gray-700',
+            'rounded-xl',
+            /* Base shadow - subtle elevation */
+            'shadow-sm',
+            /*
+             * Focus state styles
+             *
+             * Uses box-shadow for the purple glow effect instead of ring.
+             * The shadow has two layers:
+             * 1. Outer glow: Purple tint with low opacity for the glow effect
+             * 2. Inner shadow: Subtle shadow for depth
+             *
+             * Border transitions to a purple tint on focus.
+             */
+            isFocused && [
+              'border-purple-400 dark:border-purple-500',
+              'shadow-[0_0_0_3px_rgba(168,85,247,0.1),0_1px_2px_rgba(0,0,0,0.05)]',
+              'dark:shadow-[0_0_0_3px_rgba(168,85,247,0.15),0_1px_2px_rgba(0,0,0,0.1)]',
+            ],
+            /* Smooth transition for all interactive states */
+            'transition-all duration-200 ease-out',
+            /* Disabled state - reduced opacity but not jarring */
+            isDisabled && 'opacity-60 cursor-not-allowed'
+          )}
+        >
+          {/*
+           * Textarea
+           *
+           * Design: Clean, minimal textarea without internal borders.
+           * Blends seamlessly with the container to feel like one unit.
+           * Placeholder uses muted color for visual hierarchy.
+           */}
+          <textarea
+            ref={textareaRef}
+            value={value}
+            onChange={handleChange}
+            onKeyDown={handleKeyDown}
+            onFocus={() => setIsFocused(true)}
+            onBlur={() => setIsFocused(false)}
+            placeholder={placeholder}
+            disabled={isDisabled}
+            aria-label="Message input"
+            aria-describedby={
+              showCharacterCount && isNearLimit ? 'char-count' : undefined
+            }
+            aria-invalid={isOverLimit}
+            rows={1}
+            className={cn(
+              /* Reset default textarea styles completely */
+              'resize-none',
+              'appearance-none',
+              'border-0 border-none',
+              'bg-transparent',
+              'outline-none outline-0 outline-transparent',
+              'shadow-none',
+              'ring-0 ring-transparent ring-offset-0',
+              /* Remove ALL focus indicators - container handles focus styling */
+              'focus:ring-0 focus:ring-transparent focus:ring-offset-0',
+              'focus:outline-none focus:outline-0 focus:outline-transparent',
+              'focus:border-0 focus:border-none focus:border-transparent',
+              'focus:shadow-none',
+              'focus-visible:ring-0 focus-visible:ring-transparent focus-visible:ring-offset-0',
+              'focus-visible:outline-none focus-visible:outline-0 focus-visible:outline-transparent',
+              'focus-visible:border-0 focus-visible:border-none',
+              /* WebKit-specific resets */
+              '[&:focus]:outline-none [&:focus]:ring-0 [&:focus]:border-none',
+              /* Sizing - flex to fill available space */
+              'flex-1',
+              'min-h-[56px]',
+              'max-h-[200px]',
+              /* Padding - comfortable typing area */
+              'py-2',
+              'px-1',
+              /* Typography - clean, readable text */
+              'text-[15px]',
+              'leading-relaxed',
+              'text-gray-900 dark:text-gray-100',
+              /* Placeholder - muted color for visual hierarchy */
+              'placeholder:text-gray-400 dark:placeholder:text-gray-500',
+              /* Scrollbar for overflow content */
+              'overflow-y-auto',
+              /* Disabled state */
+              'disabled:cursor-not-allowed',
+              textareaClassName
+            )}
+            style={{
+              height: `${MIN_TEXTAREA_HEIGHT}px`,
+              outline: 'none',
+              boxShadow: 'none',
+            }}
+          />
+
+          {/*
+           * Send Button
+           *
+           * Design: Circular button with purple gradient background.
+           * Stands out as the primary action without being visually heavy.
+           *
+           * Hover: Subtle scale effect (105%) with soft shadow for
+           * tactile feedback that doesn't feel like a 90s web button.
+           *
+           * Disabled: Clearly visible but not jarring - reduced opacity
+           * and no pointer events.
+           */}
+          <button
+            type="submit"
+            disabled={!canSubmit}
+            aria-label={isLoading ? 'Sending message...' : 'Send message'}
+            className={cn(
+              /* Base sizing - circular button */
+              'shrink-0',
+              'h-10 w-10',
+              'rounded-full',
+              /* Flexbox centering for icon */
+              'flex items-center justify-center',
+              /* Background - purple gradient for brand consistency */
+              'bg-purple-600',
+              'hover:bg-purple-700',
+              /* Text/icon color */
+              'text-white',
+              /*
+               * Hover effect
+               *
+               * Subtle scale (105%) creates tactile feedback.
+               * Soft shadow adds depth without being heavy.
+               * Active state scales down slightly for press feedback.
+               */
+              !isDisabled && [
+                'hover:scale-105',
+                'hover:shadow-md',
+                'hover:shadow-purple-500/25',
+                'active:scale-95',
+              ],
+              /* Smooth transition for all states */
+              'transition-all duration-200 ease-out',
+              /*
+               * Disabled state
+               *
+               * Reduced opacity makes it clearly disabled.
+               * Gray background instead of purple to indicate inactive.
+               * Cursor changes to indicate non-interactive.
+               */
+              !canSubmit && [
+                'opacity-40',
+                'bg-gray-400 dark:bg-gray-600',
+                'cursor-not-allowed',
+                'hover:scale-100',
+                'hover:shadow-none',
+              ],
+              /* Focus visible for keyboard navigation */
+              'focus:outline-none',
+              'focus-visible:ring-2',
+              'focus-visible:ring-purple-500',
+              'focus-visible:ring-offset-2'
+            )}
+          >
+            {isLoading ? (
+              /* Loading spinner when processing */
+              <Spinner
+                size="sm"
+                color="white"
+                spinnerStyle="ring"
+                label="Sending..."
+              />
+            ) : (
+              /* Send icon - slightly rotated for visual interest */
+              <Send className="h-4 w-4" strokeWidth={2} />
+            )}
+          </button>
+        </div>
+
+        {/* Footer row - provider selector, keyboard hints, and character count */}
+        <div className="flex items-center justify-between px-1">
+          {/* Left side: Provider selector and keyboard hints */}
+          <div className="flex items-center gap-3">
+            {/*
+             * Provider Selector - Claude-style model dropdown
+             *
+             * Positioned on the left side of the footer, similar to
+             * how Claude shows the model selector in the input area.
+             */}
+            <ProviderSelector />
+
+            {/*
+             * Keyboard Hints
+             *
+             * Design: Small, subtle text that doesn't compete with the
+             * main input. Uses lighter color and smaller font size.
+             * Hidden on mobile to save space.
+             */}
+            <div
+              className={cn(
+                /* Typography - smaller and lighter */
+                'text-[11px]',
+                'text-gray-400 dark:text-gray-500',
+                /* Hide on small screens - not essential info */
+                'hidden sm:block'
+              )}
+            >
+              <kbd className="rounded bg-gray-100 dark:bg-gray-800 px-1 py-0.5 font-mono text-[10px] text-gray-500 dark:text-gray-400">
+                Enter
+              </kbd>
+              <span className="mx-1">to send</span>
+              <kbd className="rounded bg-gray-100 dark:bg-gray-800 px-1 py-0.5 font-mono text-[10px] text-gray-500 dark:text-gray-400">
+                Shift+Enter
+              </kbd>
+              <span className="ml-1">for new line</span>
+            </div>
+          </div>
+
+          {/*
+           * Character Counter (right side)
+           *
+           * Design: Subtle indicator that appears when approaching
+           * the character limit. Uses smaller text and lighter color
+           * to not distract from the main input.
+           *
+           * Over limit: Turns red to clearly indicate the error state.
+           */}
+          {showCharacterCount && isNearLimit && (
+            <div
+              id="char-count"
+              role="status"
+              aria-live="polite"
+              className={cn(
+                /* Typography - small and subtle */
+                'text-[11px]',
+                /* Color based on limit status */
+                isOverLimit
+                  ? 'text-red-500 dark:text-red-400'
+                  : 'text-gray-400 dark:text-gray-500',
+                /* Smooth fade-in animation */
+                'animate-fade-in'
+              )}
+            >
+              {characterCountText}
+              {isOverLimit && (
+                <span className="ml-1 font-medium">(exceeds limit)</span>
+              )}
+            </div>
+          )}
+        </div>
+      </form>
+    );
+  }
+);
+
+/* Display name for React DevTools */
+ChatInput.displayName = 'ChatInput';
+
+export { ChatInput };

frontend/src/components/chat/chat-message.tsx

@@ -0,0 +1,467 @@
+/**
+ * ChatMessage Component
+ *
+ * A Claude-inspired chat message component that displays messages in a
+ * conversational format with proper alignment:
+ * - User messages: Right-aligned with contained width (bubble style)
+ * - Assistant messages: Left-aligned, full-width, minimal styling
+ *
+ * Design Philosophy (Claude UI Principles):
+ * =========================================
+ * 1. Right-aligned user messages - Creates natural conversation flow
+ * 2. Left-aligned assistant messages - Full-width for content focus
+ * 3. Clean typography - Focus on readability with proper line-height
+ * 4. Minimal chrome - Let the content speak for itself
+ *
+ * @module components/chat/chat-message
+ * @since 1.0.0
+ *
+ * @example
+ * // User message (right-aligned with purple background)
+ * <ChatMessage
+ *   message={{
+ *     id: 'msg-1',
+ *     role: 'user',
+ *     content: 'What is PMV?',
+ *     timestamp: new Date(),
+ *   }}
+ * />
+ *
+ * @example
+ * // Assistant message with streaming cursor (left-aligned, clean)
+ * <ChatMessage
+ *   message={{
+ *     id: 'msg-2',
+ *     role: 'assistant',
+ *     content: 'PMV stands for Predicted Mean Vote...',
+ *     timestamp: new Date(),
+ *     isStreaming: true,
+ *   }}
+ * />
+ *
+ * @example
+ * // Assistant message with sources
+ * <ChatMessage
+ *   message={{
+ *     id: 'msg-3',
+ *     role: 'assistant',
+ *     content: 'The comfort zone is defined as...',
+ *     timestamp: new Date(),
+ *     sources: [{ id: '1', headingPath: 'Chapter 1', page: 5, text: '...' }],
+ *   }}
+ * />
+ */
+
+'use client';
+
+import { forwardRef, type HTMLAttributes, memo } from 'react';
+import { User, Sparkles } from 'lucide-react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import rehypeHighlight from 'rehype-highlight';
+import { cn } from '@/lib/utils';
+import { formatRelativeTime } from '@/lib/utils';
+import type { Message } from '@/types';
+import { MemoizedSourceCitations } from './source-citations';
+import { CodeBlock } from './code-block';
+
+/**
+ * Props for the ChatMessage component.
+ *
+ * Extends standard HTML div attributes for flexibility in styling
+ * and event handling, while requiring the core message data.
+ */
+export interface ChatMessageProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'content'
+> {
+  /**
+   * The message object containing all message data.
+   * Includes role, content, timestamp, and optional sources/streaming state.
+   */
+  message: Message;
+
+  /**
+   * Whether to show the timestamp below the message.
+   * Useful to hide timestamps in rapid streaming scenarios.
+   *
+   * @default true
+   */
+  showTimestamp?: boolean;
+
+  /**
+   * Custom CSS class for the message content area.
+   * Separate from the container className for precise styling.
+   */
+  bubbleClassName?: string;
+}
+
+/**
+ * StreamingCursor Component
+ *
+ * Renders an animated blinking cursor to indicate that the assistant
+ * is still generating content. Uses CSS animation for smooth blinking.
+ * The cursor uses a purple tint to match the brand identity.
+ *
+ * @internal
+ */
+function StreamingCursor(): React.ReactElement {
+  return (
+    <span
+      className="ml-0.5 inline-block h-4 w-2 animate-[cursor-blink_1s_ease-in-out_infinite] bg-[var(--color-primary-500)] align-middle"
+      aria-hidden="true"
+    >
+      <style>{`
+        @keyframes cursor-blink {
+          0%, 50% { opacity: 1; }
+          51%, 100% { opacity: 0; }
+        }
+      `}</style>
+    </span>
+  );
+}
+
+/**
+ * MessageAvatar Component
+ *
+ * Renders the avatar icon for either user or assistant messages.
+ * Uses a minimal design approach:
+ * - User: Small purple circle with user icon (maintains brand identity)
+ * - Assistant: Simple sparkle icon without circle background (minimal chrome)
+ *
+ * Avatars are smaller (h-6 w-6) and positioned at the top-left of messages
+ * for a cleaner, more document-like reading experience.
+ *
+ * @param role - The role of the message sender ('user' or 'assistant')
+ * @returns Avatar icon element
+ *
+ * @internal
+ */
+function MessageAvatar({
+  role,
+}: {
+  role: Message['role'];
+}): React.ReactElement {
+  const isUser = role === 'user';
+
+  return (
+    <div
+      className={cn(
+        /* Base avatar styles - smaller for minimal design */
+        'flex items-center justify-center shrink-0',
+        /* Size: smaller h-6 w-6 for subtlety */
+        'h-6 w-6',
+        /* User gets a purple circle background; assistant has no background */
+        isUser
+          ? 'rounded-full bg-[var(--color-primary-500)]'
+          : '' /* No background for assistant - minimal chrome */
+      )}
+      aria-hidden="true"
+    >
+      {isUser ? (
+        <User className="h-3.5 w-3.5 text-white" strokeWidth={2.5} />
+      ) : (
+        <Sparkles
+          className="h-5 w-5 text-[var(--color-primary-500)]"
+          strokeWidth={2}
+        />
+      )}
+    </div>
+  );
+}
+
+/**
+ * MessageContent Component
+ *
+ * Renders the message text content using React Markdown with enhanced
+ * typography for better readability. Supports GFM (tables, lists, etc.)
+ * and syntax highlighting.
+ *
+ * Typography enhancements:
+ * - Slightly larger prose size for comfortable reading
+ * - Proper line-height for long-form content
+ * - Purple-colored links for brand consistency
+ *
+ * @param content - The text content of the message
+ * @param isStreaming - Whether the message is still being streamed
+ * @param isUser - Whether this is a user message (affects link styling)
+ * @returns Formatted message content element
+ *
+ * @internal
+ */
+function MessageContent({
+  content,
+  isStreaming = false,
+  isUser = false,
+}: {
+  content: string;
+  isStreaming?: boolean;
+  isUser?: boolean;
+}): React.ReactElement {
+  return (
+    <div
+      className={cn(
+        'relative',
+        /* Enhanced prose typography - slightly larger for readability */
+        'prose prose-base max-w-none',
+        /* User messages: light text on purple; Assistant: dark prose with invert */
+        isUser ? 'prose-invert' : 'dark:prose-invert',
+        /* Proper line-height for long-form content */
+        'leading-relaxed',
+        /* Color overrides to inherit from parent (important for user white text) */
+        'prose-p:text-[inherit]',
+        'prose-headings:text-[inherit]',
+        'prose-strong:text-[inherit]',
+        'prose-ul:text-[inherit]',
+        'prose-ol:text-[inherit]',
+        'prose-code:text-[inherit]',
+        /* Spacing adjustments */
+        'prose-p:my-2',
+        'prose-headings:my-3',
+        'prose-ul:my-2',
+        'prose-ol:my-2',
+        'prose-li:my-0.5',
+        /* Break words */
+        'break-words'
+      )}
+    >
+      <ReactMarkdown
+        remarkPlugins={[remarkGfm]}
+        rehypePlugins={[rehypeHighlight]}
+        components={{
+          // Use our custom CodeBlock component for code blocks
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+          code: ({ node, inline, className, children, ...props }: any) => {
+            return (
+              <CodeBlock
+                inline={inline}
+                className={className}
+                {...props}
+              >
+                {children}
+              </CodeBlock>
+            );
+          },
+          // Custom styling for links
+          // User messages: light underlined links on purple background
+          // Assistant messages: purple links for brand consistency
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+          a: ({ node, className, children, ...props }: any) => (
+            <a
+              className={cn(
+                isUser
+                  ? /* User: light links that stand out on purple background */
+                    'text-white/90 underline underline-offset-2 hover:text-white font-medium'
+                  : /* Assistant: purple links for brand consistency */
+                    'text-[var(--color-primary-600)] dark:text-[var(--color-primary-400)] hover:underline font-medium',
+                className
+              )}
+              target="_blank"
+              rel="noopener noreferrer"
+              {...props}
+            >
+              {children}
+            </a>
+          ),
+        }}
+      >
+        {content}
+      </ReactMarkdown>
+
+      {/* Show purple-tinted blinking cursor when message is still streaming */}
+      {isStreaming && <StreamingCursor />}
+    </div>
+  );
+}
+
+/**
+ * ChatMessage Component
+ *
+ * A Claude-inspired chat message component with proper message alignment:
+ * - User messages: Right-aligned with contained width
+ * - Assistant messages: Left-aligned, full-width
+ *
+ * @remarks
+ * ## Visual Design (Claude-Inspired)
+ * - **User messages**: Right-aligned with purple gradient background,
+ *   max-width constrained for natural conversation flow. No avatar
+ *   shown for cleaner appearance.
+ * - **Assistant messages**: Left-aligned, full-width with avatar icon.
+ *   Clean text directly on the page background.
+ *
+ * ## Layout (Claude-Style)
+ * - User messages right-aligned with max-width (80%)
+ * - Assistant messages left-aligned, full-width
+ * - Smaller, more subtle avatars for assistant only
+ * - No bubble borders for assistant messages
+ *
+ * ## Accessibility Features
+ * - Uses `role="article"` for semantic grouping of message content
+ * - Includes `aria-label` describing the message author and time
+ * - Avatars are hidden from screen readers (decorative)
+ * - Streaming cursor is hidden from screen readers
+ *
+ * ## Streaming Support
+ * - When `isStreaming` is true on the message, displays an animated
+ *   purple-tinted blinking cursor at the end of the content
+ * - Useful for real-time SSE/WebSocket message updates
+ *
+ * ## Animation
+ * - Messages fade in and slide up on initial render
+ * - Uses CSS animations that respect `prefers-reduced-motion`
+ *
+ * @param props - ChatMessage component props
+ * @returns React element containing the styled chat message
+ *
+ * @see {@link ChatMessageProps} for full prop documentation
+ * @see {@link Message} for the message data structure
+ */
+const ChatMessage = forwardRef<HTMLDivElement, ChatMessageProps>(
+  (
+    { message, showTimestamp = true, bubbleClassName, className, ...props },
+    ref
+  ) => {
+    const isUser = message.role === 'user';
+
+    /**
+     * Format the timestamp for screen reader accessibility.
+     * Provides context like "User message from 2 minutes ago"
+     */
+    const timeLabel = formatRelativeTime(message.timestamp);
+    const ariaLabel = `${isUser ? 'Your' : 'Assistant'} message from ${timeLabel}`;
+
+    return (
+      <article
+        ref={ref}
+        role="article"
+        aria-label={ariaLabel}
+        className={cn(
+          /* Full-width container */
+          'w-full',
+          /* Animation on appearance */
+          'animate-slide-up',
+          /*
+           * User messages: flex container to enable right-alignment
+           * Assistant messages: normal flow (left-aligned)
+           */
+          isUser ? 'flex justify-end' : '',
+          className
+        )}
+        {...props}
+      >
+        {/*
+         * Message container with conditional styling:
+         * - User: Right-aligned purple bubble with constrained width
+         * - Assistant: Left-aligned, full-width, minimal styling
+         */}
+        <div
+          className={cn(
+            /* Base padding and layout */
+            'px-4 py-3 rounded-2xl',
+            /* Role-based width and styling */
+            isUser
+              ? [
+                /* User: Constrained width, right-aligned bubble */
+                'max-w-[85%] sm:max-w-[75%]',
+                /* Purple gradient background for user messages */
+                'bg-gradient-to-br from-[var(--color-primary-600)] to-[var(--color-primary-700)]',
+                'text-white',
+                /* Subtle shadow for depth */
+                'shadow-sm',
+              ]
+              : [
+                /* Assistant: Full-width, no background */
+                'w-full',
+                'bg-transparent',
+                'text-[var(--foreground)]',
+              ],
+            bubbleClassName
+          )}
+        >
+          {/* Flex container for avatar and content */}
+          <div className={cn(
+            'flex gap-3 items-start',
+            /* User messages: no avatar, just content */
+            isUser && 'justify-end'
+          )}>
+            {/* Avatar - only show for assistant messages */}
+            {!isUser && <MessageAvatar role={message.role} />}
+
+            {/* Message content container */}
+            <div className={cn(
+              'min-w-0',
+              /* User messages don't need flex-1 since they're right-aligned */
+              !isUser && 'flex-1'
+            )}>
+              {/* Message text content */}
+              <div
+                className={cn(
+                  /* Text styling - inherit color from parent */
+                  'text-base leading-relaxed'
+                )}
+              >
+                <MessageContent
+                  content={message.content}
+                  isStreaming={message.isStreaming}
+                  isUser={isUser}
+                />
+              </div>
+
+              {/* Source Citations - Only show for completed assistant messages with sources */}
+              {message.role === 'assistant' &&
+                message.sources &&
+                message.sources.length > 0 &&
+                !message.isStreaming && (
+                  <div
+                    className="mt-4"
+                    aria-label={`${message.sources.length} source${message.sources.length === 1 ? '' : 's'} referenced in this response`}
+                  >
+                    <MemoizedSourceCitations sources={message.sources} />
+                  </div>
+                )}
+
+              {/* Timestamp - shown below content */}
+              {showTimestamp && (
+                <time
+                  dateTime={message.timestamp.toISOString()}
+                  className={cn(
+                    /* Timestamp styling */
+                    'block mt-2',
+                    'text-xs',
+                    /* User: lighter text on purple; Assistant: muted */
+                    isUser
+                      ? 'text-white/70'
+                      : 'text-[var(--foreground-muted)]'
+                  )}
+                >
+                  {timeLabel}
+                </time>
+              )}
+            </div>
+          </div>
+        </div>
+      </article>
+    );
+  }
+);
+
+/* Display name for React DevTools */
+ChatMessage.displayName = 'ChatMessage';
+
+/**
+ * Memoized ChatMessage for performance optimization.
+ *
+ * Since chat messages are typically rendered in a list and don't change
+ * frequently (except during streaming), memoization prevents unnecessary
+ * re-renders when sibling messages update.
+ *
+ * The component re-renders when:
+ * - message.id changes (new message)
+ * - message.content changes (streaming updates)
+ * - message.isStreaming changes (streaming state)
+ * - showTimestamp or className props change
+ */
+const MemoizedChatMessage = memo(ChatMessage);
+
+/* Export both versions - use Memoized for lists, regular for single messages */
+export { ChatMessage, MemoizedChatMessage };

frontend/src/components/chat/code-block.tsx

@@ -0,0 +1,94 @@
+'use client';
+
+import { Check, Copy, Terminal } from 'lucide-react';
+import { memo, useRef, useState, useCallback } from 'react';
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+
+interface CodeBlockProps extends React.HTMLAttributes<HTMLElement> {
+    inline?: boolean;
+    className?: string;
+    children?: React.ReactNode;
+}
+
+/**
+ * CodeBlock Component
+ *
+ * Renders a code block with syntax highlighting (via rehype-highlight classes),
+ * a language label, and a copy-to-clipboard button.
+ * Designed to work as a custom component for react-markdown.
+ */
+export const CodeBlock = memo(
+    ({ inline, className, children, ...props }: CodeBlockProps) => {
+        // specific ref to the code element for copying
+        const codeRef = useRef<HTMLElement>(null);
+        const [isCopied, setIsCopied] = useState(false);
+
+        // Extract language from className (format: "language-xyz")
+        // react-markdown (via rehype-highlight) passes "language-xyz" in className
+        const match = /language-(\w+)/.exec(className || '');
+        const language = match ? match[1] : '';
+
+        // Handle copy functionality
+        const handleCopy = useCallback(() => {
+            if (codeRef.current && codeRef.current.textContent) {
+                navigator.clipboard.writeText(codeRef.current.textContent);
+                setIsCopied(true);
+                setTimeout(() => setIsCopied(false), 2000);
+            }
+        }, []);
+
+        // If inline code, render simple styled code tag
+        if (inline) {
+            return (
+                <code
+                    className={cn(
+                        'bg-[var(--background-secondary)]',
+                        'px-1.5 py-0.5 rounded-md',
+                        'text-sm font-mono text-[var(--color-primary-700)] dark:text-[var(--color-primary-300)]',
+                        className
+                    )}
+                    {...props}
+                >
+                    {children}
+                </code>
+            );
+        }
+
+        return (
+            <div className="group relative my-4 overflow-hidden rounded-xl border border-[var(--border)] bg-[#1e1e1e] shadow-md dark:border-[var(--border-ui)]">
+                {/* Header with language and actions */}
+                <div className="flex items-center justify-between border-b border-white/10 bg-[#2d2d2d] px-4 py-2 text-xs text-gray-400">
+                    <div className="flex items-center gap-2">
+                        <Terminal className="h-4 w-4" />
+                        <span className="font-medium uppercase">{language || 'text'}</span>
+                    </div>
+                    <Button
+                        variant="ghost"
+                        size="icon"
+                        className="h-6 w-6 text-gray-400 hover:bg-white/10 hover:text-white"
+                        onClick={handleCopy}
+                        aria-label="Copy code"
+                    >
+                        {isCopied ? (
+                            <Check className="h-3.5 w-3.5 text-green-400" />
+                        ) : (
+                            <Copy className="h-3.5 w-3.5" />
+                        )}
+                    </Button>
+                </div>
+
+                {/* Code content */}
+                <div className="overflow-x-auto p-4">
+                    <pre {...props} className={cn('text-sm font-mono leading-relaxed', className)}>
+                        <code ref={codeRef} className={className}>
+                            {children}
+                        </code>
+                    </pre>
+                </div>
+            </div>
+        );
+    }
+);
+
+CodeBlock.displayName = 'CodeBlock';

frontend/src/components/chat/empty-state.tsx

@@ -0,0 +1,658 @@
+/**
+ * EmptyState Component - Claude-Style Minimal Design
+ *
+ * A welcoming empty state component displayed when the chat has no messages.
+ * Provides a friendly introduction to the RAG chatbot with example questions
+ * that users can click to quickly start a conversation.
+ *
+ * Features a premium custom SVG illustration representing thermal comfort concepts
+ * with subtle animations that respect user motion preferences. The design follows
+ * Claude's minimal aesthetic - content flows naturally on the page background
+ * without visible card boundaries or container styling.
+ *
+ * ## Design Philosophy
+ * - No glassmorphism or card containers
+ * - Content floats naturally on the page background
+ * - Suggestion buttons are lightweight and feel native to the page
+ * - Clean, distraction-free interface that focuses on content
+ *
+ * ## Purple Theme Colors
+ * The component uses the following purple color palette via CSS custom properties:
+ * - purple-100 (#f3e8ff): Light backgrounds, window fills
+ * - purple-200 (#e9d5ff): Secondary elements, doors
+ * - purple-300 (#d8b4fe): Decorative elements, medium accents
+ * - purple-400 (#c084fc): Icons, gradient starts
+ * - purple-500 (#a855f7): Primary accent color
+ * - purple-600 (#9333ea): Gradient ends, active states
+ * - purple-700 (#7c3aed): Strokes, borders
+ *
+ * @module components/chat/empty-state
+ * @since 1.0.0
+ *
+ * @example
+ * // Basic usage in ChatContainer
+ * <EmptyState onExampleClick={(question) => handleQuestionClick(question)} />
+ *
+ * @example
+ * // With custom styling
+ * <EmptyState
+ *   onExampleClick={handleClick}
+ *   className="my-8"
+ * />
+ */
+
+'use client';
+
+import { memo, useCallback, type HTMLAttributes } from 'react';
+import { MessageSquare } from 'lucide-react';
+import { cn } from '@/lib/utils';
+
+/**
+ * ThermalComfortIllustration Component - Purple Theme
+ *
+ * A premium, custom SVG illustration representing thermal comfort concepts.
+ * Features a stylized building with temperature waves and comfort indicators,
+ * all rendered with a cohesive purple color scheme.
+ *
+ * ## Design Elements (Purple Theme)
+ * - Central building silhouette with purple-400 to purple-600 gradient
+ * - Thermometer element with purple-300 to purple-600 gradient fill
+ * - Flowing wave lines with purple-300 to purple-400 gradient
+ * - Circular comfort zone with purple-200 to purple-400 radial gradient
+ * - Building windows in purple-100, door in purple-200
+ * - Strokes in purple-700 for definition
+ * - Comfort indicator dots in purple-300, purple-400, purple-500
+ *
+ * ## Animation Features
+ * - Gentle floating animation on the main container
+ * - Subtle pulse effect on the comfort zone circle
+ * - Wave lines with staggered opacity animations
+ * - All animations respect `prefers-reduced-motion`
+ *
+ * @param className - Optional CSS classes to apply
+ * @returns SVG element with thermal comfort illustration in purple theme
+ *
+ * @internal
+ */
+function ThermalComfortIllustration({
+  className,
+}: {
+  className?: string;
+}): React.ReactElement {
+  return (
+    <svg
+      viewBox="0 0 100 100"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className={cn(
+        /* Base size for the illustration */
+        'h-20 w-20',
+        /* Float animation - creates gentle vertical movement
+           Uses motion-safe: prefix to respect prefers-reduced-motion */
+        'motion-safe:animate-[thermalFloat_4s_ease-in-out_infinite]',
+        className
+      )}
+      /* Decorative illustration, hidden from screen readers */
+      aria-hidden="true"
+      role="img"
+    >
+      {/* ============================================
+          SVG Definitions: Purple Gradients and Filters
+          All gradients use purple color scheme for cohesive design
+          ============================================ */}
+      <defs>
+        {/*
+          Building Gradient - Purple Tones
+          Creates depth on the main building structure
+          Uses purple-400 (#c084fc) to purple-600 (#9333ea)
+        */}
+        <linearGradient
+          id="buildingGradient"
+          x1="0%"
+          y1="0%"
+          x2="100%"
+          y2="100%"
+        >
+          {/* Start: Medium purple - creates highlight on top-left */}
+          <stop offset="0%" stopColor="var(--color-primary-400)" />
+          {/* End: Rich purple - creates shadow on bottom-right */}
+          <stop offset="100%" stopColor="var(--color-primary-600)" />
+        </linearGradient>
+
+        {/*
+          Comfort Zone Gradient - Soft Purple Radial
+          Creates a glowing orb effect behind the illustration
+          Uses purple-200 (#e9d5ff) to purple-400 (#c084fc)
+        */}
+        <radialGradient
+          id="comfortZoneGradient"
+          cx="50%"
+          cy="50%"
+          r="50%"
+          fx="30%"  /* Offset focal point for 3D effect */
+          fy="30%"
+        >
+          {/* Center: Soft purple with high opacity */}
+          <stop offset="0%" stopColor="var(--color-primary-200)" stopOpacity="0.8" />
+          {/* Middle: Medium-light purple, fading */}
+          <stop offset="70%" stopColor="var(--color-primary-400)" stopOpacity="0.4" />
+          {/* Edge: Medium purple, nearly transparent */}
+          <stop offset="100%" stopColor="var(--color-primary-400)" stopOpacity="0.1" />
+        </radialGradient>
+
+        {/*
+          Thermometer Fill Gradient - Purple Temperature Indicator
+          Vertical gradient simulating mercury/temperature level
+          Uses purple-300 (#d8b4fe) to purple-600 (#9333ea)
+        */}
+        <linearGradient
+          id="thermoGradient"
+          x1="0%"
+          y1="100%"  /* Start from bottom */
+          x2="0%"
+          y2="0%"    /* End at top */
+        >
+          {/* Bottom: Lighter purple - cooler indication */}
+          <stop offset="0%" stopColor="var(--color-primary-300)" />
+          {/* Middle: Main purple - neutral zone */}
+          <stop offset="50%" stopColor="var(--color-primary-600)" />
+          {/* Top: Rich purple - warmer indication */}
+          <stop offset="100%" stopColor="var(--color-primary-600)" />
+        </linearGradient>
+
+        {/*
+          Wave Gradient - Air Flow Representation
+          Horizontal gradient for flowing wave lines
+          Uses purple-300 (#d8b4fe) to purple-400 (#c084fc)
+        */}
+        <linearGradient
+          id="waveGradient"
+          x1="0%"
+          y1="0%"
+          x2="100%"
+          y2="0%"
+        >
+          {/* Start: Faded purple - creates trailing edge effect */}
+          <stop offset="0%" stopColor="var(--color-primary-300)" stopOpacity="0.2" />
+          {/* Center: Visible purple - wave peak */}
+          <stop offset="50%" stopColor="var(--color-primary-400)" stopOpacity="0.6" />
+          {/* End: Faded purple - creates leading edge effect */}
+          <stop offset="100%" stopColor="var(--color-primary-300)" stopOpacity="0.2" />
+        </linearGradient>
+      </defs>
+
+      {/* ============================================
+          Background: Comfort Zone Circle
+          A soft radial purple element suggesting optimal thermal conditions
+          Animates with subtle pulse for organic feel
+          ============================================ */}
+      <circle
+        cx="50"
+        cy="50"
+        r="42"
+        fill="url(#comfortZoneGradient)"
+        /* Pulse animation: creates breathing effect
+           3s duration for calm, professional feel */
+        className="motion-safe:animate-[thermalPulse_3s_ease-in-out_infinite]"
+      />
+
+      {/* ============================================
+          Building Silhouette
+          Central element representing the built environment
+          Uses purple gradient with purple-700 strokes for definition
+          Features windows (purple-100) and door (purple-200)
+          ============================================ */}
+      <g transform="translate(25, 28)">
+        {/* Main building body - pitched roof style
+            Filled with purple gradient for depth */}
+        <path
+          d="M5 45 L5 18 L25 8 L45 18 L45 45 Z"
+          fill="url(#buildingGradient)"
+          /* Purple-700 stroke for crisp definition */
+          stroke="var(--color-primary-700)"
+          strokeWidth="1"
+          strokeLinejoin="round"
+        />
+
+        {/* Roof accent line - emphasizes the pitched roof
+            Thicker stroke for visual hierarchy */}
+        <path
+          d="M5 18 L25 8 L45 18"
+          fill="none"
+          stroke="var(--color-primary-700)"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+
+        {/* Windows - grid pattern suggesting occupancy
+            Uses purple-100 for bright, welcoming appearance */}
+        {/* Left column of windows */}
+        <rect x="10" y="22" width="6" height="6" rx="1" fill="var(--color-primary-100)" opacity="0.9" />
+        <rect x="10" y="32" width="6" height="6" rx="1" fill="var(--color-primary-100)" opacity="0.9" />
+
+        {/* Right column of windows */}
+        <rect x="34" y="22" width="6" height="6" rx="1" fill="var(--color-primary-100)" opacity="0.9" />
+        <rect x="34" y="32" width="6" height="6" rx="1" fill="var(--color-primary-100)" opacity="0.9" />
+
+        {/* Door - central entrance
+            Uses purple-200 for subtle differentiation from windows */}
+        <rect x="20" y="32" width="10" height="13" rx="1" fill="var(--color-primary-200)" />
+        {/* Door handle - small detail in purple-600 */}
+        <circle cx="27" cy="39" r="1" fill="var(--color-primary-600)" />
+      </g>
+
+      {/* ============================================
+          Thermometer Element
+          Positioned to the right, indicating temperature measurement
+          Uses purple theme: outline in purple-100, fill with purple gradient
+          ============================================ */}
+      <g transform="translate(72, 25)">
+        {/* Thermometer outline - bulb-style design
+            Light purple-100 background, purple-400 border */}
+        <path
+          d="M6 0 C2.7 0 0 2.7 0 6 L0 35 C-2 37 -3 40 -3 43 C-3 49 2 54 8 54 C14 54 19 49 19 43 C19 40 18 37 16 35 L16 6 C16 2.7 13.3 0 10 0 Z"
+          fill="var(--color-primary-100)"
+          stroke="var(--color-primary-400)"
+          strokeWidth="1.5"
+        />
+
+        {/* Thermometer fill - animated warmth level
+            Purple gradient creates temperature indication
+            Pulses to suggest active measurement */}
+        <path
+          d="M6 38 L6 10 C6 8 7 7 8 7 C9 7 10 8 10 10 L10 38 C12 39 14 41 14 43 C14 47 11 50 8 50 C5 50 2 47 2 43 C2 41 4 39 6 38 Z"
+          fill="url(#thermoGradient)"
+          /* Pulse animation with 0.5s delay for staggered effect */
+          className="motion-safe:animate-[thermalPulse_3s_ease-in-out_infinite_0.5s]"
+        />
+
+        {/* Temperature measurement marks - tick marks on thermometer
+            Purple-400 for subtle visibility */}
+        <line x1="12" y1="15" x2="14" y2="15" stroke="var(--color-primary-400)" strokeWidth="1" />
+        <line x1="12" y1="22" x2="14" y2="22" stroke="var(--color-primary-400)" strokeWidth="1" />
+        <line x1="12" y1="29" x2="14" y2="29" stroke="var(--color-primary-400)" strokeWidth="1" />
+      </g>
+
+      {/* ============================================
+          Wave Lines - Air Flow Representation
+          Animated purple curves suggesting thermal circulation
+          Staggered timing creates flowing, organic effect
+          ============================================ */}
+      {/* Top wave - highest opacity for visual hierarchy */}
+      <g className="motion-safe:animate-[thermalWave_2s_ease-in-out_infinite]">
+        <path
+          d="M12 30 Q22 26 32 30 Q42 34 52 30"
+          fill="none"
+          stroke="url(#waveGradient)"
+          strokeWidth="2"
+          strokeLinecap="round"
+          opacity="0.7"
+        />
+      </g>
+
+      {/* Middle wave - 0.3s delay for staggered motion */}
+      <g className="motion-safe:animate-[thermalWave_2s_ease-in-out_infinite_0.3s]">
+        <path
+          d="M8 42 Q18 38 28 42 Q38 46 48 42"
+          fill="none"
+          stroke="url(#waveGradient)"
+          strokeWidth="2"
+          strokeLinecap="round"
+          opacity="0.5"
+        />
+      </g>
+
+      {/* Bottom wave - 0.6s delay completes the flowing sequence */}
+      <g className="motion-safe:animate-[thermalWave_2s_ease-in-out_infinite_0.6s]">
+        <path
+          d="M15 55 Q25 51 35 55 Q45 59 55 55"
+          fill="none"
+          stroke="url(#waveGradient)"
+          strokeWidth="2"
+          strokeLinecap="round"
+          opacity="0.6"
+        />
+      </g>
+
+      {/* ============================================
+          Comfort Indicator Dots - Purple Accents
+          Small circular elements suggesting optimal conditions
+          Each dot uses different purple shade for visual interest:
+          - Top-left: purple-400 (medium purple)
+          - Bottom-right: purple-300 (lighter purple)
+          - Bottom-left: purple-500 (main accent purple)
+          ============================================ */}
+      {/* Top-left indicator dot - purple-400 */}
+      <circle
+        cx="18"
+        cy="22"
+        r="2"
+        fill="var(--color-primary-400)"
+        opacity="0.6"
+        /* Faster pulse with 0.2s delay */
+        className="motion-safe:animate-[thermalPulse_2s_ease-in-out_infinite_0.2s]"
+      />
+      {/* Bottom-right indicator dot - purple-300 (lighter) */}
+      <circle
+        cx="82"
+        cy="72"
+        r="2.5"
+        fill="var(--color-primary-300)"
+        opacity="0.5"
+        /* Medium delay for staggered effect */
+        className="motion-safe:animate-[thermalPulse_2s_ease-in-out_infinite_0.8s]"
+      />
+      {/* Bottom-left indicator dot - purple-500 (main accent) */}
+      <circle
+        cx="15"
+        cy="75"
+        r="1.5"
+        fill="var(--color-primary-500)"
+        opacity="0.4"
+        /* Longest delay completes the sequence */
+        className="motion-safe:animate-[thermalPulse_2s_ease-in-out_infinite_1.2s]"
+      />
+    </svg>
+  );
+}
+
+/**
+ * Example questions displayed in the empty state.
+ *
+ * These are pre-defined questions that demonstrate the types of queries
+ * the RAG chatbot can answer about pythermalcomfort. Limited to 2 questions
+ * for a cleaner, less overwhelming interface:
+ * 1. PMV model - core thermal comfort calculation
+ * 2. Adaptive comfort - alternative model for naturally ventilated spaces
+ *
+ * @internal
+ */
+const EXAMPLE_QUESTIONS = [
+  'What is the PMV model and how do I calculate it?',
+  'How do I use the adaptive comfort model in pythermalcomfort?',
+] as const;
+
+/**
+ * Props for the EmptyState component.
+ *
+ * Extends standard HTML div attributes for flexibility in styling
+ * and event handling. The onClick prop is omitted to prevent conflicts
+ * with the internal example click handling.
+ */
+export interface EmptyStateProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onClick'
+> {
+  /**
+   * Callback fired when a user clicks an example question.
+   * The clicked question text is passed as the argument.
+   * This should typically populate the chat input with the question.
+   *
+   * @param question - The text of the clicked example question
+   */
+  onExampleClick: (question: string) => void;
+}
+
+/**
+ * ExampleQuestionButton Component - Claude-Style Minimal Design
+ *
+ * An individual example question rendered as a clickable button.
+ * Uses a lightweight, text-focused design that feels native to the page
+ * without heavy container styling.
+ *
+ * ## Design Philosophy
+ * - Minimal visual weight - no heavy borders or shadows
+ * - Subtle hover state using background color change
+ * - Feels like a natural page element, not a contained widget
+ * - Purple icon accent maintains brand consistency
+ *
+ * @param question - The question text to display
+ * @param onClick - Callback fired when the button is clicked
+ *
+ * @internal
+ */
+function ExampleQuestionButton({
+  question,
+  onClick,
+}: {
+  question: string;
+  onClick: () => void;
+}): React.ReactElement {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={cn(
+        /* Base button styles - full width layout */
+        'w-full text-left',
+        'px-4 py-3',
+        /* Minimal styling - transparent background by default */
+        'bg-transparent',
+        /* Very subtle border for definition without heaviness */
+        'border border-transparent',
+        /* Rounded corners for softer feel */
+        'rounded-lg',
+        /* Text styling - small size for secondary content */
+        'text-sm text-[var(--foreground)]',
+        /* Flexbox aligns icon and text horizontally */
+        'flex items-start gap-3',
+        /* Hover state - subtle background highlight
+           No border or shadow changes for minimal effect */
+        'hover:bg-[var(--foreground)]/5',
+        /* Smooth transition */
+        'transition-colors duration-150',
+        /* Focus state for keyboard accessibility
+           Ring color uses focus variable (purple-themed) */
+        'focus:outline-none',
+        'focus-visible:ring-2',
+        'focus-visible:ring-[var(--border-focus)]',
+        'focus-visible:ring-offset-2',
+        /* Cursor indicates interactivity */
+        'cursor-pointer'
+      )}
+    >
+      {/* Question mark icon - purple-500 for visual accent
+          Aligned to top of text for multi-line questions */}
+      <MessageSquare
+        className={cn(
+          'mt-0.5 h-4 w-4 shrink-0',
+          /* Purple-500 (#a855f7) - main accent color */
+          'text-[var(--color-primary-500)]'
+        )}
+        strokeWidth={2}
+        /* Icon is decorative, text provides meaning */
+        aria-hidden="true"
+      />
+      {/* Question text - inherits foreground color */}
+      <span>{question}</span>
+    </button>
+  );
+}
+
+/**
+ * EmptyState Component - Claude-Style Minimal Design
+ *
+ * Displays a welcoming interface when the chat has no messages. This component
+ * serves as the initial state of the chat, providing users with context about
+ * what the chatbot can do and offering quick-start example questions.
+ *
+ * @remarks
+ * ## Visual Design - Claude-Style Minimal
+ *
+ * The component follows Claude's minimal design philosophy:
+ * - No glassmorphism, card containers, or visible boundaries
+ * - Content flows naturally on the page background
+ * - Lightweight suggestion buttons without heavy styling
+ * - Clean typography with proper hierarchy
+ * - Focus on content, not decoration
+ *
+ * ## Thermal Comfort Illustration (Purple Theme)
+ *
+ * The illustration (`ThermalComfortIllustration`) includes:
+ * - Stylized building with purple-400 to purple-600 gradient
+ * - Thermometer with purple-300 to purple-600 gradient fill
+ * - Wave lines in purple-300 to purple-400 gradient
+ * - Comfort zone circle with purple-200 to purple-400 radial gradient
+ * - Building windows in purple-100, door in purple-200
+ * - Strokes in purple-700 for definition
+ * - Comfort dots in purple-300, purple-400, purple-500
+ * - Subtle animations (float, pulse, wave) respecting `prefers-reduced-motion`
+ *
+ * ## Interaction Pattern
+ *
+ * When users click an example question:
+ * 1. The `onExampleClick` callback is fired with the question text
+ * 2. The parent component (ChatContainer) should populate the input
+ * 3. Optionally, the parent can auto-submit the question
+ *
+ * ## Accessibility
+ *
+ * - All example questions are focusable buttons
+ * - Focus states are clearly visible with purple ring
+ * - Illustration is hidden from screen readers (decorative, aria-hidden="true")
+ * - Uses semantic heading hierarchy
+ * - Animations respect `prefers-reduced-motion` via `motion-safe:` prefix
+ *
+ * ## Animation
+ *
+ * The component uses the slide-up animation for a smooth entrance,
+ * creating a polished feel when the chat interface first loads.
+ * The illustration adds additional subtle animations:
+ * - `thermalFloat`: Gentle vertical float (4s cycle)
+ * - `thermalPulse`: Soft breathing effect (2-3s cycles)
+ * - `thermalWave`: Horizontal wave motion (2s cycles with stagger)
+ *
+ * @param props - EmptyState component props
+ * @returns React element containing the welcome interface
+ *
+ * @see {@link EmptyStateProps} for full prop documentation
+ * @see {@link ThermalComfortIllustration} for illustration details
+ */
+function EmptyStateComponent({
+  onExampleClick,
+  className,
+  ...props
+}: EmptyStateProps): React.ReactElement {
+  /**
+   * Create memoized click handlers for each example question.
+   * This prevents creating new function references on each render,
+   * optimizing performance when the component re-renders.
+   */
+  const handleExampleClick = useCallback(
+    (question: string) => {
+      onExampleClick(question);
+    },
+    [onExampleClick]
+  );
+
+  return (
+    <div
+      className={cn(
+        /* Full width container with max width for readability */
+        'mx-auto w-full max-w-2xl',
+        /* Comfortable spacing - content flows on page background */
+        'px-4 py-8',
+        /* Smooth entrance animation */
+        'animate-slide-up',
+        className
+      )}
+      {...props}
+    >
+      {/* Content flows directly on page background - no card container
+          Claude-style minimal design with natural spacing */}
+
+      {/* Illustration section - Premium thermal comfort SVG
+          Centered with proper vertical spacing */}
+      <div className="mb-6 flex justify-center">
+        <div
+          className={cn(
+            /* Container provides consistent sizing for illustration */
+            'h-24 w-24',
+            /* Flex centering ensures illustration is perfectly positioned */
+            'flex items-center justify-center'
+          )}
+        >
+          {/* Purple-themed thermal comfort illustration */}
+          <ThermalComfortIllustration />
+        </div>
+      </div>
+
+      {/* Title section - Clear hierarchy with heading and description */}
+      <div className="mb-8 text-center">
+        {/* Main heading - bold and prominent */}
+        <h2
+          className={cn(
+            /* Large, bold text for primary heading */
+            'text-2xl font-bold',
+            /* Uses foreground color for maximum contrast */
+            'text-[var(--foreground)]',
+            /* Tight spacing before description */
+            'mb-2'
+          )}
+        >
+          Ask about thermal comfort and pythermalcomfort
+        </h2>
+        {/* Descriptive subtitle - provides context */}
+        <p
+          className={cn(
+            /* Secondary color for less emphasis than heading */
+            'text-[var(--foreground-secondary)]',
+            /* Smaller text size with relaxed line height for readability */
+            'text-sm leading-relaxed',
+            /* Constrained width prevents overly long lines */
+            'mx-auto max-w-md'
+          )}
+        >
+          Get answers about thermal comfort models, concepts, standards and the
+          pythermalcomfort library. Your questions are answered using
+          scientific sources and official documentations.
+        </p>
+      </div>
+
+      {/* Example questions section - Quick-start options */}
+      <div className="space-y-3">
+        {/* Section label - small caps style */}
+        <p
+          className={cn(
+            /* Small, uppercase text for label styling */
+            'text-xs font-medium tracking-wide uppercase',
+            /* Muted color to not compete with questions */
+            'text-[var(--foreground-muted)]',
+            /* Spacing positions label above grid */
+            'mb-3 px-1'
+          )}
+        >
+          Try asking
+        </p>
+
+        {/* Questions grid - responsive 1 or 2 column layout
+            Single column on mobile, two columns on larger screens */}
+        <div className="grid gap-3 sm:grid-cols-2">
+          {EXAMPLE_QUESTIONS.map((question) => (
+            <ExampleQuestionButton
+              key={question}
+              question={question}
+              onClick={() => handleExampleClick(question)}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/* Display name for React DevTools debugging */
+EmptyStateComponent.displayName = 'EmptyState';
+
+/**
+ * Memoized EmptyState for performance optimization.
+ *
+ * The EmptyState component doesn't change frequently, so memoization
+ * prevents unnecessary re-renders when the parent component updates.
+ * Only re-renders when onExampleClick callback changes (which should
+ * be stable if defined with useCallback in the parent).
+ */
+const EmptyState = memo(EmptyStateComponent);
+
+export { EmptyState };

frontend/src/components/chat/error-state.tsx

@@ -0,0 +1,652 @@
+/**
+ * ErrorState Component
+ *
+ * A minimal error display component for the RAG chatbot interface. Handles
+ * various error scenarios including quota exceeded (503), network failures,
+ * and general errors with distinct visual styling and user-friendly messaging.
+ *
+ * Features:
+ * - Type-specific visual styling using the design system's color palette:
+ *   - Quota errors: Purple accent (via --color-primary-* CSS variables)
+ *   - Network errors: Blue semantic color
+ *   - General errors: Red semantic color
+ * - Live countdown timer for quota errors with auto-retry
+ * - Retry functionality with disabled state during countdown
+ * - Dismiss capability for clearing errors
+ * - Clean, minimal design with subtle shadows
+ * - Full WCAG AA accessibility compliance
+ * - Smooth entrance animations
+ *
+ * @module components/chat/error-state
+ * @since 1.0.0
+ *
+ * @example
+ * // Basic quota error with countdown (displays with purple theme)
+ * <ErrorState
+ *   type="quota"
+ *   retryAfter={60}
+ *   onRetry={() => handleRetry()}
+ *   onDismiss={() => clearError()}
+ * />
+ *
+ * @example
+ * // Network error with retry button (displays with blue theme)
+ * <ErrorState
+ *   type="network"
+ *   onRetry={() => handleRetry()}
+ * />
+ *
+ * @example
+ * // General error with custom message (displays with red theme)
+ * <ErrorState
+ *   type="general"
+ *   message="Failed to process your request. Please try again."
+ *   onRetry={() => handleRetry()}
+ *   onDismiss={() => clearError()}
+ * />
+ */
+
+'use client';
+
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useState,
+  type HTMLAttributes,
+} from 'react';
+import { AlertTriangle, WifiOff, RefreshCw, Clock, X } from 'lucide-react';
+import { cn } from '@/lib/utils';
+
+/**
+ * Error type definitions for visual and content differentiation.
+ *
+ * - `quota`: Service temporarily unavailable due to rate limiting (HTTP 503)
+ * - `network`: Connection issues preventing communication with the server
+ * - `general`: Catch-all for other error types
+ *
+ * @public
+ */
+export type ErrorType = 'quota' | 'network' | 'general';
+
+/**
+ * Props for the ErrorState component.
+ *
+ * Extends standard HTML div attributes for flexibility in styling
+ * and event handling while providing error-specific configuration.
+ *
+ * @public
+ */
+export interface ErrorStateProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  /**
+   * Error type for visual distinction and default messaging.
+   * Each type has its own icon, color scheme, and default message.
+   *
+   * - `quota`: Purple styling with clock icon (uses design system's primary color)
+   * - `network`: Blue styling with wifi-off icon (semantic network/connection color)
+   * - `general`: Red styling with alert triangle icon (semantic error color)
+   */
+  type: ErrorType;
+
+  /**
+   * User-friendly error message to display.
+   * If not provided, a default message based on the error type is shown.
+   *
+   * @example
+   * message="Unable to connect to the server. Please try again later."
+   */
+  message?: string;
+
+  /**
+   * Seconds until retry is allowed (primarily for quota errors).
+   * When provided, displays a live countdown timer and disables
+   * the retry button until the countdown reaches zero.
+   *
+   * @example
+   * retryAfter={45} // Shows "Try again in 45s" and counts down
+   */
+  retryAfter?: number;
+
+  /**
+   * Callback fired when the retry button is clicked.
+   * The retry button is only shown when this callback is provided.
+   * For quota errors with retryAfter, the button is disabled during countdown.
+   *
+   * @param event - The click event from the retry button
+   */
+  onRetry?: () => void;
+
+  /**
+   * Callback fired when the dismiss button is clicked.
+   * The dismiss button is only shown when this callback is provided.
+   * Use this to clear the error state in the parent component.
+   */
+  onDismiss?: () => void;
+}
+
+/**
+ * Configuration object for error type-specific styling and content.
+ *
+ * @internal
+ */
+interface ErrorTypeConfig {
+  /** Lucide React icon component */
+  icon: typeof AlertTriangle;
+  /** Default message when no custom message is provided */
+  defaultMessage: string;
+  /** Tailwind classes for the icon container background */
+  iconBgClass: string;
+  /** Tailwind classes for the icon color */
+  iconColorClass: string;
+  /** Tailwind classes for the card border accent */
+  borderAccentClass: string;
+  /** Tailwind classes for action button styling */
+  buttonClass: string;
+}
+
+/**
+ * Error type configuration mapping.
+ *
+ * Defines the visual appearance and default content for each error type.
+ * Uses CSS variables from globals.css for consistent theming.
+ *
+ * Color scheme:
+ * - quota: Purple (via --color-primary-* CSS variables) - indicates temporary unavailability
+ * - network: Blue - semantic color for connectivity issues
+ * - general: Red - semantic color for errors/failures
+ *
+ * @internal
+ */
+const ERROR_TYPE_CONFIGS: Record<ErrorType, ErrorTypeConfig> = {
+  /**
+   * Quota error configuration - Purple theme
+   *
+   * Uses the design system's primary color (purple) via CSS variables.
+   * This ensures the quota error styling automatically follows any
+   * theme changes to the primary color palette.
+   */
+  quota: {
+    icon: Clock,
+    defaultMessage:
+      'Our service is currently at capacity. Please wait a moment.',
+    /* Purple gradient background for icon circle */
+    iconBgClass:
+      'bg-gradient-to-br from-[var(--color-primary-100)] to-[var(--color-primary-200)]',
+    /* Purple icon color */
+    iconColorClass: 'text-[var(--color-primary-600)]',
+    /* Purple border accent */
+    borderAccentClass: 'border-[var(--color-primary-300)]',
+    /* Purple button with proper contrast for text */
+    buttonClass:
+      'bg-[var(--color-primary-500)] text-[var(--color-primary-button-text)] hover:bg-[var(--color-primary-600)] disabled:bg-[var(--color-primary-200)] disabled:text-[var(--foreground-muted)]',
+  },
+  /**
+   * Network error configuration - Blue theme
+   *
+   * Uses semantic blue color for connectivity/network issues.
+   * Blue is commonly associated with information and connection states.
+   */
+  network: {
+    icon: WifiOff,
+    defaultMessage: 'Unable to connect. Please check your internet connection.',
+    /* Blue gradient background for icon circle */
+    iconBgClass: 'bg-gradient-to-br from-blue-100 to-blue-200',
+    /* Blue icon color */
+    iconColorClass: 'text-blue-600',
+    /* Blue border accent */
+    borderAccentClass: 'border-blue-300',
+    /* Blue button styling */
+    buttonClass:
+      'bg-blue-500 text-white hover:bg-blue-600 disabled:bg-blue-200 disabled:text-blue-400',
+  },
+  /**
+   * General error configuration - Red theme
+   *
+   * Uses semantic red color for general errors and failures.
+   * Red is universally recognized as an error/warning indicator.
+   */
+  general: {
+    icon: AlertTriangle,
+    defaultMessage: 'Something went wrong. Please try again.',
+    /* Red gradient background for icon circle */
+    iconBgClass: 'bg-gradient-to-br from-red-100 to-red-200',
+    /* Red icon color */
+    iconColorClass: 'text-red-600',
+    /* Red border accent */
+    borderAccentClass: 'border-red-300',
+    /* Red button styling */
+    buttonClass:
+      'bg-red-500 text-white hover:bg-red-600 disabled:bg-red-200 disabled:text-red-400',
+  },
+};
+
+/**
+ * Formats seconds into a human-readable countdown string.
+ *
+ * Converts raw seconds into minutes:seconds format when appropriate,
+ * or displays just seconds for shorter durations.
+ *
+ * @param seconds - Number of seconds remaining
+ * @returns Formatted string (e.g., "45s", "1:30")
+ *
+ * @internal
+ */
+function formatCountdown(seconds: number): string {
+  if (seconds <= 0) return '0s';
+
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+
+  // Format with leading zero for seconds when showing minutes
+  return `${minutes}:${remainingSeconds.toString().padStart(2, '0')}`;
+}
+
+/**
+ * Custom hook for managing the countdown timer.
+ *
+ * Handles the countdown logic with proper cleanup on unmount.
+ * Returns the current countdown value and whether the countdown is active.
+ *
+ * @param initialSeconds - Starting value for the countdown
+ * @returns Object containing current seconds and active state
+ *
+ * @internal
+ */
+function useCountdown(initialSeconds: number | undefined): {
+  secondsRemaining: number;
+  isCountdownActive: boolean;
+} {
+  // Initialize state with the provided value or 0
+  const [secondsRemaining, setSecondsRemaining] = useState<number>(
+    initialSeconds ?? 0
+  );
+
+  // Determine if countdown is active (has time remaining)
+  const isCountdownActive = secondsRemaining > 0;
+
+  /**
+   * Effect to reset countdown when initialSeconds prop changes AND
+   * handle the countdown timer interval.
+   *
+   * This pattern of calling setState at the start of an effect to reset
+   * state when a prop changes is intentional - it's the standard React
+   * pattern for synchronizing state with props.
+   * See: https://react.dev/learn/you-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes
+   *
+   * Creates an interval that decrements the counter every second.
+   * Cleans up the interval when:
+   * - Component unmounts
+   * - Countdown reaches zero
+   * - initialSeconds prop changes
+   */
+  useEffect(() => {
+    // Reset the countdown when initialSeconds changes
+    // This is the synchronization pattern - reset state when prop changes
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setSecondsRemaining(initialSeconds ?? 0);
+
+    // Don't start timer if no initial value or zero
+    if (!initialSeconds || initialSeconds <= 0) {
+      return;
+    }
+
+    // Create interval to decrement countdown every second
+    const intervalId = setInterval(() => {
+      setSecondsRemaining((prev) => {
+        // Stop at zero
+        if (prev <= 1) {
+          clearInterval(intervalId);
+          return 0;
+        }
+        return prev - 1;
+      });
+    }, 1000);
+
+    // Cleanup interval on unmount or when initialSeconds changes
+    return () => {
+      clearInterval(intervalId);
+    };
+  }, [initialSeconds]);
+
+  return { secondsRemaining, isCountdownActive };
+}
+
+/**
+ * ErrorState Component
+ *
+ * Displays a minimal error state card with type-specific styling,
+ * optional countdown timer, and action buttons for retry/dismiss.
+ *
+ * @remarks
+ * ## Visual Design
+ *
+ * The component features a clean, minimal card design with:
+ * - Type-specific icon in a gradient circle
+ * - Clear heading and descriptive message
+ * - Optional countdown timer display (purple-themed for quota errors)
+ * - Action buttons (retry and dismiss)
+ * - Subtle shadow for depth without overwhelming the UI
+ *
+ * ## Color Theming
+ *
+ * Each error type uses a distinct color to provide semantic meaning:
+ * - Quota errors: Purple (via CSS variables --color-primary-*)
+ * - Network errors: Blue (semantic connectivity color)
+ * - General errors: Red (semantic error color)
+ *
+ * ## Countdown Timer
+ *
+ * For quota errors (503 responses), the component can display a live
+ * countdown timer that shows when the user can retry:
+ * - Timer updates every second with purple-themed styling
+ * - Retry button is disabled during countdown
+ * - Timer automatically enables retry when it reaches zero
+ * - Proper cleanup on component unmount
+ *
+ * ## Accessibility
+ *
+ * The component follows WCAG AA guidelines:
+ * - Uses `role="alert"` for screen reader announcements
+ * - `aria-live="assertive"` for immediate announcement of errors
+ * - Decorative icons are hidden from screen readers
+ * - All interactive elements are keyboard accessible
+ * - Focus states are clearly visible
+ *
+ * ## Animation
+ *
+ * Uses the slide-up animation for smooth entrance, consistent
+ * with other components in the application.
+ *
+ * @param props - ErrorState component props
+ * @returns React element containing the error display
+ *
+ * @see {@link ErrorStateProps} for full prop documentation
+ */
+function ErrorStateComponent({
+  type,
+  message,
+  retryAfter,
+  onRetry,
+  onDismiss,
+  className,
+  ...props
+}: ErrorStateProps): React.ReactElement {
+  /**
+   * Get configuration for the current error type.
+   * Includes icon, colors, and default message.
+   */
+  const config = ERROR_TYPE_CONFIGS[type];
+
+  /**
+   * Use the countdown hook to manage timer state.
+   * Provides current seconds remaining and active state.
+   */
+  const { secondsRemaining, isCountdownActive } = useCountdown(retryAfter);
+
+  /**
+   * Determine the message to display.
+   * Use custom message if provided, otherwise fall back to type default.
+   */
+  const displayMessage = message || config.defaultMessage;
+
+  /**
+   * Determine if retry button should be disabled.
+   * Disabled during countdown for quota errors.
+   */
+  const isRetryDisabled = type === 'quota' && isCountdownActive;
+
+  /**
+   * Memoized retry handler to prevent unnecessary re-renders.
+   * Only calls onRetry if provided and not disabled.
+   */
+  const handleRetry = useCallback(() => {
+    if (onRetry && !isRetryDisabled) {
+      onRetry();
+    }
+  }, [onRetry, isRetryDisabled]);
+
+  /**
+   * Memoized dismiss handler to prevent unnecessary re-renders.
+   */
+  const handleDismiss = useCallback(() => {
+    if (onDismiss) {
+      onDismiss();
+    }
+  }, [onDismiss]);
+
+  // Get the icon component from config
+  const IconComponent = config.icon;
+
+  return (
+    <div
+      role="alert"
+      aria-live="assertive"
+      className={cn(
+        /* Full width container with max width constraint */
+        'mx-auto w-full max-w-lg',
+        /* Spacing */
+        'px-4 py-6',
+        /* Animation on entrance */
+        'animate-slide-up',
+        className
+      )}
+      {...props}
+    >
+      {/* Card container with clean, minimal design */}
+      <div
+        className={cn(
+          /* Solid background for clean minimal aesthetic */
+          'bg-[var(--background-secondary)]',
+          /* Type-specific border accent for visual distinction */
+          'border',
+          config.borderAccentClass,
+          /* Rounded corners */
+          'rounded-2xl',
+          /* Subtle shadow for depth without overwhelming */
+          'shadow-[var(--shadow-md)]',
+          /* Padding */
+          'p-6',
+          /* Relative for dismiss button positioning */
+          'relative'
+        )}
+      >
+        {/* Dismiss button - positioned in top right corner */}
+        {onDismiss && (
+          <button
+            type="button"
+            onClick={handleDismiss}
+            aria-label="Dismiss error"
+            className={cn(
+              /* Positioning */
+              'absolute top-3 right-3',
+              /* Size and shape */
+              'h-8 w-8 rounded-full',
+              /* Flex for centering icon */
+              'flex items-center justify-center',
+              /* Colors and hover state */
+              'text-[var(--foreground-muted)]',
+              'hover:bg-[var(--background-tertiary)]',
+              'hover:text-[var(--foreground-secondary)]',
+              /* Transition */
+              'transition-colors duration-[var(--transition-fast)]',
+              /* Focus state for accessibility */
+              'focus:outline-none',
+              'focus-visible:ring-2',
+              'focus-visible:ring-[var(--border-focus)]',
+              'focus-visible:ring-offset-2'
+            )}
+          >
+            <X className="h-4 w-4" aria-hidden="true" />
+          </button>
+        )}
+
+        {/* Icon section */}
+        <div className="mb-4 flex justify-center">
+          <div
+            className={cn(
+              /* Circular container for icon */
+              'h-14 w-14 rounded-full',
+              /* Type-specific gradient background */
+              config.iconBgClass,
+              /* Flex for centering icon */
+              'flex items-center justify-center',
+              /* Shadow for depth */
+              'shadow-[var(--shadow-md)]'
+            )}
+          >
+            <IconComponent
+              className={cn('h-7 w-7', config.iconColorClass)}
+              strokeWidth={1.5}
+              aria-hidden="true"
+            />
+          </div>
+        </div>
+
+        {/* Title section */}
+        <div className="mb-4 text-center">
+          <h3
+            className={cn(
+              /* Typography */
+              'text-lg font-semibold',
+              'text-[var(--foreground)]',
+              /* Spacing */
+              'mb-2'
+            )}
+          >
+            {type === 'quota' && 'Service Temporarily Unavailable'}
+            {type === 'network' && 'Connection Lost'}
+            {type === 'general' && 'Oops! Something Went Wrong'}
+          </h3>
+          <p
+            className={cn(
+              /* Typography */
+              'text-[var(--foreground-secondary)]',
+              'text-sm leading-relaxed',
+              /* Max width for readability */
+              'mx-auto max-w-sm'
+            )}
+          >
+            {displayMessage}
+          </p>
+        </div>
+
+        {/*
+          Countdown timer display (only for quota errors with retryAfter)
+          Uses purple theme via CSS variables (--color-primary-*)
+          to match the quota error styling
+        */}
+        {type === 'quota' && retryAfter !== undefined && retryAfter > 0 && (
+          <div
+            className={cn(
+              /* Container styling with purple background tint */
+              'mb-4 mx-auto max-w-xs',
+              'px-4 py-2',
+              'bg-[var(--color-primary-50)]/50',
+              /* Purple border to match quota error theme */
+              'border border-[var(--color-primary-200)]',
+              'rounded-[var(--radius-lg)]',
+              /* Flex layout for icon and text alignment */
+              'flex items-center justify-center gap-2',
+              /* Smooth fade-in animation */
+              'animate-fade-in'
+            )}
+            aria-live="polite"
+            aria-atomic="true"
+          >
+            {/* Clock icon in purple */}
+            <Clock
+              className="h-4 w-4 text-[var(--color-primary-500)]"
+              strokeWidth={2}
+              aria-hidden="true"
+            />
+            {/* Countdown text in purple for visual consistency */}
+            <span className="text-sm font-medium text-[var(--color-primary-700)]">
+              {isCountdownActive
+                ? `Try again in ${formatCountdown(secondsRemaining)}`
+                : 'Ready to retry'}
+            </span>
+          </div>
+        )}
+
+        {/*
+          Action buttons section
+          Button color matches the error type for visual consistency:
+          - Quota: Purple button (via CSS variables)
+          - Network: Blue button (semantic connectivity color)
+          - General: Red button (semantic error color)
+        */}
+        {onRetry && (
+          <div className="flex justify-center">
+            <button
+              type="button"
+              onClick={handleRetry}
+              disabled={isRetryDisabled}
+              className={cn(
+                /* Base button styles */
+                'px-5 py-2.5',
+                'rounded-[var(--radius-lg)]',
+                /* Font styling */
+                'text-sm font-medium',
+                /* Flex for icon alignment */
+                'inline-flex items-center gap-2',
+                /*
+                  Type-specific button colors:
+                  - quota: Purple (CSS variables)
+                  - network: Blue
+                  - general: Red
+                */
+                config.buttonClass,
+                /* Subtle shadow */
+                'shadow-[var(--shadow-sm)]',
+                /* Smooth transitions */
+                'transition-all duration-[var(--transition-fast)]',
+                /* Hover shadow enhancement (when not disabled) */
+                'hover:shadow-[var(--shadow-md)]',
+                /* Focus state for accessibility */
+                'focus:outline-none',
+                'focus-visible:ring-2',
+                'focus-visible:ring-[var(--border-focus)]',
+                'focus-visible:ring-offset-2',
+                /* Disabled state styling */
+                'disabled:cursor-not-allowed',
+                'disabled:shadow-none'
+              )}
+            >
+              <RefreshCw
+                className={cn(
+                  'h-4 w-4',
+                  /* Animate icon when countdown is active to indicate waiting */
+                  isCountdownActive && 'animate-pulse-custom'
+                )}
+                strokeWidth={2}
+                aria-hidden="true"
+              />
+              <span>{isRetryDisabled ? 'Please wait...' : 'Try Again'}</span>
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/* Display name for React DevTools */
+ErrorStateComponent.displayName = 'ErrorState';
+
+/**
+ * Memoized ErrorState for performance optimization.
+ *
+ * The ErrorState component benefits from memoization as it may be
+ * rendered within frequently updating parent components. Only re-renders
+ * when props change, preventing unnecessary work during chat updates.
+ *
+ * @public
+ */
+const ErrorState = memo(ErrorStateComponent);
+
+export { ErrorState };

frontend/src/components/chat/index.ts

@@ -0,0 +1,189 @@
+/**
+ * Chat Components Barrel Export
+ *
+ * Re-exports all chat-specific components for convenient imports.
+ * These components work together to create the chat interface for
+ * the RAG chatbot application.
+ *
+ * @module components/chat
+ * @since 1.0.0
+ *
+ * @example
+ * // Import individual components
+ * import { ChatMessage, ChatInput, ChatContainer } from '@/components/chat';
+ *
+ * @example
+ * // Use components together in a page
+ * import { ChatContainer } from '@/components/chat';
+ *
+ * function ChatPage() {
+ *   return <ChatContainer title="My Chat" />;
+ * }
+ *
+ * @example
+ * // Build a custom chat interface with lower-level components
+ * import {
+ *   MemoizedChatMessage,
+ *   ChatInput,
+ *   EmptyState,
+ * } from '@/components/chat';
+ * import { useChat } from '@/hooks/use-chat';
+ *
+ * function CustomChatInterface() {
+ *   const { messages, addMessage, isLoading } = useChat();
+ *
+ *   return (
+ *     <div>
+ *       {messages.length === 0 ? (
+ *         <EmptyState onExampleClick={(q) => addMessage('user', q)} />
+ *       ) : (
+ *         messages.map(msg => (
+ *           <MemoizedChatMessage key={msg.id} message={msg} />
+ *         ))
+ *       )}
+ *       <ChatInput onSubmit={(content) => addMessage('user', content)} isLoading={isLoading} />
+ *     </div>
+ *   );
+ * }
+ */
+
+/**
+ * ChatMessage - Display component for individual chat messages.
+ *
+ * Renders user and assistant messages with distinct styling:
+ * - User messages: Right-aligned, primary orange background
+ * - Assistant messages: Left-aligned, secondary gray background
+ *
+ * Supports streaming state with animated cursor.
+ *
+ * @see {@link ./chat-message} for full documentation
+ */
+export { ChatMessage, MemoizedChatMessage } from './chat-message';
+export type { ChatMessageProps } from './chat-message';
+
+/**
+ * ChatInput - Input component for composing chat messages.
+ *
+ * Features:
+ * - Auto-growing textarea (up to 200px)
+ * - Enter to submit, Shift+Enter for new line
+ * - Character limit indicator
+ * - Loading state with spinner
+ * - Imperative handle for programmatic control
+ *
+ * @see {@link ./chat-input} for full documentation
+ */
+export { ChatInput } from './chat-input';
+export type { ChatInputProps, ChatInputHandle } from './chat-input';
+
+/**
+ * ChatContainer - Main orchestrating component for the chat interface.
+ *
+ * The primary component for integrating a full chat experience.
+ * Combines header, message list, empty state, and input area.
+ *
+ * Features:
+ * - Header with title and optional subtitle
+ * - Scrollable message list with auto-scroll
+ * - Empty state with example questions
+ * - Fixed input area at bottom
+ * - Error banner for error display
+ * - Loading indicator during response generation
+ *
+ * @see {@link ./chat-container} for full documentation
+ */
+export { ChatContainer } from './chat-container';
+export type { ChatContainerProps } from './chat-container';
+
+/**
+ * EmptyState - Welcome component shown when chat has no messages.
+ *
+ * Displays a friendly introduction with example questions that
+ * users can click to quickly start a conversation.
+ *
+ * Features:
+ * - Welcoming icon and title
+ * - Descriptive subtitle
+ * - Clickable example question buttons
+ * - Modern card design with glassmorphism effect
+ *
+ * @see {@link ./empty-state} for full documentation
+ */
+export { EmptyState } from './empty-state';
+export type { EmptyStateProps } from './empty-state';
+
+/**
+ * ErrorState - Error display component for various error scenarios.
+ *
+ * A premium error state component that handles quota exceeded (503),
+ * network failures, and general errors with distinct visual styling.
+ *
+ * Features:
+ * - Type-specific visual styling (quota, network, general)
+ * - Live countdown timer for quota errors with auto-retry
+ * - Retry and dismiss functionality
+ * - Glassmorphism card design
+ * - Full WCAG AA accessibility compliance
+ *
+ * @see {@link ./error-state} for full documentation
+ */
+export { ErrorState } from './error-state';
+export type { ErrorStateProps, ErrorType } from './error-state';
+
+/**
+ * ProviderToggle - LLM provider selection component (pill layout).
+ *
+ * A premium horizontal pill/chip layout for selecting LLM providers
+ * with real-time status indicators and cooldown timers.
+ *
+ * Features:
+ * - Horizontal pill layout with "Auto" as first option
+ * - Green pulse dot for available providers
+ * - Red dot with countdown for providers in cooldown
+ * - Full keyboard navigation (arrow keys, Home/End)
+ * - Radio group accessibility semantics
+ * - Responsive: stacks vertically on mobile
+ *
+ * @see {@link ./provider-toggle} for full documentation
+ */
+export { ProviderToggle } from './provider-toggle';
+export type { ProviderToggleProps } from './provider-toggle';
+
+/**
+ * ProviderSelector - Claude-style dropdown for LLM provider selection.
+ *
+ * A minimal dropdown selector styled after Claude's model selector,
+ * designed to be placed in the input area near the send button.
+ *
+ * Features:
+ * - Compact dropdown trigger showing selected provider
+ * - Dropdown menu with all available providers
+ * - Status indicators (available, cooldown)
+ * - Cooldown timer display
+ * - Keyboard navigation support
+ *
+ * @see {@link ./provider-selector} for full documentation
+ */
+export { ProviderSelector } from './provider-selector';
+export type { ProviderSelectorProps } from './provider-selector';
+
+/**
+ * Sidebar - Collapsible left sidebar showing current provider/model.
+ *
+ * Displays the currently selected LLM provider and model name.
+ * Collapses to icon-only mode for a minimal footprint.
+ *
+ * Features:
+ * - Shows provider name and model name
+ * - Collapsible to icon-only mode
+ * - Persists collapse state to localStorage
+ * - Status indicators for availability
+ *
+ * @see {@link ./sidebar} for full documentation
+ */
+export { Sidebar } from './sidebar';
+export type { SidebarProps } from './sidebar';
+
+// Future exports (to be implemented in subsequent steps):
+// export * from './source-card';
+// export * from './message-list';

frontend/src/components/chat/provider-selector.tsx

@@ -0,0 +1,359 @@
+/**
+ * ProviderSelector Component - Claude-Style Model Dropdown
+ *
+ * A minimal dropdown selector for LLM providers, styled after Claude's
+ * model selector in the input area. Shows the currently selected provider
+ * with a chevron indicator, and opens a dropdown for selection.
+ *
+ * @module components/chat/provider-selector
+ * @since 1.0.0
+ *
+ * @example
+ * // Usage in ChatInput
+ * <ProviderSelector />
+ */
+
+'use client';
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactElement,
+} from 'react';
+import { ChevronDown, Zap, Check, Clock } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { useProviders, type ProviderStatus } from '@/hooks';
+
+/**
+ * Props for the ProviderSelector component.
+ */
+export interface ProviderSelectorProps {
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * Provider option type including Auto option.
+ * @internal
+ */
+interface ProviderOption {
+  id: string | null;
+  name: string;
+  isAvailable: boolean;
+  cooldownSeconds: number | null;
+}
+
+/**
+ * Auto option configuration.
+ * @internal
+ */
+const AUTO_OPTION: ProviderOption = {
+  id: null,
+  name: 'Auto',
+  isAvailable: true,
+  cooldownSeconds: null,
+};
+
+/**
+ * Format cooldown seconds.
+ * @internal
+ */
+function formatCooldown(seconds: number): string {
+  if (seconds <= 0) return '';
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes > 0) {
+    return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+  }
+  return `${remainingSeconds}s`;
+}
+
+/**
+ * Transform providers to options.
+ * @internal
+ */
+function transformToOptions(providers: ProviderStatus[]): ProviderOption[] {
+  const providerOptions: ProviderOption[] = providers.map((provider) => ({
+    id: provider.id,
+    name: provider.name,
+    isAvailable: provider.isAvailable,
+    cooldownSeconds: provider.cooldownSeconds,
+  }));
+  return [AUTO_OPTION, ...providerOptions];
+}
+
+/**
+ * Status dot indicator.
+ * @internal
+ */
+function StatusDot({ isAvailable, hasCooldown }: { isAvailable: boolean; hasCooldown: boolean }): ReactElement {
+  if (hasCooldown) {
+    return <span className="h-1.5 w-1.5 rounded-full bg-amber-500" />;
+  }
+  if (isAvailable) {
+    return <span className="h-1.5 w-1.5 rounded-full bg-green-500" />;
+  }
+  return <span className="h-1.5 w-1.5 rounded-full bg-gray-400" />;
+}
+
+/**
+ * ProviderSelector Component
+ *
+ * A Claude-style dropdown for selecting LLM providers. Positioned in the
+ * input area, it shows the current selection with a minimal design that
+ * expands to show all available providers.
+ */
+export function ProviderSelector({ className }: ProviderSelectorProps): ReactElement {
+  const {
+    providers,
+    selectedProvider,
+    selectProvider,
+    isLoading,
+  } = useProviders();
+
+  const [isOpen, setIsOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  /* Transform providers to options */
+  const options = useMemo(() => transformToOptions(providers), [providers]);
+
+  /* Find selected option */
+  const selectedOption = useMemo(() => {
+    return options.find((opt) => opt.id === selectedProvider) ?? AUTO_OPTION;
+  }, [options, selectedProvider]);
+
+  /* Handle outside click to close dropdown */
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    }
+
+    if (isOpen) {
+      document.addEventListener('mousedown', handleClickOutside);
+      return () => document.removeEventListener('mousedown', handleClickOutside);
+    }
+  }, [isOpen]);
+
+  /* Handle escape key to close */
+  useEffect(() => {
+    function handleEscape(event: globalThis.KeyboardEvent) {
+      if (event.key === 'Escape' && isOpen) {
+        setIsOpen(false);
+        buttonRef.current?.focus();
+      }
+    }
+
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [isOpen]);
+
+  /* Toggle dropdown */
+  const handleToggle = useCallback(() => {
+    setIsOpen((prev) => !prev);
+  }, []);
+
+  /* Select provider and close */
+  const handleSelect = useCallback(
+    (id: string | null) => {
+      selectProvider(id);
+      setIsOpen(false);
+      buttonRef.current?.focus();
+    },
+    [selectProvider]
+  );
+
+  /* Keyboard navigation in dropdown */
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLButtonElement>, index: number) => {
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault();
+          const nextIndex = (index + 1) % options.length;
+          const nextButton = containerRef.current?.querySelectorAll('[role="option"]')[nextIndex] as HTMLButtonElement;
+          nextButton?.focus();
+          break;
+        case 'ArrowUp':
+          e.preventDefault();
+          const prevIndex = (index - 1 + options.length) % options.length;
+          const prevButton = containerRef.current?.querySelectorAll('[role="option"]')[prevIndex] as HTMLButtonElement;
+          prevButton?.focus();
+          break;
+        case 'Enter':
+        case ' ':
+          e.preventDefault();
+          handleSelect(options[index].id);
+          break;
+      }
+    },
+    [options, handleSelect]
+  );
+
+  /* Loading state */
+  if (isLoading) {
+    return (
+      <div className={cn('h-8 w-20 animate-pulse rounded-lg bg-gray-200 dark:bg-gray-700', className)} />
+    );
+  }
+
+  return (
+    <div ref={containerRef} className={cn('relative', className)}>
+      {/* Trigger Button - Claude-style minimal */}
+      <button
+        ref={buttonRef}
+        type="button"
+        onClick={handleToggle}
+        aria-expanded={isOpen}
+        aria-haspopup="listbox"
+        aria-label={`Selected provider: ${selectedOption.name}`}
+        className={cn(
+          /* Layout */
+          'inline-flex items-center gap-1.5',
+          'h-8 px-3',
+          /* Typography */
+          'text-sm font-medium',
+          'text-gray-600 dark:text-gray-300',
+          /* Styling - minimal and clean */
+          'rounded-lg',
+          'bg-transparent',
+          /* Hover/focus states */
+          'hover:bg-gray-100 dark:hover:bg-gray-800',
+          'focus:outline-none',
+          'focus-visible:ring-2 focus-visible:ring-purple-500 focus-visible:ring-offset-2',
+          /* Transition */
+          'transition-colors duration-150',
+          /* Cursor */
+          'cursor-pointer'
+        )}
+      >
+        {/* Auto icon or status dot */}
+        {selectedOption.id === null ? (
+          <Zap className="h-3.5 w-3.5 text-purple-500" aria-hidden="true" />
+        ) : (
+          <StatusDot
+            isAvailable={selectedOption.isAvailable}
+            hasCooldown={selectedOption.cooldownSeconds !== null && selectedOption.cooldownSeconds > 0}
+          />
+        )}
+
+        {/* Provider name */}
+        <span>{selectedOption.name}</span>
+
+        {/* Chevron */}
+        <ChevronDown
+          className={cn(
+            'h-3.5 w-3.5 text-gray-400',
+            'transition-transform duration-150',
+            isOpen && 'rotate-180'
+          )}
+          aria-hidden="true"
+        />
+      </button>
+
+      {/* Dropdown Menu */}
+      {isOpen && (
+        <div
+          role="listbox"
+          aria-label="Select provider"
+          className={cn(
+            /* Position - above the button */
+            'absolute bottom-full left-0 mb-2',
+            /* Sizing */
+            'min-w-[160px]',
+            /* Styling */
+            'bg-white dark:bg-gray-900',
+            'border border-gray-200 dark:border-gray-700',
+            'rounded-xl',
+            'shadow-lg',
+            /* Animation */
+            'animate-fade-in',
+            /* Overflow */
+            'overflow-hidden',
+            /* Z-index */
+            'z-50'
+          )}
+        >
+          <div className="py-1">
+            {options.map((option, index) => {
+              const isSelected = option.id === selectedProvider;
+              const hasCooldown = option.cooldownSeconds !== null && option.cooldownSeconds > 0;
+
+              return (
+                <button
+                  key={option.id ?? 'auto'}
+                  type="button"
+                  role="option"
+                  aria-selected={isSelected}
+                  onClick={() => handleSelect(option.id)}
+                  onKeyDown={(e) => handleKeyDown(e, index)}
+                  className={cn(
+                    /* Layout */
+                    'w-full flex items-center justify-between gap-3',
+                    'px-3 py-2',
+                    /* Typography */
+                    'text-sm',
+                    /* Colors */
+                    isSelected
+                      ? 'bg-purple-50 dark:bg-purple-900/20 text-purple-700 dark:text-purple-300'
+                      : 'text-gray-700 dark:text-gray-200',
+                    /* Hover */
+                    !isSelected && 'hover:bg-gray-50 dark:hover:bg-gray-800',
+                    /* Disabled appearance for cooldown */
+                    hasCooldown && !isSelected && 'opacity-60',
+                    /* Focus */
+                    'focus:outline-none focus:bg-gray-50 dark:focus:bg-gray-800',
+                    /* Transition */
+                    'transition-colors duration-100',
+                    /* Cursor */
+                    'cursor-pointer'
+                  )}
+                >
+                  {/* Left side: icon/dot and name */}
+                  <span className="flex items-center gap-2">
+                    {option.id === null ? (
+                      <Zap
+                        className={cn(
+                          'h-3.5 w-3.5',
+                          isSelected ? 'text-purple-500' : 'text-purple-400'
+                        )}
+                        aria-hidden="true"
+                      />
+                    ) : (
+                      <StatusDot isAvailable={option.isAvailable} hasCooldown={hasCooldown} />
+                    )}
+                    <span className="font-medium">{option.name}</span>
+                  </span>
+
+                  {/* Right side: cooldown or check */}
+                  <span className="flex items-center gap-1.5">
+                    {hasCooldown && (
+                      <span className="flex items-center gap-1 text-xs text-amber-600 dark:text-amber-400">
+                        <Clock className="h-3 w-3" aria-hidden="true" />
+                        {formatCooldown(option.cooldownSeconds!)}
+                      </span>
+                    )}
+                    {isSelected && (
+                      <Check
+                        className="h-4 w-4 text-purple-500"
+                        strokeWidth={2.5}
+                        aria-hidden="true"
+                      />
+                    )}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+ProviderSelector.displayName = 'ProviderSelector';

frontend/src/components/chat/provider-toggle.tsx

@@ -0,0 +1,756 @@
+'use client';
+
+/**
+ * Provider Toggle Component
+ *
+ * A production-ready, premium UI component for selecting LLM providers.
+ * Displays providers as horizontal selectable pills with real-time status
+ * indicators, cooldown timers, and accessibility-first design.
+ *
+ * @module components/chat/provider-toggle
+ * @since 1.0.0
+ *
+ * @example
+ * // Basic usage
+ * import { ProviderToggle } from '@/components/chat';
+ *
+ * function ChatHeader() {
+ *   return (
+ *     <header>
+ *       <h1>Chat</h1>
+ *       <ProviderToggle />
+ *     </header>
+ *   );
+ * }
+ *
+ * @example
+ * // Compact variant for tight spaces
+ * <ProviderToggle compact />
+ *
+ * @example
+ * // With custom className
+ * <ProviderToggle className="mt-4" />
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactElement,
+} from 'react';
+import { Zap, RefreshCw, Clock, AlertCircle } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { useProviders, type ProviderStatus } from '@/hooks';
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/**
+ * Props for the ProviderToggle component.
+ *
+ * @public
+ */
+export interface ProviderToggleProps {
+  /**
+   * Additional CSS classes to apply to the container.
+   */
+  className?: string;
+
+  /**
+   * Smaller variant for tight spaces.
+   * Reduces padding, font sizes, and indicator sizes.
+   *
+   * @default false
+   */
+  compact?: boolean;
+}
+
+/**
+ * Internal type representing a provider option including the "Auto" option.
+ *
+ * @internal
+ */
+interface ProviderOption {
+  /** Unique identifier (null for auto mode) */
+  id: string | null;
+  /** Display name */
+  name: string;
+  /** Description text */
+  description: string;
+  /** Whether the provider is available */
+  isAvailable: boolean;
+  /** Remaining cooldown in seconds (null if not in cooldown) */
+  cooldownSeconds: number | null;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Auto option configuration.
+ * This is always the first option in the provider list.
+ *
+ * @internal
+ */
+const AUTO_OPTION: ProviderOption = {
+  id: null,
+  name: 'Auto',
+  description: 'Automatically select the best available provider',
+  isAvailable: true,
+  cooldownSeconds: null,
+};
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Format cooldown seconds into a human-readable string.
+ *
+ * @param seconds - Cooldown duration in seconds
+ * @returns Formatted string (e.g., "2m 30s" or "45s")
+ *
+ * @internal
+ */
+function formatCooldown(seconds: number): string {
+  if (seconds <= 0) return '';
+
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+
+  if (minutes > 0) {
+    return remainingSeconds > 0
+      ? `${minutes}m ${remainingSeconds}s`
+      : `${minutes}m`;
+  }
+
+  return `${remainingSeconds}s`;
+}
+
+/**
+ * Transform provider statuses into option format, prepending Auto option.
+ *
+ * @param providers - Array of provider statuses from the hook
+ * @returns Array of provider options with Auto as the first element
+ *
+ * @internal
+ */
+function transformToOptions(providers: ProviderStatus[]): ProviderOption[] {
+  const providerOptions: ProviderOption[] = providers.map((provider) => ({
+    id: provider.id,
+    name: provider.name,
+    description: provider.description,
+    isAvailable: provider.isAvailable,
+    cooldownSeconds: provider.cooldownSeconds,
+  }));
+
+  return [AUTO_OPTION, ...providerOptions];
+}
+
+// ============================================================================
+// Sub-Components
+// ============================================================================
+
+/**
+ * Status indicator dot with pulse animation for available providers.
+ *
+ * @param props - Component props
+ * @param props.status - Current status ('available', 'cooldown', 'unknown')
+ * @param props.compact - Whether to render in compact mode
+ * @returns Status indicator element
+ *
+ * @internal
+ */
+function StatusIndicator({
+  status,
+  compact = false,
+}: {
+  status: 'available' | 'cooldown' | 'unknown';
+  compact?: boolean;
+}): ReactElement {
+  const baseClasses = cn(
+    'rounded-full shrink-0',
+    compact ? 'h-1.5 w-1.5' : 'h-2 w-2'
+  );
+
+  switch (status) {
+    case 'available':
+      return (
+        <span className="relative flex">
+          <span
+            className={cn(
+              baseClasses,
+              'bg-[var(--success)]',
+              /* Pulse animation for available status */
+              'animate-[pulse-glow_2s_ease-in-out_infinite]'
+            )}
+          />
+          {/* Outer glow ring for emphasis */}
+          <span
+            className={cn(
+              'absolute inset-0 rounded-full bg-[var(--success)]',
+              'animate-[ping_2s_cubic-bezier(0,0,0.2,1)_infinite] opacity-75'
+            )}
+          />
+          <style>{`
+            @keyframes pulse-glow {
+              0%, 100% { opacity: 1; }
+              50% { opacity: 0.7; }
+            }
+          `}</style>
+        </span>
+      );
+
+    case 'cooldown':
+      return <span className={cn(baseClasses, 'bg-[var(--error)]')} />;
+
+    case 'unknown':
+    default:
+      return (
+        <span
+          className={cn(baseClasses, 'bg-[var(--foreground-muted)] opacity-50')}
+        />
+      );
+  }
+}
+
+/**
+ * Inner countdown timer component that handles the countdown logic.
+ *
+ * This component is designed to be used with a key prop that changes
+ * when initialSeconds changes, causing a remount that resets the countdown.
+ * This pattern avoids calling setState synchronously in useEffect.
+ *
+ * @param props - Component props
+ * @param props.initialSeconds - Starting countdown value in seconds
+ * @param props.compact - Whether to render in compact mode
+ * @returns Countdown display element
+ *
+ * @internal
+ */
+function CooldownTimerInner({
+  initialSeconds,
+  compact = false,
+}: {
+  initialSeconds: number;
+  compact?: boolean;
+}): ReactElement {
+  /* Initialize state with the starting value */
+  const [remainingSeconds, setRemainingSeconds] = useState(
+    () => initialSeconds
+  );
+
+  /* Set up decrement interval - runs once on mount */
+  useEffect(() => {
+    /* Don't set up interval if no time remaining */
+    if (initialSeconds <= 0) {
+      return;
+    }
+
+    /* Set up decrement interval */
+    const intervalId = setInterval(() => {
+      setRemainingSeconds((prev) => {
+        const next = prev - 1;
+        if (next <= 0) {
+          clearInterval(intervalId);
+          return 0;
+        }
+        return next;
+      });
+    }, 1000);
+
+    /* Cleanup on unmount */
+    return () => {
+      clearInterval(intervalId);
+    };
+    /* Empty dependency array - only run on mount */
+    /* eslint-disable-next-line react-hooks/exhaustive-deps */
+  }, []);
+
+  if (remainingSeconds <= 0) {
+    return <></>;
+  }
+
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center gap-1',
+        'font-medium text-[var(--error)]',
+        compact ? 'text-[10px]' : 'text-xs'
+      )}
+      aria-live="polite"
+      aria-atomic="true"
+    >
+      <Clock
+        className={compact ? 'h-2.5 w-2.5' : 'h-3 w-3'}
+        aria-hidden="true"
+      />
+      <span>{formatCooldown(remainingSeconds)}</span>
+    </span>
+  );
+}
+
+/**
+ * Cooldown countdown timer wrapper that handles prop changes via key.
+ *
+ * Uses the key prop pattern to remount the inner component when
+ * initialSeconds changes, which resets the countdown properly without
+ * needing to call setState in useEffect.
+ *
+ * @param props - Component props
+ * @param props.initialSeconds - Starting cooldown value in seconds
+ * @param props.compact - Whether to render in compact mode
+ * @returns Countdown display element
+ *
+ * @internal
+ */
+function CooldownTimer({
+  initialSeconds,
+  compact = false,
+}: {
+  initialSeconds: number;
+  compact?: boolean;
+}): ReactElement {
+  /* Use initialSeconds as key to remount when it changes */
+  return (
+    <CooldownTimerInner
+      key={initialSeconds}
+      initialSeconds={initialSeconds}
+      compact={compact}
+    />
+  );
+}
+
+/**
+ * Skeleton loader for the provider toggle during loading state.
+ *
+ * @param props - Component props
+ * @param props.compact - Whether to render in compact mode
+ * @returns Skeleton element
+ *
+ * @internal
+ */
+function ProviderToggleSkeleton({
+  compact = false,
+}: {
+  compact?: boolean;
+}): ReactElement {
+  return (
+    <div
+      className={cn('flex flex-wrap gap-2', compact ? 'gap-1.5' : 'gap-2')}
+      role="group"
+      aria-label="Loading provider options..."
+    >
+      {/* Render 3 skeleton pills (Auto + 2 providers) */}
+      {[1, 2, 3].map((i) => (
+        <div
+          key={i}
+          className={cn(
+            'animate-pulse rounded-full',
+            'bg-[var(--background-tertiary)]',
+            compact ? 'h-7 w-16' : 'h-9 w-20'
+          )}
+        />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Error state display with refresh button.
+ *
+ * @param props - Component props
+ * @param props.error - Error message to display
+ * @param props.onRefresh - Callback to trigger refresh
+ * @param props.compact - Whether to render in compact mode
+ * @returns Error display element
+ *
+ * @internal
+ */
+function ProviderToggleError({
+  error,
+  onRefresh,
+  compact = false,
+}: {
+  error: string;
+  onRefresh: () => void;
+  compact?: boolean;
+}): ReactElement {
+  return (
+    <div
+      className={cn(
+        'flex items-center gap-2',
+        'text-[var(--error)]',
+        compact ? 'text-xs' : 'text-sm'
+      )}
+      role="alert"
+    >
+      <AlertCircle
+        className={compact ? 'h-3.5 w-3.5' : 'h-4 w-4'}
+        aria-hidden="true"
+      />
+      <span className="max-w-[200px] truncate" title={error}>
+        {error}
+      </span>
+      <button
+        type="button"
+        onClick={onRefresh}
+        className={cn(
+          'inline-flex items-center justify-center',
+          'rounded-full p-1',
+          'text-[var(--foreground-secondary)]',
+          'hover:bg-[var(--background-secondary)] hover:text-[var(--foreground)]',
+          'focus-visible:ring-2 focus-visible:outline-none',
+          'focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2',
+          'focus-visible:ring-offset-[var(--background)]',
+          'transition-colors duration-[var(--transition-fast)]'
+        )}
+        aria-label="Retry loading providers"
+      >
+        <RefreshCw
+          className={compact ? 'h-3 w-3' : 'h-3.5 w-3.5'}
+          aria-hidden="true"
+        />
+      </button>
+    </div>
+  );
+}
+
+/**
+ * Individual provider pill button.
+ *
+ * @param props - Component props
+ * @returns Provider pill element
+ *
+ * @internal
+ */
+function ProviderPill({
+  option,
+  isSelected,
+  onSelect,
+  compact = false,
+  tabIndex,
+  onKeyDown,
+}: {
+  option: ProviderOption;
+  isSelected: boolean;
+  onSelect: (id: string | null) => void;
+  compact?: boolean;
+  tabIndex: number;
+  onKeyDown: (e: KeyboardEvent<HTMLButtonElement>) => void;
+}): ReactElement {
+  const isAuto = option.id === null;
+  const isUnavailable = !option.isAvailable;
+  const hasCooldown =
+    option.cooldownSeconds !== null && option.cooldownSeconds > 0;
+
+  /* Determine status for indicator */
+  const status: 'available' | 'cooldown' | 'unknown' = useMemo(() => {
+    if (isAuto) return 'available';
+    if (hasCooldown) return 'cooldown';
+    if (option.isAvailable) return 'available';
+    return 'unknown';
+  }, [isAuto, hasCooldown, option.isAvailable]);
+
+  /* Handle click */
+  const handleClick = useCallback(() => {
+    /* Allow selection even if unavailable (user might want to see cooldown) */
+    onSelect(option.id);
+  }, [onSelect, option.id]);
+
+  return (
+    <button
+      type="button"
+      role="radio"
+      aria-checked={isSelected}
+      aria-label={`${option.name}${isSelected ? ' (selected)' : ''}${
+        isUnavailable && !isAuto
+          ? hasCooldown
+            ? ` - cooling down for ${formatCooldown(option.cooldownSeconds!)}`
+            : ' - unavailable'
+          : ''
+      }`}
+      tabIndex={tabIndex}
+      onClick={handleClick}
+      onKeyDown={onKeyDown}
+      disabled={false}
+      className={cn(
+        /* Base styles */
+        'relative inline-flex items-center gap-1.5',
+        'rounded-full font-medium whitespace-nowrap',
+        'transition-all duration-[var(--transition-fast)]',
+        'cursor-pointer select-none',
+
+        /* Size variants */
+        compact ? 'h-7 px-2.5 py-1 text-xs' : 'h-9 px-3.5 py-1.5 text-sm',
+
+        /* Focus styles */
+        'focus-visible:ring-2 focus-visible:outline-none',
+        'focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2',
+        'focus-visible:ring-offset-[var(--background)]',
+
+        /* Selected state */
+        isSelected && [
+          'bg-[var(--color-primary-500)] text-white',
+          'shadow-[var(--shadow-md)]',
+          'border-2 border-[var(--color-primary-600)]',
+        ],
+
+        /* Unselected state */
+        !isSelected && [
+          'bg-[var(--background-secondary)]',
+          'border border-[var(--border)]',
+          'text-[var(--foreground-secondary)]',
+          /* Hover - only when not disabled visually */
+          !isUnavailable && [
+            'hover:bg-[var(--background-tertiary)]',
+            'hover:border-[var(--foreground-muted)]',
+            'hover:text-[var(--foreground)]',
+            'hover:scale-[1.02]',
+            'hover:shadow-[var(--shadow-sm)]',
+          ],
+        ],
+
+        /* Unavailable/muted state (not selected) */
+        isUnavailable &&
+          !isSelected &&
+          !isAuto && ['opacity-60', 'cursor-not-allowed']
+      )}
+    >
+      {/* Auto icon for the Auto option */}
+      {isAuto && (
+        <Zap
+          className={cn(
+            compact ? 'h-3 w-3' : 'h-3.5 w-3.5',
+            isSelected ? 'text-white' : 'text-[var(--color-primary-500)]'
+          )}
+          aria-hidden="true"
+        />
+      )}
+
+      {/* Status indicator for non-auto options */}
+      {!isAuto && <StatusIndicator status={status} compact={compact} />}
+
+      {/* Provider name */}
+      <span>{option.name}</span>
+
+      {/* Cooldown timer (only shown for non-auto options in cooldown) */}
+      {hasCooldown && !isAuto && (
+        <CooldownTimer
+          initialSeconds={option.cooldownSeconds!}
+          compact={compact}
+        />
+      )}
+    </button>
+  );
+}
+
+// ============================================================================
+// Main Component
+// ============================================================================
+
+/**
+ * Provider Toggle Component
+ *
+ * A premium horizontal pill/chip layout for selecting LLM providers.
+ * Features real-time status indicators, cooldown timers, and full
+ * keyboard navigation support.
+ *
+ * @remarks
+ * ## Features
+ * - Horizontal pill layout with "Auto" as the first option
+ * - Green pulse dot for available providers
+ * - Red dot with countdown timer for providers in cooldown
+ * - Gray dot for unknown/unavailable status
+ * - Selected state with primary color highlight
+ * - Subtle hover scale and shadow transitions
+ * - Responsive: stacks vertically on mobile
+ *
+ * ## Accessibility
+ * - Radio group semantics for selection
+ * - Full keyboard navigation (arrow keys)
+ * - Proper ARIA labels and states
+ * - Focus indicators meeting WCAG AA
+ * - Screen reader announcements for cooldown timers
+ *
+ * ## State Management
+ * - Uses useProviders hook internally for provider status
+ * - Graceful loading state with skeleton
+ * - Error state with refresh button
+ * - Local countdown timer that decrements every second
+ *
+ * @param props - Component props
+ * @returns Provider toggle element
+ *
+ * @example
+ * // Basic usage
+ * <ProviderToggle />
+ *
+ * @example
+ * // Compact mode for headers
+ * <ProviderToggle compact className="ml-auto" />
+ */
+export function ProviderToggle({
+  className,
+  compact = false,
+}: ProviderToggleProps): ReactElement {
+  const {
+    providers,
+    selectedProvider,
+    selectProvider,
+    isLoading,
+    error,
+    refresh,
+  } = useProviders();
+
+  /* Transform providers to options format */
+  const options = useMemo(() => transformToOptions(providers), [providers]);
+
+  /* Find the index of the currently selected option */
+  const selectedIndex = useMemo(() => {
+    return options.findIndex((opt) => opt.id === selectedProvider);
+  }, [options, selectedProvider]);
+
+  /* Refs for keyboard navigation */
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  /**
+   * Handle keyboard navigation within the radio group.
+   * Supports arrow keys for navigation and Enter/Space for selection.
+   */
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLButtonElement>, currentIndex: number) => {
+      let newIndex = currentIndex;
+      let handled = false;
+
+      switch (e.key) {
+        case 'ArrowRight':
+        case 'ArrowDown':
+          /* Move to next option, wrap around */
+          newIndex = (currentIndex + 1) % options.length;
+          handled = true;
+          break;
+
+        case 'ArrowLeft':
+        case 'ArrowUp':
+          /* Move to previous option, wrap around */
+          newIndex = (currentIndex - 1 + options.length) % options.length;
+          handled = true;
+          break;
+
+        case 'Home':
+          /* Move to first option */
+          newIndex = 0;
+          handled = true;
+          break;
+
+        case 'End':
+          /* Move to last option */
+          newIndex = options.length - 1;
+          handled = true;
+          break;
+      }
+
+      if (handled) {
+        e.preventDefault();
+        e.stopPropagation();
+
+        /* Select the new option */
+        selectProvider(options[newIndex].id);
+
+        /* Focus the new button */
+        const container = containerRef.current;
+        if (container) {
+          const buttons = container.querySelectorAll('button[role="radio"]');
+          const targetButton = buttons[newIndex] as HTMLButtonElement;
+          targetButton?.focus();
+        }
+      }
+    },
+    [options, selectProvider]
+  );
+
+  /* Render loading state */
+  if (isLoading) {
+    return (
+      <div className={className}>
+        <ProviderToggleSkeleton compact={compact} />
+      </div>
+    );
+  }
+
+  /* Render error state */
+  if (error && providers.length === 0) {
+    return (
+      <div className={className}>
+        <ProviderToggleError
+          error={error}
+          onRefresh={refresh}
+          compact={compact}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className={cn(
+        /* Layout - horizontal on desktop, wrap on mobile */
+        'flex flex-wrap items-center',
+        compact ? 'gap-1.5' : 'gap-2',
+        /* Responsive: vertical stack on very small screens */
+        'flex-col items-stretch sm:flex-row sm:items-center',
+        className
+      )}
+      role="radiogroup"
+      aria-label="Select LLM provider"
+    >
+      {options.map((option, index) => (
+        <ProviderPill
+          key={option.id ?? 'auto'}
+          option={option}
+          isSelected={option.id === selectedProvider}
+          onSelect={selectProvider}
+          compact={compact}
+          /* Only the selected option is in tab order (roving tabindex) */
+          tabIndex={index === selectedIndex ? 0 : -1}
+          onKeyDown={(e) => handleKeyDown(e, index)}
+        />
+      ))}
+
+      {/* Refresh button (subtle, at the end) */}
+      <button
+        type="button"
+        onClick={refresh}
+        className={cn(
+          'inline-flex items-center justify-center',
+          'rounded-full',
+          'text-[var(--foreground-muted)]',
+          'hover:bg-[var(--background-secondary)] hover:text-[var(--foreground)]',
+          'focus-visible:ring-2 focus-visible:outline-none',
+          'focus-visible:ring-[var(--border-focus)] focus-visible:ring-offset-2',
+          'focus-visible:ring-offset-[var(--background)]',
+          'transition-all duration-[var(--transition-fast)]',
+          'hover:rotate-180',
+          compact ? 'h-6 w-6' : 'h-7 w-7'
+        )}
+        aria-label="Refresh provider status"
+        title="Refresh provider status"
+      >
+        <RefreshCw
+          className={compact ? 'h-3 w-3' : 'h-3.5 w-3.5'}
+          aria-hidden="true"
+        />
+      </button>
+    </div>
+  );
+}
+
+/* Display name for React DevTools */
+ProviderToggle.displayName = 'ProviderToggle';

frontend/src/components/chat/sidebar.tsx

@@ -0,0 +1,284 @@
+/**
+ * Sidebar Component
+ *
+ * A collapsible left sidebar that displays the current LLM provider
+ * and model information. Follows a modern design similar to VS Code
+ * or Slack sidebars.
+ *
+ * @module components/chat/sidebar
+ * @since 1.0.0
+ *
+ * @example
+ * // Basic usage
+ * <Sidebar />
+ *
+ * @example
+ * // With custom className
+ * <Sidebar className="border-r" />
+ */
+
+'use client';
+
+import {
+  useCallback,
+  useEffect,
+  useState,
+  type ReactElement,
+} from 'react';
+import {
+  ChevronLeft,
+  ChevronRight,
+  Cpu,
+  Info,
+  Zap,
+} from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { useProviders } from '@/hooks';
+
+/**
+ * Props for the Sidebar component.
+ */
+export interface SidebarProps {
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * localStorage key for sidebar collapsed state.
+ * @internal
+ */
+const STORAGE_KEY = 'rag-chatbot-sidebar-collapsed';
+
+/**
+ * Sidebar width constants.
+ * @internal
+ */
+const SIDEBAR_WIDTH = {
+  expanded: 'w-56',
+  collapsed: 'w-12',
+};
+
+/**
+ * Sidebar Component
+ *
+ * A collapsible sidebar showing the current LLM provider and model.
+ * Features:
+ * - Displays provider name and model name
+ * - Collapsible to icon-only mode
+ * - Persists collapse state to localStorage
+ * - Smooth animations
+ */
+export function Sidebar({ className }: SidebarProps): ReactElement {
+  const { providers, selectedProvider } = useProviders();
+
+  // Collapse state with localStorage persistence
+  const [isCollapsed, setIsCollapsed] = useState(false);
+  const [mounted, setMounted] = useState(false);
+
+  // Load collapsed state from localStorage on mount
+  useEffect(() => {
+    setMounted(true);
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored !== null) {
+      setIsCollapsed(stored === 'true');
+    }
+  }, []);
+
+  // Toggle collapse state
+  const toggleCollapsed = useCallback(() => {
+    setIsCollapsed((prev) => {
+      const newValue = !prev;
+      localStorage.setItem(STORAGE_KEY, String(newValue));
+      return newValue;
+    });
+  }, []);
+
+  // Get current provider info
+  const currentProvider = selectedProvider
+    ? providers.find((p) => p.id === selectedProvider)
+    : null;
+
+  const providerName = selectedProvider
+    ? currentProvider?.name || selectedProvider
+    : 'Auto';
+
+  // Use primaryModel from backend API (fetched via useProviders)
+  // Falls back to "Auto-selected" for auto mode or "Loading..." if not yet fetched
+  const modelName = selectedProvider
+    ? currentProvider?.primaryModel || 'Loading...'
+    : 'Auto-selected';
+
+
+  // Don't render until mounted to avoid hydration mismatch
+  if (!mounted) {
+    return (
+      <aside
+        className={cn(
+          SIDEBAR_WIDTH.expanded,
+          'shrink-0',
+          className
+        )}
+      />
+    );
+  }
+
+  return (
+    <aside
+      className={cn(
+        /* Width transition */
+        isCollapsed ? SIDEBAR_WIDTH.collapsed : SIDEBAR_WIDTH.expanded,
+        'shrink-0',
+        /* Transition for smooth collapse */
+        'transition-all duration-200 ease-in-out',
+        /* Border */
+        'border-r border-[var(--border)]/20',
+        /* Background */
+        'bg-[var(--background-secondary)]',
+        /* Flex layout */
+        'flex flex-col',
+        className
+      )}
+    >
+      {/* Header with collapse button */}
+      <div
+        className={cn(
+          'flex items-center justify-between',
+          'px-3 py-3',
+          'border-b border-[var(--border)]/10'
+        )}
+      >
+        {!isCollapsed && (
+          <span className="text-xs font-medium text-[var(--foreground-muted)] uppercase tracking-wider">
+            Model
+          </span>
+        )}
+        <button
+          type="button"
+          onClick={toggleCollapsed}
+          aria-label={isCollapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+          className={cn(
+            'p-1.5 rounded-md',
+            'text-[var(--foreground-muted)]',
+            'hover:bg-[var(--background-tertiary)]',
+            'hover:text-[var(--foreground)]',
+            'transition-colors duration-150',
+            isCollapsed && 'mx-auto'
+          )}
+        >
+          {isCollapsed ? (
+            <ChevronRight className="h-4 w-4" />
+          ) : (
+            <ChevronLeft className="h-4 w-4" />
+          )}
+        </button>
+      </div>
+
+      {/* Provider/Model Info */}
+      <div className="flex-1 px-2 py-3">
+        <div
+          className={cn(
+            'rounded-lg p-3',
+            'bg-[var(--background-tertiary)]/50',
+            'border border-[var(--border)]/10'
+          )}
+        >
+          {isCollapsed ? (
+            /* Collapsed: Icon only */
+            <div className="flex flex-col items-center gap-2">
+              {selectedProvider ? (
+                <Cpu
+                  className="h-5 w-5 text-[var(--color-primary-500)]"
+                  aria-label={`${providerName} - ${modelName}`}
+                />
+              ) : (
+                <Zap
+                  className="h-5 w-5 text-[var(--color-primary-500)]"
+                  aria-label="Auto mode"
+                />
+              )}
+            </div>
+          ) : (
+            /* Expanded: Full info */
+            <div className="space-y-2">
+              {/* Provider icon and name */}
+              <div className="flex items-center gap-2">
+                {selectedProvider ? (
+                  <Cpu className="h-4 w-4 text-[var(--color-primary-500)]" />
+                ) : (
+                  <Zap className="h-4 w-4 text-[var(--color-primary-500)]" />
+                )}
+                <span className="text-sm font-medium text-[var(--foreground)]">
+                  {providerName}
+                </span>
+              </div>
+
+              {/* Model name */}
+              <div className="pl-6">
+                <p className="text-xs text-[var(--foreground-muted)]">
+                  {modelName}
+                </p>
+              </div>
+
+              {/* Status indicator */}
+              {currentProvider && (
+                <div className="flex items-center gap-2 pl-6 pt-1">
+                  <span
+                    className={cn(
+                      'h-1.5 w-1.5 rounded-full',
+                      currentProvider.isAvailable
+                        ? 'bg-green-500'
+                        : 'bg-amber-500'
+                    )}
+                  />
+                  <span className="text-[10px] text-[var(--foreground-muted)]/70">
+                    {currentProvider.isAvailable
+                      ? 'Available'
+                      : `Cooldown: ${currentProvider.cooldownSeconds}s`}
+                  </span>
+                </div>
+              )}
+
+              {/* Auto mode indicator */}
+              {!selectedProvider && (
+                <div className="flex items-center gap-2 pl-6 pt-1">
+                  <span className="h-1.5 w-1.5 rounded-full bg-green-500 animate-pulse" />
+                  <span className="text-[10px] text-[var(--foreground-muted)]/70">
+                    Auto-selecting best
+                  </span>
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+
+        {/* Info section - only when expanded */}
+        {!isCollapsed && (
+          <div
+            className={cn(
+              'mt-3 rounded-lg p-3',
+              'bg-[var(--color-primary-500)]/5',
+              'border border-[var(--color-primary-500)]/10'
+            )}
+          >
+            <div className="flex items-start gap-2">
+              <Info className="h-3.5 w-3.5 text-[var(--color-primary-500)] mt-0.5 shrink-0" />
+              <div className="space-y-1.5">
+                <p className="text-xs text-[var(--foreground-muted)] leading-relaxed">
+                  Shows the currently active model. If a model hits its rate limit,
+                  the system automatically switches to the next available model.
+                </p>
+                <p className="text-xs text-[var(--foreground-muted)]/70 leading-relaxed">
+                  {selectedProvider
+                    ? `Fallback order: ${currentProvider?.allModels?.slice(0, 3).join(' → ') || 'Loading...'}`
+                    : 'Auto mode picks the best available provider automatically.'}
+                </p>
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    </aside>
+  );
+}
+
+Sidebar.displayName = 'Sidebar';

frontend/src/components/chat/source-card.tsx

@@ -0,0 +1,580 @@
+/**
+ * SourceCard Component
+ *
+ * A premium-quality card component for displaying source citations from the
+ * RAG retrieval system. Designed to present document chunk information in a
+ * clean, accessible, and interactive manner.
+ *
+ * This component displays:
+ * - Document heading path (hierarchy breadcrumb)
+ * - Page number badge
+ * - Truncated/expandable source text
+ * - Optional relevance score indicator
+ *
+ * @module components/chat/source-card
+ * @since 1.0.0
+ *
+ * @example
+ * // Basic usage with required props
+ * <SourceCard
+ *   source={{
+ *     id: 'chunk-123',
+ *     headingPath: 'Introduction > Thermal Comfort > PMV Model',
+ *     page: 42,
+ *     text: 'The PMV model predicts the mean response...',
+ *   }}
+ * />
+ *
+ * @example
+ * // With relevance score displayed
+ * <SourceCard
+ *   source={{
+ *     id: 'chunk-456',
+ *     headingPath: 'Chapter 3 > Calculations',
+ *     page: 78,
+ *     text: 'To calculate the operative temperature...',
+ *     score: 0.92,
+ *   }}
+ *   showScore
+ * />
+ *
+ * @example
+ * // Custom truncation length
+ * <SourceCard
+ *   source={source}
+ *   truncateLength={200}
+ * />
+ */
+
+'use client';
+
+import {
+  forwardRef,
+  lazy,
+  memo,
+  Suspense,
+  useCallback,
+  useState,
+  type HTMLAttributes,
+  type KeyboardEvent,
+} from 'react';
+import { cn, truncateText } from '@/lib/utils';
+import type { Source } from '@/types';
+
+/**
+ * Lazy-loaded icons from lucide-react for bundle optimization.
+ *
+ * Icons are only loaded when the component is rendered, reducing
+ * the initial bundle size. This follows the project convention of
+ * lazy-loading heavy dependencies.
+ */
+const FileText = lazy(() =>
+  import('lucide-react').then((mod) => ({ default: mod.FileText }))
+);
+const ChevronDown = lazy(() =>
+  import('lucide-react').then((mod) => ({ default: mod.ChevronDown }))
+);
+const ChevronUp = lazy(() =>
+  import('lucide-react').then((mod) => ({ default: mod.ChevronUp }))
+);
+
+/**
+ * Default maximum characters to display before truncation.
+ * Chosen to show approximately 2-3 lines of text in typical card widths.
+ */
+const DEFAULT_TRUNCATE_LENGTH = 150;
+
+/**
+ * Icon placeholder component for Suspense fallback.
+ * Renders an empty span with icon dimensions to prevent layout shift.
+ *
+ * @internal
+ */
+function IconPlaceholder({
+  className,
+}: {
+  className?: string;
+}): React.ReactElement {
+  return <span className={cn('inline-block h-4 w-4', className)} />;
+}
+
+/**
+ * Props for the SourceCard component.
+ *
+ * Extends standard HTML div attributes for flexibility in styling
+ * and event handling while requiring the core source data.
+ */
+export interface SourceCardProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'id'> {
+  /**
+   * The source object containing citation data from RAG retrieval.
+   * Includes heading path, page number, text excerpt, and optional score.
+   */
+  source: Source;
+
+  /**
+   * Whether to display the relevance score badge.
+   * When true, shows a subtle percentage indicator based on source.score.
+   *
+   * @default false
+   */
+  showScore?: boolean;
+
+  /**
+   * Maximum number of characters to display before truncation.
+   * Text exceeding this length will show a "Show more" button.
+   *
+   * @default 150
+   */
+  truncateLength?: number;
+
+  /**
+   * Initial expanded state for the text content.
+   * When true, the full text is shown by default.
+   *
+   * @default false
+   */
+  defaultExpanded?: boolean;
+}
+
+/**
+ * PageBadge Component
+ *
+ * Renders a small badge displaying the page number from the source document.
+ * Uses muted styling to be informative without dominating the visual hierarchy.
+ *
+ * @param page - The page number to display
+ * @returns Badge element with page number
+ *
+ * @internal
+ */
+function PageBadge({ page }: { page: number }): React.ReactElement {
+  return (
+    <span
+      className={cn(
+        /* Badge layout and sizing */
+        'inline-flex items-center justify-center',
+        'px-2 py-0.5',
+        /* Typography - small and subtle */
+        'text-xs font-medium',
+        'text-[var(--foreground-muted)]',
+        /* Background and border styling */
+        'bg-[var(--background-tertiary)]',
+        'rounded-[var(--radius-sm)]',
+        /* Prevent shrinking in flex containers */
+        'shrink-0'
+      )}
+      /* Provide accessible label for screen readers */
+      aria-label={`Page ${page}`}
+    >
+      Page {page}
+    </span>
+  );
+}
+
+/**
+ * ScoreBadge Component
+ *
+ * Renders an optional relevance score as a percentage badge.
+ * Only visible when showScore prop is true and score exists.
+ * Uses color coding to indicate relevance level.
+ *
+ * @param score - Relevance score from 0-1 (converted to percentage)
+ * @returns Badge element with percentage, or null if no score
+ *
+ * @internal
+ */
+function ScoreBadge({
+  score,
+}: {
+  score: number | undefined;
+}): React.ReactElement | null {
+  /* Don't render if no score provided */
+  if (score === undefined) {
+    return null;
+  }
+
+  /* Convert 0-1 score to percentage for display */
+  const percentage = Math.round(score * 100);
+
+  /**
+   * Determine badge color based on relevance threshold:
+   * - High relevance (>= 80%): Success green
+   * - Medium relevance (>= 60%): Primary purple
+   * - Low relevance (< 60%): Muted gray
+   */
+  const colorClass =
+    percentage >= 80
+      ? 'text-[var(--success)] bg-[var(--success)]/10'
+      : percentage >= 60
+        ? 'text-[var(--color-primary-600)] bg-[var(--color-primary-100)]'
+        : 'text-[var(--foreground-muted)] bg-[var(--background-tertiary)]';
+
+  return (
+    <span
+      className={cn(
+        /* Badge layout and sizing */
+        'inline-flex items-center justify-center',
+        'px-2 py-0.5',
+        /* Typography */
+        'text-xs font-medium',
+        /* Dynamic color based on score */
+        colorClass,
+        /* Border radius */
+        'rounded-[var(--radius-sm)]',
+        /* Prevent shrinking */
+        'shrink-0'
+      )}
+      /* Accessible label explaining the score */
+      aria-label={`Relevance score: ${percentage} percent`}
+    >
+      {percentage}%
+    </span>
+  );
+}
+
+/**
+ * HeadingPath Component
+ *
+ * Renders the document hierarchy breadcrumb with a file icon.
+ * The heading path shows the navigation from document root to the
+ * specific section (e.g., "Chapter 1 > Section 2 > Subsection").
+ *
+ * @param headingPath - The formatted heading hierarchy string
+ * @returns Heading path element with icon
+ *
+ * @internal
+ */
+function HeadingPath({
+  headingPath,
+}: {
+  headingPath: string;
+}): React.ReactElement {
+  return (
+    <div
+      className={cn(
+        /* Flex layout for icon + text alignment */
+        'flex items-start gap-2',
+        /* Allow text to wrap while maintaining alignment */
+        'min-w-0'
+      )}
+    >
+      {/* Document icon with Suspense for lazy loading */}
+      <Suspense fallback={<IconPlaceholder className="mt-0.5 shrink-0" />}>
+        <FileText
+          className={cn(
+            /* Icon sizing */
+            'h-4 w-4',
+            /* Prevent icon from shrinking */
+            'shrink-0',
+            /* Slight top offset to align with text baseline */
+            'mt-0.5',
+            /* Muted color to not dominate */
+            'text-[var(--foreground-muted)]'
+          )}
+          strokeWidth={2}
+          aria-hidden="true"
+        />
+      </Suspense>
+
+      {/* Heading path text */}
+      <span
+        className={cn(
+          /* Typography */
+          'text-sm font-medium leading-snug',
+          'text-[var(--foreground)]',
+          /* Truncate with ellipsis if too long */
+          'line-clamp-2'
+        )}
+      >
+        {headingPath}
+      </span>
+    </div>
+  );
+}
+
+/**
+ * ExpandableText Component
+ *
+ * Renders the source text content with expand/collapse functionality.
+ * Text is truncated by default and can be expanded via button click.
+ * Includes smooth height animation and proper accessibility attributes.
+ *
+ * @param text - The full source text content
+ * @param truncateLength - Maximum characters before truncation
+ * @param expanded - Current expanded state
+ * @param onToggle - Callback when expand/collapse is triggered
+ * @returns Expandable text section with toggle button
+ *
+ * @internal
+ */
+function ExpandableText({
+  text,
+  truncateLength,
+  expanded,
+  onToggle,
+}: {
+  text: string;
+  truncateLength: number;
+  expanded: boolean;
+  onToggle: () => void;
+}): React.ReactElement {
+  /**
+   * Determine if text needs truncation based on length.
+   * If text is shorter than truncateLength, no expand button is needed.
+   */
+  const needsTruncation = text.length > truncateLength;
+
+  /**
+   * Compute displayed text based on expansion state.
+   * Uses the truncateText utility for word-boundary-aware truncation.
+   */
+  const displayedText =
+    expanded || !needsTruncation ? text : truncateText(text, truncateLength);
+
+  /**
+   * Generate unique ID for the text region for aria-controls.
+   * Using a simple approach since each card instance is unique.
+   */
+  const textRegionId = 'source-text-region';
+
+  /**
+   * Handle keyboard interaction for accessibility.
+   * Supports Enter and Space keys for toggle activation.
+   */
+  const handleKeyDown = (event: KeyboardEvent<HTMLButtonElement>): void => {
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      onToggle();
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-2">
+      {/* Text content region with smooth transition */}
+      <p
+        id={textRegionId}
+        className={cn(
+          /* Typography for readability */
+          'text-sm leading-relaxed',
+          'text-[var(--foreground-secondary)]',
+          /* Whitespace handling */
+          'whitespace-pre-wrap break-words',
+          /* Smooth height transition for expand/collapse */
+          'transition-all duration-[var(--transition-normal)]'
+        )}
+      >
+        {displayedText}
+      </p>
+
+      {/* Show more/less toggle button - only if truncation is needed */}
+      {needsTruncation && (
+        <button
+          type="button"
+          onClick={onToggle}
+          onKeyDown={handleKeyDown}
+          aria-expanded={expanded}
+          aria-controls={textRegionId}
+          className={cn(
+            /* Layout - align to end of container */
+            'inline-flex items-center gap-1',
+            'self-end',
+            /* Typography */
+            'text-xs font-medium',
+            'text-[var(--color-primary-text)]',
+            /* Interactive states */
+            'cursor-pointer',
+            'transition-colors duration-[var(--transition-fast)]',
+            'hover:text-[var(--color-primary-600)]',
+            /* Focus styles for accessibility */
+            'rounded-[var(--radius-sm)]',
+            'focus-visible:outline-none',
+            'focus-visible:ring-2',
+            'focus-visible:ring-[var(--border-focus)]',
+            'focus-visible:ring-offset-2',
+            'focus-visible:ring-offset-[var(--background-secondary)]',
+            /* Padding for better click target */
+            'px-1.5 py-0.5',
+            '-mr-1.5'
+          )}
+        >
+          {/* Button label changes based on state */}
+          <span>{expanded ? 'Show less' : 'Show more'}</span>
+
+          {/* Chevron icon indicates expandable action */}
+          <Suspense fallback={<IconPlaceholder className="h-3.5 w-3.5" />}>
+            {expanded ? (
+              <ChevronUp
+                className="h-3.5 w-3.5"
+                strokeWidth={2.5}
+                aria-hidden="true"
+              />
+            ) : (
+              <ChevronDown
+                className="h-3.5 w-3.5"
+                strokeWidth={2.5}
+                aria-hidden="true"
+              />
+            )}
+          </Suspense>
+        </button>
+      )}
+    </div>
+  );
+}
+
+/**
+ * SourceCard Component
+ *
+ * A production-ready card component for displaying source citations
+ * from the RAG retrieval system. Presents document chunks with their
+ * metadata in an accessible, interactive format.
+ *
+ * @remarks
+ * ## Visual Design
+ * - Clean card layout with subtle background differentiation
+ * - Document icon with heading path breadcrumb
+ * - Page number badge in the header
+ * - Expandable text content with smooth animation
+ * - Optional relevance score indicator
+ *
+ * ## Accessibility Features
+ * - Proper ARIA labels on all interactive elements
+ * - `aria-expanded` attribute on expand/collapse button
+ * - `aria-controls` linking button to controlled region
+ * - Keyboard navigation support (Enter/Space to toggle)
+ * - Focus visible styles meeting WCAG 2.1 requirements
+ * - Semantic HTML structure (article element for grouping)
+ *
+ * ## Performance Optimizations
+ * - Lazy-loaded icons to reduce initial bundle size
+ * - React.memo wrapper to prevent unnecessary re-renders
+ * - Efficient state management with useState
+ *
+ * ## Color Contrast (WCAG AA)
+ * - Primary text: 15.7:1 on background-secondary (light mode)
+ * - Secondary text: 6.9:1 on background-secondary (light mode)
+ * - Muted text: 4.55:1 on background-secondary (light mode)
+ * - All interactions maintain required contrast ratios
+ *
+ * @param props - SourceCard component props
+ * @returns React element containing the styled source card
+ *
+ * @see {@link SourceCardProps} for full prop documentation
+ * @see {@link Source} for the source data structure
+ */
+const SourceCard = forwardRef<HTMLDivElement, SourceCardProps>(
+  (
+    {
+      source,
+      showScore = false,
+      truncateLength = DEFAULT_TRUNCATE_LENGTH,
+      defaultExpanded = false,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    /**
+     * Local state for tracking text expansion.
+     * Initialized from defaultExpanded prop.
+     */
+    const [isExpanded, setIsExpanded] = useState(defaultExpanded);
+
+    /**
+     * Memoized toggle handler to prevent unnecessary re-creations.
+     * Uses functional update pattern for state safety.
+     */
+    const handleToggle = useCallback(() => {
+      setIsExpanded((prev) => !prev);
+    }, []);
+
+    return (
+      <article
+        ref={ref}
+        /**
+         * Using article element for semantic grouping of related content.
+         * Each source citation is a self-contained piece of information.
+         */
+        className={cn(
+          /* Card container styling */
+          'relative',
+          'rounded-[var(--radius-sm)]',
+          'bg-[var(--background-secondary)]',
+          'border border-[var(--border)]',
+          /* Padding for content */
+          'p-3 sm:p-4',
+          /* Subtle hover effect for interactive feel */
+          'transition-all duration-[var(--transition-normal)]',
+          'hover:border-[var(--foreground-muted)]',
+          'hover:shadow-[var(--shadow-sm)]',
+          /* Custom classes from props */
+          className
+        )}
+        /* Accessible label describing the source */
+        aria-label={`Source from ${source.headingPath}, page ${source.page}`}
+        {...props}
+      >
+        {/* Header section: heading path + badges */}
+        <header
+          className={cn(
+            /* Flex layout for header content */
+            'flex items-start justify-between gap-3',
+            /* Bottom spacing before text content */
+            'mb-3'
+          )}
+        >
+          {/* Left side: heading path with icon */}
+          <HeadingPath headingPath={source.headingPath} />
+
+          {/* Right side: badges (page number and optional score) */}
+          <div className="flex items-center gap-2 shrink-0">
+            {/* Relevance score badge (conditional) */}
+            {showScore && <ScoreBadge score={source.score} />}
+
+            {/* Page number badge (always shown) */}
+            <PageBadge page={source.page} />
+          </div>
+        </header>
+
+        {/* Divider line between header and content */}
+        <hr
+          className={cn(
+            'border-t border-[var(--border)]',
+            '-mx-3 sm:-mx-4',
+            'mb-3'
+          )}
+          aria-hidden="true"
+        />
+
+        {/* Content section: expandable text */}
+        <ExpandableText
+          text={source.text}
+          truncateLength={truncateLength}
+          expanded={isExpanded}
+          onToggle={handleToggle}
+        />
+      </article>
+    );
+  }
+);
+
+/* Display name for React DevTools debugging */
+SourceCard.displayName = 'SourceCard';
+
+/**
+ * Memoized SourceCard for performance optimization.
+ *
+ * Since source cards are typically rendered in lists and their content
+ * rarely changes after initial render, memoization prevents unnecessary
+ * re-renders when sibling components update.
+ *
+ * The component re-renders when:
+ * - source object reference changes
+ * - showScore, truncateLength, or defaultExpanded props change
+ * - className or other HTML attributes change
+ */
+const MemoizedSourceCard = memo(SourceCard);
+
+/* Export both versions - use Memoized for lists, regular for single usage */
+export { SourceCard, MemoizedSourceCard };