@aigentic/ruflo 3.7.0-alpha.69

package/src/ruvocal/docs/adr/ADR-029-HUGGINGFACE-CHAT-UI-CLOUD-RUN.md

@@ -0,0 +1,1236 @@
+# ADR-029: HuggingFace Chat UI on Cloud Run — chat.conveyorclaims.ai
+
+## Status
+Implemented (2026-02-26), Updated (2026-03-04)
+
+## Date
+2026-02-26
+
+## Deployed Services
+
+| Service | URL | Status |
+|---------|-----|--------|
+| **HF Chat UI** | https://hf-chat-ui-245235083640.us-central1.run.app | Live |
+| **Custom Domain** | https://chat.conveyorclaims.ai | Live (SSL: Google Trust Services) |
+| **MCP Bridge** | https://mcp-bridge-hwqrrwrlna-uc.a.run.app | Live (5 tools) |
+
+## Context
+
+The current chat system (`extensions-cloudrun/apps/chat-system`) is a custom React + Vite SPA backed by Gemini. While it serves internal workflow needs well (ADR-014, ADR-024, ADR-027), we need a **production-grade, multi-model chat interface** at `chat.conveyorclaims.ai` that:
+
+1. Exposes **GPT-5 family models** (gpt-5, gpt-5-mini, gpt-5-nano, gpt-5-pro, gpt-5.1, gpt-5.2) plus multi-provider models (Google Gemini, Anthropic Claude) using **existing Google Secret Manager keys**
+2. Integrates with **existing Cloud Functions** (airtable-agent, db-query-agent, simulation-agent, case-manager, workflow-search) via MCP tool calling
+3. Connects to **ruvector-postgres** (10.128.0.2) for vector search over workflow documents (384d all-MiniLM-L6-v2 embeddings, 311 chunks) — all tool/data operations go through PostgreSQL, NOT MongoDB
+4. Provides conversation persistence, authentication, and a polished UI out of the box
+5. Deploys as a new Cloud Run service alongside the existing chat-system — no disruption
+
+### Database Strategy: Hybrid PostgreSQL + MongoDB
+
+HuggingFace Chat UI **requires MongoDB** for its internal persistence layer (conversations, users, sessions, assistants). This cannot be swapped for PostgreSQL without forking the project. However, **all business data and tool operations** route through ruvector-postgres via the MCP Bridge:
+
+| Layer | Database | Purpose |
+|-------|----------|---------|
+| **Chat UI internals** | MongoDB (lightweight sidecar or Atlas free tier) | Conversations, user sessions, assistant configs |
+| **Business data & tools** | ruvector-postgres (10.128.0.2) | Workflow search, case data, analytics, embeddings |
+| **AI provider keys** | Google Secret Manager | `openai-api-key`, `anthropic-api-key`, `google-api-key` |
+
+MongoDB handles only what Chat UI needs internally. All the **real work** — workflow search, case management, analytics, simulations — flows through the existing ruvector-postgres via MCP tools. The MongoDB instance can run as a sidecar container on the same Cloud Run service using the bundled `chat-ui-db` image, requiring **zero additional infrastructure**.
+
+### Multi-Provider Strategy via Google Secret Manager
+
+All AI provider API keys already exist in Google Secret Manager (ADR-004). Chat UI will pull these at runtime:
+
+| Secret ID | Provider | Models |
+|-----------|----------|--------|
+| `openai-api-key` | OpenAI | GPT-5.2, GPT-5, GPT-5-mini, GPT-5-nano, GPT-4o, o3 |
+| `anthropic-api-key` | Anthropic | Claude (when credits refilled) |
+| `google-api-key` | Google | Gemini 2.5 Pro/Flash (when key renewed) |
+
+### Why HuggingFace Chat UI
+
+[HuggingFace Chat UI](https://github.com/huggingface/chat-ui) (Apache 2.0, 10,400+ GitHub stars) is the open-source codebase powering HuggingChat. It provides:
+
+- **Native OpenAI-compatible API support** — connects directly to `api.openai.com/v1`, auto-discovers all available models
+- **MCP (Model Context Protocol) tool calling** — exposes external APIs as callable tools from within chat
+- **Multi-model selector** — users pick from GPT-5, GPT-5-mini, GPT-4o, etc. in a dropdown
+- **Smart routing ("Omni")** — auto-selects the best model per query
+- **Built-in web search + RAG** — retrieval-augmented generation with search grounding
+- **MongoDB-backed persistence** — conversation history, user sessions, assistants (bundled sidecar option eliminates external dependency)
+- **OpenID Connect auth** — Google OAuth integration
+- **SvelteKit SSR** — fast, server-rendered UI with streaming responses
+- **Docker-ready** — pre-built images at `ghcr.io/huggingface/chat-ui`
+- **Whisper voice transcription** — speech-to-text input
+
+This eliminates months of custom UI development while providing a superior chat experience.
+
+### Why NOT Modify the Existing Chat System
+
+| Factor | Existing Chat System | HuggingFace Chat UI |
+|--------|---------------------|-------------------|
+| AI Provider | Gemini-only (tightly coupled) | Any OpenAI-compatible API |
+| Model switching | None (ADR-028 proposes abstraction) | Built-in multi-model selector |
+| Conversation persistence | LocalStorage only | MongoDB sidecar + ruvector-postgres for tools |
+| Tool calling | Custom FunctionExecutor | MCP standard protocol |
+| Authentication | Custom Google OAuth | OpenID Connect (standard) |
+| Voice input | None | Whisper transcription |
+| Web search | None | Built-in RAG |
+| Maintenance burden | Custom React/Vite SPA | Community-maintained OSS |
+
+The existing chat system continues serving its current role. This ADR creates a **parallel, GPT-5-powered interface** at a separate domain.
+
+## Decision
+
+Deploy HuggingFace Chat UI as a new Cloud Run service (`hf-chat-ui`) with:
+- GPT-5 model family via OpenAI API
+- Custom MCP server bridging to existing Cloud Functions
+- MongoDB Atlas for conversation persistence
+- Google OAuth via OpenID Connect
+- Custom domain mapping to `chat.conveyorclaims.ai`
+- VPC connector for ruvector-postgres access
+
+---
+
+## Architecture
+
+```
+                         ┌─────────────────────────────┐
+                         │    chat.conveyorclaims.ai    │
+                         │   (Cloud Run Domain Mapping) │
+                         └──────────────┬──────────────┘
+                                        │ HTTPS
+                                        ▼
+┌───────────────────────────────────────────────────────────────────────┐
+│                    Cloud Run: hf-chat-ui                              │
+│                    ghcr.io/huggingface/chat-ui-db                     │
+│                    Port 3000, 2Gi RAM, 2 CPU                         │
+│                    us-central1, VPC: conveyor-connector               │
+│                                                                       │
+│  ┌─────────────┐  ┌──────────────┐  ┌─────────────┐  ┌───────────┐  │
+│  │  SvelteKit  │  │  MCP Client  │  │  Multi-LLM  │  │  MongoDB  │  │
+│  │  Frontend   │  │  (Tool Call) │  │  Provider   │  │  Sidecar  │  │
+│  └──────┬──────┘  └──────┬───────┘  └──────┬──────┘  └───────────┘  │
+│         │                │                  │                         │
+└─────────┼────────────────┼──────────────────┼─────────────────────────┘
+          │                │                  │
+          │                │          ┌───────┼───────────────┐
+          │                │          │       │               │
+          │                ▼          ▼       ▼               ▼
+          │       ┌──────────────┐  ┌──────┐ ┌────────┐ ┌─────────┐
+          │       │ MCP Bridge   │  │OpenAI│ │ Google │ │Anthropic│
+          │       │ (Cloud Run)  │  │ API  │ │Gemini  │ │ Claude  │
+          │       │              │  │      │ │ API    │ │ API     │
+          │       │ Routes to:   │  │gpt-5 │ │gemini  │ │claude   │
+          │       │ Cloud Fns +  │  │gpt-5m│ │2.5-pro │ │sonnet-4 │
+          │       │ ruvector-pg  │  │gpt-4o│ │2.5-fl  │ │         │
+          │       └──────┬───────┘  │o3    │ │        │ │         │
+          │              │          └──────┘ └────────┘ └─────────┘
+          │              ▼               Keys from Google Secret Manager
+          │  ┌───────────────────────────────────┐
+          │  │      Existing Cloud Functions      │
+          │  │      (No Changes Required)         │
+          │  │                                    │
+          │  │  • airtable-agent                  │
+          │  │  • db-query-agent                  │
+          │  │  • case-manager                    │
+          │  │  • simulation-agent                │
+          │  │  • workflow-search                 │
+          │  └───────────────┬───────────────────┘
+          │                  │ VPC (10.128.0.0/20)
+          │                  ▼
+          │  ┌───────────────────────────────────┐
+          │  │     ruvector-postgres VM           │
+          └─▶│     10.128.0.2:5432               │
+             │     PostgreSQL 17.7 + ruvector    │
+             │                                    │
+             │  PRIMARY DATA STORE:               │
+             │  • workflow_chunks (311 rows)      │
+             │  • embeddings (320 vectors, 384d) │
+             │  • HNSW index (m=16, ef=64)       │
+             │  • Case data, analytics, metrics  │
+             └───────────────────────────────────┘
+```
+
+---
+
+## Implementation
+
+### Phase 1: MongoDB Sidecar (Bundled with Chat UI)
+
+HuggingFace Chat UI requires MongoDB for internal persistence (conversations, users, sessions). Rather than adding an external MongoDB dependency, we use the **bundled `chat-ui-db` image** which includes MongoDB as a sidecar process. Data is persisted via a Cloud Run volume mount.
+
+**Why sidecar, not Atlas:**
+- Zero additional infrastructure or accounts
+- No network latency (localhost connection)
+- All business data still lives in ruvector-postgres via MCP tools
+- MongoDB only stores lightweight chat UI metadata
+- If we outgrow this, upgrade to Atlas later (just change `MONGODB_URL`)
+
+**Configuration:**
+```ini
+# Bundled MongoDB uses local storage — no connection string needed
+# The chat-ui-db image starts MongoDB internally on localhost:27017
+MONGODB_URL=mongodb://localhost:27017
+MONGODB_DB_NAME=conveyor-chat
+```
+
+**Volume mount for persistence** (Cloud Run 2nd gen):
+```bash
+# Data persists across container restarts via /data volume
+# The chat-ui-db image stores MongoDB data at /data/db
+```
+
+**Upgrade path:** If conversation volume grows beyond what a sidecar can handle, switch to MongoDB Atlas by updating `MONGODB_URL` in Secret Manager — zero code changes.
+
+### Why MongoDB Cannot Be Avoided
+
+HuggingFace Chat UI is **hardcoded to MongoDB** — its data layer uses MongoDB queries, aggregations, and GridFS throughout the SvelteKit backend. Replacing it with PostgreSQL would require forking the entire project. The sidecar approach (`chat-ui-db` image) bundles MongoDB **inside the same container**, so:
+
+- No external MongoDB service to manage
+- No additional infrastructure cost
+- No MongoDB Atlas account needed
+- Data lives on the container's ephemeral storage (conversations are lightweight and regenerable)
+- All **business-critical data** (cases, workflows, embeddings, analytics) stays in ruvector-postgres
+
+Think of MongoDB here as an internal implementation detail of Chat UI — like SQLite in a desktop app. The user never interacts with it directly. Ruvector-postgres remains the **single source of truth** for all Conveyor data.
+
+---
+
+### Phase 2: MCP Bridge Server
+
+The MCP Bridge Server exposes existing Cloud Functions as MCP-compatible tools that Chat UI can call. This is a lightweight Node.js service deployed as a separate Cloud Run service.
+
+**File: `infrastructure/gcp/mcp-bridge/index.js`**
+
+```javascript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { z } from "zod";
+
+const CLOUD_FUNCTIONS = {
+  airtable: "https://airtable-agent-hwqrrwrlna-uc.a.run.app",
+  dbQuery:  "https://db-query-agent-hwqrrwrlna-uc.a.run.app",
+  caseManager: "https://case-manager-hwqrrwrlna-uc.a.run.app",
+  simulation: "https://simulation-agent-hwqrrwrlna-uc.a.run.app",
+  workflowSearch: "https://us-central1-new-project-473022.cloudfunctions.net/workflow-search",
+};
+
+const server = new McpServer({
+  name: "conveyor-tools",
+  version: "1.0.0",
+});
+
+// Tool: Search workflow documents (vector search via ruvector-postgres)
+server.tool(
+  "search_workflows",
+  "Search CLG workflow procedures, FAQs, and case management steps using semantic search. Returns relevant workflow steps for a given query.",
+  {
+    query: z.string().describe("Natural language query about workflow procedures"),
+    limit: z.number().optional().default(5).describe("Max results to return"),
+  },
+  async ({ query, limit }) => {
+    const resp = await fetch(CLOUD_FUNCTIONS.workflowSearch, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ action: "search", query, limit }),
+    });
+    const data = await resp.json();
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Tool: Query database analytics
+server.tool(
+  "query_database",
+  "Run analytics queries against the PostgreSQL database. Supports case metrics, revenue forecasts, and trend analysis.",
+  {
+    query: z.string().describe("Natural language analytics query"),
+    type: z.enum(["metrics", "forecast", "trend", "custom"]).optional().default("metrics"),
+  },
+  async ({ query, type }) => {
+    const resp = await fetch(CLOUD_FUNCTIONS.dbQuery, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query, type }),
+    });
+    const data = await resp.json();
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Tool: Case management operations
+server.tool(
+  "manage_case",
+  "Look up case status, get next steps, list cases, or perform case management operations via Airtable.",
+  {
+    action: z.enum(["status", "list", "next_steps", "update"]).describe("Case action"),
+    caseId: z.string().optional().describe("Case ID (e.g., C-02420)"),
+    filters: z.record(z.string()).optional().describe("Filter criteria for list action"),
+  },
+  async ({ action, caseId, filters }) => {
+    const resp = await fetch(CLOUD_FUNCTIONS.caseManager, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ action, caseId, filters }),
+    });
+    const data = await resp.json();
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Tool: Run RL simulations
+server.tool(
+  "run_simulation",
+  "Run reinforcement learning strategy simulations for case settlement optimization. Uses Q-learning and Monte Carlo methods.",
+  {
+    scenario: z.string().describe("Simulation scenario description"),
+    episodes: z.number().optional().default(1000).describe("Number of simulation episodes"),
+    strategy: z.enum(["q_learning", "monte_carlo", "policy_gradient"]).optional().default("q_learning"),
+  },
+  async ({ scenario, episodes, strategy }) => {
+    const resp = await fetch(CLOUD_FUNCTIONS.simulation, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ scenario, episodes, strategy }),
+    });
+    const data = await resp.json();
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Tool: Airtable CRUD
+server.tool(
+  "airtable_query",
+  "Query or update Airtable records. Supports listing cases, clients, carriers, and performing CRUD operations.",
+  {
+    action: z.enum(["list", "get", "create", "update"]).describe("CRUD action"),
+    table: z.string().describe("Airtable table name (e.g., Cases, Clients, Carriers)"),
+    recordId: z.string().optional().describe("Record ID for get/update"),
+    filters: z.record(z.string()).optional().describe("Filter criteria"),
+    fields: z.record(z.unknown()).optional().describe("Fields for create/update"),
+  },
+  async ({ action, table, recordId, filters, fields }) => {
+    const resp = await fetch(CLOUD_FUNCTIONS.airtable, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ action, table, recordId, filters, fields }),
+    });
+    const data = await resp.json();
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Express HTTP transport
+const app = express();
+
+app.post("/mcp", async (req, res) => {
+  const transport = new StreamableHTTPServerTransport("/mcp");
+  await server.connect(transport);
+  await transport.handleRequest(req, res);
+});
+
+app.get("/health", (_, res) => res.json({ status: "ok" }));
+
+app.listen(3001, () => console.log("MCP Bridge running on :3001"));
+```
+
+**Deploy:**
+```bash
+gcloud run deploy mcp-bridge \
+  --source=infrastructure/gcp/mcp-bridge \
+  --platform=managed \
+  --region=us-central1 \
+  --port=3001 \
+  --memory=512Mi \
+  --cpu=1 \
+  --min-instances=0 \
+  --max-instances=5 \
+  --vpc-connector=conveyor-connector \
+  --allow-unauthenticated
+```
+
+---
+
+### Phase 3: MCP Tool Servers (3 Sources)
+
+Chat UI supports multiple MCP servers simultaneously. We configure **three** to give GPT-5 full access to Conveyor's data ecosystem:
+
+#### MCP Server 1: Conveyor Bridge (Custom — Cloud Functions + ruvector-postgres)
+
+The custom MCP Bridge from Phase 2. Provides 5 tools:
+
+| Tool | Backend | Purpose |
+|------|---------|---------|
+| `search_workflows` | workflow-search → ruvector-postgres | Semantic search over CLG workflow docs (311 chunks, 384d HNSW) |
+| `query_database` | db-query-agent → ruvector-postgres | SQL analytics, revenue forecasts, trend analysis |
+| `manage_case` | case-manager → Airtable | Case status lookup, next steps, updates |
+| `run_simulation` | simulation-agent | RL strategy simulations (Q-learning, Monte Carlo) |
+| `airtable_query` | airtable-agent → Airtable | Generic Airtable CRUD across all tables |
+
+#### MCP Server 2: Official Airtable MCP
+
+[Airtable's official MCP server](https://support.airtable.com/docs/using-the-airtable-mcp-server) provides **direct base access** — no custom bridge needed. This gives GPT-5 full schema awareness and natural language querying.
+
+**Capabilities:**
+- List all bases, tables, fields, and views
+- Read, create, update, delete records
+- Search records with filters
+- Schema inspection (field types, options, linked records)
+- No additional infrastructure — hosted by Airtable
+
+**Secret:** `airtable-api-key` (already in Google Secret Manager)
+
+```
+URL: https://mcp.airtable.com/v0/mcp
+Auth: Bearer ${AIRTABLE_API_KEY}
+```
+
+> **Why both Airtable MCP AND the Conveyor Bridge airtable tool?** The official Airtable MCP gives raw CRUD access — GPT-5 can browse schemas and build ad-hoc queries. The Conveyor Bridge `manage_case` tool provides **structured, pre-built** case management workflows. Users benefit from both: exploration via Airtable MCP, workflow-guided operations via the bridge.
+
+#### MCP Server 3: Google Drive MCP
+
+[Google's official MCP for Drive](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) provides access to the CLG Workflow shared drive documents.
+
+**Capabilities:**
+- Search files across Drive (including shared drives)
+- Read document contents (Docs, Sheets, Slides)
+- List files in folders
+- Read Google Sheets cells and ranges
+- Access the 🔴CLG Workflow shared drive (0AMTB1wrVg9HLUk9PVA)
+
+**Secrets:** `google-client-id`, `google-client-secret` (both in Secret Manager)
+
+```
+URL: https://mcp.googleapis.com/v1/drive
+Auth: OAuth2 service account or user token
+```
+
+> **Why both Google Drive MCP AND the workflow-search tool?** The workflow-search tool provides **vector-indexed semantic search** (HNSW, <50ms) over pre-chunked workflow documents. The Google Drive MCP provides **raw file access** — read any document, list folders, access spreadsheets. Use workflow-search for "what's the process for X?" and Google Drive MCP for "show me the intake form template."
+
+#### Combined Tool Landscape
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    HF Chat UI — MCP Clients                      │
+│                                                                   │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │ Conveyor Bridge  │  │ Airtable MCP   │  │ Google Drive MCP│  │
+│  │ (Custom)         │  │ (Official)      │  │ (Google)        │  │
+│  │                  │  │                 │  │                 │  │
+│  │ • search_wf      │  │ • list_bases   │  │ • search_files  │  │
+│  │ • query_db       │  │ • list_tables  │  │ • read_doc      │  │
+│  │ • manage_case    │  │ • read_records │  │ • list_folder   │  │
+│  │ • run_sim        │  │ • create_record│  │ • read_sheets   │  │
+│  │ • airtable_query │  │ • update_record│  │ • get_metadata  │  │
+│  │                  │  │ • search       │  │                 │  │
+│  └────────┬─────────┘  └───────┬────────┘  └───────┬─────────┘  │
+│           │                    │                    │             │
+└───────────┼────────────────────┼────────────────────┼─────────────┘
+            │                    │                    │
+            ▼                    ▼                    ▼
+   Cloud Functions +      Airtable API        Google Drive API
+   ruvector-postgres      (airtable.com)      (googleapis.com)
+```
+
+---
+
+### Phase 4: Multi-Provider Model Configuration
+
+All API keys are pulled from **Google Secret Manager** at runtime via Cloud Run `--set-secrets`. The MODELS environment variable configures multi-provider access.
+
+#### Secrets Used (all already exist in Secret Manager)
+
+| Secret ID | Env Var | Provider |
+|-----------|---------|----------|
+| `openai-api-key` | `OPENAI_API_KEY` | OpenAI (GPT-5 family) |
+| `anthropic-api-key` | `ANTHROPIC_API_KEY` | Anthropic (Claude) |
+| `google-api-key` | `GOOGLE_API_KEY` | Google (Gemini) |
+
+#### Model Lineup
+
+```ini
+MODELS=`[
+  {
+    "name": "gpt-5.2",
+    "id": "gpt-5.2",
+    "displayName": "GPT-5.2 (Latest)",
+    "description": "OpenAI's latest flagship model. Best for complex reasoning and analysis.",
+    "supportsTools": true,
+    "parameters": {
+      "temperature": 0.7,
+      "max_new_tokens": 4096
+    },
+    "endpoints": [{
+      "type": "openai",
+      "baseURL": "https://api.openai.com/v1"
+    }]
+  },
+  {
+    "name": "gpt-5.2-pro",
+    "id": "gpt-5.2-pro",
+    "displayName": "GPT-5.2 Pro",
+    "description": "Pro tier with extended reasoning. Best for complex case analysis.",
+    "supportsTools": true,
+    "parameters": {
+      "temperature": 0.5,
+      "max_new_tokens": 8192
+    },
+    "endpoints": [{
+      "type": "openai",
+      "baseURL": "https://api.openai.com/v1"
+    }]
+  },
+  {
+    "name": "gpt-5",
+    "id": "gpt-5",
+    "displayName": "GPT-5",
+    "description": "Strong general-purpose reasoning. Good balance of speed and quality.",
+    "supportsTools": true,
+    "parameters": {
+      "temperature": 0.7,
+      "max_new_tokens": 4096
+    },
+    "endpoints": [{
+      "type": "openai",
+      "baseURL": "https://api.openai.com/v1"
+    }]
+  },
+  {
+    "name": "gpt-5-mini",
+    "id": "gpt-5-mini",
+    "displayName": "GPT-5 Mini",
+    "description": "Fast and cost-effective. Great for FAQ lookups and simple workflow queries.",
+    "supportsTools": true,
+    "parameters": {
+      "temperature": 0.7,
+      "max_new_tokens": 4096
+    },
+    "endpoints": [{
+      "type": "openai",
+      "baseURL": "https://api.openai.com/v1"
+    }]
+  },
+  {
+    "name": "gpt-5-nano",
+    "id": "gpt-5-nano",
+    "displayName": "GPT-5 Nano",
+    "description": "Ultra-fast for simple queries. Lowest cost per token.",
+    "supportsTools": true,
+    "parameters": {
+      "temperature": 0.7,
+      "max_new_tokens": 2048
+    },
+    "endpoints": [{
+      "type": "openai",
+      "baseURL": "https://api.openai.com/v1"
+    }]
+  },
+  {
+    "name": "gpt-4o",
+    "id": "gpt-4o",
+    "displayName": "GPT-4o (Multimodal)",
+    "description": "Multimodal model. Upload images of documents, forms, or damage photos.",
+    "multimodal": true,
+    "supportsTools": true,
+    "parameters": {
+      "temperature": 0.5,
+      "max_new_tokens": 4096
+    },
+    "endpoints": [{
+      "type": "openai",
+      "baseURL": "https://api.openai.com/v1"
+    }]
+  },
+  {
+    "name": "o3",
+    "id": "o3",
+    "displayName": "o3 (Reasoning)",
+    "description": "Advanced reasoning model. Best for complex legal/financial analysis.",
+    "supportsTools": false,
+    "parameters": {
+      "max_new_tokens": 4096
+    },
+    "endpoints": [{
+      "type": "openai",
+      "baseURL": "https://api.openai.com/v1"
+    }]
+  },
+  {
+    "name": "gemini-2.5-pro",
+    "id": "gemini-2.5-pro",
+    "displayName": "Gemini 2.5 Pro (Google)",
+    "description": "Google's most capable model. Already used in the existing chat system.",
+    "supportsTools": true,
+    "parameters": {
+      "temperature": 0.7,
+      "max_new_tokens": 4096
+    },
+    "endpoints": [{
+      "type": "openai",
+      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai",
+      "apiKey": "${GOOGLE_API_KEY}"
+    }]
+  },
+  {
+    "name": "gemini-2.5-flash",
+    "id": "gemini-2.5-flash",
+    "displayName": "Gemini 2.5 Flash (Google)",
+    "description": "Google's fast model. Good for quick workflow lookups.",
+    "supportsTools": true,
+    "parameters": {
+      "temperature": 0.7,
+      "max_new_tokens": 4096
+    },
+    "endpoints": [{
+      "type": "openai",
+      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai",
+      "apiKey": "${GOOGLE_API_KEY}"
+    }]
+  },
+  {
+    "name": "claude-sonnet-4",
+    "id": "claude-sonnet-4",
+    "displayName": "Claude Sonnet 4 (Anthropic)",
+    "description": "Anthropic's balanced model. Strong instruction following and coding.",
+    "supportsTools": true,
+    "parameters": {
+      "temperature": 0.7,
+      "max_new_tokens": 4096
+    },
+    "endpoints": [{
+      "type": "openai",
+      "baseURL": "https://api.anthropic.com/v1",
+      "apiKey": "${ANTHROPIC_API_KEY}",
+      "defaultHeaders": {
+        "anthropic-version": "2023-06-01"
+      }
+    }]
+  }
+]`
+```
+
+> **Note:** Google and Anthropic keys are currently expired/out of credits (tested 2026-02-26). Models will show as unavailable until keys are renewed. OpenAI GPT-5 models are **confirmed working** with $100 balance. Chat UI gracefully handles unavailable providers — users simply see those models greyed out.
+
+---
+
+### Phase 4: Chat UI Cloud Run Deployment
+
+#### 4a. Secrets Setup (All Already Exist)
+
+All required secrets already exist in Google Secret Manager (verified 2026-02-26). Just verify access:
+
+```bash
+# All 8 secrets needed for hf-chat-ui
+SECRETS=(
+  openai-api-key        # GPT-5 models
+  anthropic-api-key     # Claude models
+  google-api-key        # Gemini models
+  airtable-api-key      # Airtable MCP
+  airtable-base-id      # Airtable base reference
+  google-client-id      # Google OAuth + Drive MCP
+  google-client-secret   # Google OAuth + Drive MCP
+  gemini-api-key        # Backup Gemini key
+)
+
+# Verify all secrets exist
+for secret in "${SECRETS[@]}"; do
+  echo -n "$secret: "
+  gcloud secrets versions access latest --secret="$secret" \
+    --project=new-project-473022 2>/dev/null | head -c 12 && echo "... ✓" || echo "MISSING"
+done
+
+# Grant access to compute service account
+for secret in "${SECRETS[@]}"; do
+  gcloud secrets add-iam-policy-binding "$secret" \
+    --project=new-project-473022 \
+    --member="serviceAccount:245235083640-compute@developer.gserviceaccount.com" \
+    --role="roles/secretmanager.secretAccessor" \
+    --quiet 2>/dev/null || true
+done
+```
+
+**Secrets inventory for this deployment:**
+
+| Secret | Purpose | Status |
+|--------|---------|--------|
+| `openai-api-key` | GPT-5 model access | Active ($100 balance) |
+| `anthropic-api-key` | Claude model access | Needs credits |
+| `google-api-key` | Gemini model access | Needs renewal |
+| `airtable-api-key` | Airtable MCP direct access | Active |
+| `airtable-base-id` | Airtable base reference | Active |
+| `google-client-id` | Google OAuth + Drive MCP | Active |
+| `google-client-secret` | Google OAuth + Drive MCP | Active |
+| `gemini-api-key` | Backup Gemini key | Active |
+
+#### 4b. Environment File
+
+**File: `infrastructure/gcp/hf-chat-ui/.env.production`**
+
+```ini
+# ── Model Provider ──────────────────────────────────────
+OPENAI_BASE_URL=https://api.openai.com/v1
+# OPENAI_API_KEY injected from Secret Manager
+
+# ── Database ────────────────────────────────────────────
+# MONGODB_URL injected from Secret Manager
+MONGODB_DB_NAME=conveyor-chat
+
+# ── Branding ────────────────────────────────────────────
+PUBLIC_APP_NAME=Conveyor AI
+PUBLIC_APP_DESCRIPTION=Insurance Case Management & Revenue Operations Assistant powered by GPT-5
+PUBLIC_ORIGIN=https://chat.conveyorclaims.ai
+
+# ── Authentication (Google OAuth) ───────────────────────
+OPENID_PROVIDER_URL=https://accounts.google.com
+OPENID_CLIENT_ID=245235083640-gkbo4otq57lqeisuigcat0bg037f49oc.apps.googleusercontent.com
+# OPENID_CLIENT_SECRET injected from Secret Manager
+OPENID_SCOPES=openid profile email
+OPENID_NAME_CLAIM=name
+COOKIE_SECURE=true
+COOKIE_SAMESITE=lax
+
+# ── MCP Tools (3 servers: Custom Bridge + Airtable + Google Drive) ──
+MCP_SERVERS=`[
+  {
+    "name": "Conveyor Tools",
+    "description": "Workflow search, DB analytics, case management, simulations via ruvector-postgres and Cloud Functions",
+    "url": "https://mcp-bridge-hwqrrwrlna-uc.a.run.app/mcp"
+  },
+  {
+    "name": "Airtable",
+    "description": "Direct Airtable base access — browse tables, search records, create/update cases, view schemas",
+    "url": "https://mcp.airtable.com/v0/mcp",
+    "headers": {
+      "Authorization": "Bearer ${AIRTABLE_API_KEY}"
+    }
+  },
+  {
+    "name": "Google Drive",
+    "description": "Search and read CLG Workflow documents, forms, and templates from Google Drive shared folders",
+    "url": "https://mcp.googleapis.com/v1/drive",
+    "headers": {
+      "Authorization": "Bearer ${GOOGLE_DRIVE_TOKEN}"
+    }
+  }
+]`
+MCP_TOOL_TIMEOUT_MS=30000
+
+# ── Smart Router ────────────────────────────────────────
+LLM_ROUTER_FALLBACK_MODEL=gpt-5
+LLM_ROUTER_ENABLE_TOOLS=true
+LLM_ROUTER_TOOLS_MODEL=gpt-5.2
+PUBLIC_LLM_ROUTER_DISPLAY_NAME=Auto (Omni)
+PUBLIC_LLM_ROUTER_ALIAS_ID=omni
+
+# ── Voice ───────────────────────────────────────────────
+TRANSCRIPTION_MODEL=openai/whisper-large-v3-turbo
+
+# ── Web Search ──────────────────────────────────────────
+USE_LOCAL_WEBSEARCH=true
+
+# ── Features ────────────────────────────────────────────
+LLM_SUMMARIZATION=true
+ENABLE_DATA_EXPORT=true
+ALLOW_IFRAME=false
+
+# ── Rate Limits ─────────────────────────────────────────
+USAGE_LIMITS={"messagesPerMinute": 20, "conversations": 100, "tools": 50}
+
+# ── System Prompt (Conveyor Identity) ───────────────────
+TASK_MODEL=gpt-5-mini
+```
+
+#### 4c. Cloud Build Configuration
+
+**File: `infrastructure/gcp/hf-chat-ui/cloudbuild.yaml`**
+
+```yaml
+steps:
+  # Step 1: Pull the pre-built HuggingFace Chat UI image
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['pull', 'ghcr.io/huggingface/chat-ui:latest']
+
+  # Step 2: Tag for GCR
+  - name: 'gcr.io/cloud-builders/docker'
+    args: [
+      'tag',
+      'ghcr.io/huggingface/chat-ui:latest',
+      'gcr.io/${PROJECT_ID}/hf-chat-ui:${_VERSION}'
+    ]
+
+  # Step 3: Push versioned tag
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['push', 'gcr.io/${PROJECT_ID}/hf-chat-ui:${_VERSION}']
+
+  # Step 4: Push latest tag
+  - name: 'gcr.io/cloud-builders/docker'
+    args: [
+      'tag',
+      'gcr.io/${PROJECT_ID}/hf-chat-ui:${_VERSION}',
+      'gcr.io/${PROJECT_ID}/hf-chat-ui:latest'
+    ]
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['push', 'gcr.io/${PROJECT_ID}/hf-chat-ui:latest']
+
+  # Step 5: Deploy to Cloud Run
+  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
+    entrypoint: gcloud
+    args: [
+      'run', 'deploy', 'hf-chat-ui',
+      '--image', 'gcr.io/${PROJECT_ID}/hf-chat-ui:${_VERSION}',
+      '--platform', 'managed',
+      '--region', 'us-central1',
+      '--port', '3000',
+      '--memory', '2Gi',
+      '--cpu', '2',
+      '--min-instances', '0',
+      '--max-instances', '10',
+      '--timeout', '300',
+      '--vpc-connector', 'conveyor-connector',
+      '--allow-unauthenticated',
+      '--set-env-vars', 'OPENAI_BASE_URL=https://api.openai.com/v1,MONGODB_DB_NAME=conveyor-chat,PUBLIC_APP_NAME=Conveyor AI,PUBLIC_ORIGIN=https://chat.conveyorclaims.ai,LLM_SUMMARIZATION=true,ENABLE_DATA_EXPORT=true',
+      '--set-secrets', 'OPENAI_API_KEY=openai-api-key:latest,ANTHROPIC_API_KEY=anthropic-api-key:latest,GOOGLE_API_KEY=google-api-key:latest,AIRTABLE_API_KEY=airtable-api-key:latest,GOOGLE_CLIENT_ID=google-client-id:latest,GOOGLE_CLIENT_SECRET=google-client-secret:latest',
+    ]
+
+substitutions:
+  _VERSION: 'v1'
+
+options:
+  logging: CLOUD_LOGGING_ONLY
+timeout: 600s
+```
+
+---
+
+### Phase 5: Custom Domain Mapping
+
+#### 5a. Map `chat.conveyorclaims.ai` to Cloud Run
+
+```bash
+# Verify domain ownership (one-time)
+gcloud domains verify conveyorclaims.ai --project=new-project-473022
+
+# Map custom domain to the Cloud Run service
+gcloud run domain-mappings create \
+  --service=hf-chat-ui \
+  --domain=chat.conveyorclaims.ai \
+  --region=us-central1 \
+  --project=new-project-473022
+```
+
+#### 5b. DNS Configuration
+
+Add these DNS records at your domain registrar for `conveyorclaims.ai`:
+
+| Type | Name | Value |
+|------|------|-------|
+| CNAME | `chat` | `ghs.googlehosted.com.` |
+
+Google manages the SSL certificate automatically. Provisioning takes 15-30 minutes after DNS propagation.
+
+#### 5c. Google OAuth Redirect URI
+
+Add `https://chat.conveyorclaims.ai/login/callback` to the authorized redirect URIs in the Google Cloud Console:
+
+```
+Console → APIs & Services → Credentials → OAuth 2.0 Client ID
+→ Authorized redirect URIs → Add:
+   https://chat.conveyorclaims.ai/login/callback
+```
+
+---
+
+### Phase 6: System Prompt Configuration
+
+Create a custom assistant in the Chat UI that embeds Conveyor's identity and formatting rules (from ADR-027):
+
+```json
+{
+  "name": "Conveyor AI",
+  "preprompt": "You are Conveyor AI, an Insurance Case Management & Revenue Operations Assistant for CLG (Claims Litigation Group).\n\n## Your Capabilities\n- Case management: Look up case status, next steps, due dates, assigned roles\n- Workflow guidance: Step-by-step procedures from CLG workflow documents\n- Revenue forecasting: Analytics and trend analysis\n- Strategy optimization: RL-based settlement strategy simulations\n- Airtable operations: Query and update case records\n\n## Response Style\n- Start conversationally: 'Great question —', 'Yes —', 'Got it —'\n- Use emoji markers: ✅ ❌ ⚠️ 🔑 💰 📌 for scannability\n- Bold field names: **Next Steps**, **Case Status**, **RS Due Date**\n- End with a key takeaway: 🔑 or 🧠 summary\n- Offer proactive follow-up: 'If you want, I can also...'\n- NEVER expose: similarity scores, chunk IDs, function names, JSON, silo numbers\n- ALWAYS attribute sources by document name: 'Referrals Workflow', 'FAQ's'\n\n## Available Tools\nYou have access to Conveyor Tools via MCP. Use them to:\n- search_workflows: Search CLG workflow procedures and FAQs\n- query_database: Run analytics against PostgreSQL\n- manage_case: Look up or update case status via Airtable\n- run_simulation: Run RL strategy simulations\n- airtable_query: Direct Airtable CRUD operations",
+  "model": "gpt-5.2"
+}
+```
+
+This can be set as the default assistant via MongoDB or via the `ASSISTANTS` environment variable.
+
+---
+
+## Deployment Runbook
+
+### Quick Deploy (4 commands)
+
+All secrets already exist in Google Secret Manager. No new secrets needed.
+
+```bash
+# 1. Deploy Chat UI to Cloud Run (bundled MongoDB sidecar via chat-ui-db image)
+gcloud run deploy hf-chat-ui \
+  --image=ghcr.io/huggingface/chat-ui-db:latest \
+  --platform=managed \
+  --region=us-central1 \
+  --port=3000 \
+  --memory=2Gi \
+  --cpu=2 \
+  --min-instances=1 \
+  --max-instances=10 \
+  --timeout=300 \
+  --vpc-connector=conveyor-connector \
+  --allow-unauthenticated \
+  --set-env-vars="OPENAI_BASE_URL=https://api.openai.com/v1,MONGODB_URL=mongodb://localhost:27017,MONGODB_DB_NAME=conveyor-chat,PUBLIC_APP_NAME=Conveyor AI,PUBLIC_ORIGIN=https://chat.conveyorclaims.ai,LLM_SUMMARIZATION=true,ENABLE_DATA_EXPORT=true,ALLOW_IFRAME=false,USE_LOCAL_WEBSEARCH=true" \
+  --set-secrets="OPENAI_API_KEY=openai-api-key:latest,ANTHROPIC_API_KEY=anthropic-api-key:latest,GOOGLE_API_KEY=google-api-key:latest,AIRTABLE_API_KEY=airtable-api-key:latest,GOOGLE_CLIENT_ID=google-client-id:latest,GOOGLE_CLIENT_SECRET=google-client-secret:latest" \
+  --project=new-project-473022
+
+# 2. Deploy MCP Bridge (connects Chat UI tools to existing Cloud Functions + ruvector-postgres)
+gcloud run deploy mcp-bridge \
+  --source=infrastructure/gcp/mcp-bridge \
+  --platform=managed \
+  --region=us-central1 \
+  --port=3001 \
+  --memory=512Mi \
+  --cpu=1 \
+  --vpc-connector=conveyor-connector \
+  --allow-unauthenticated \
+  --project=new-project-473022
+
+# 3. Map custom domain
+gcloud run domain-mappings create \
+  --service=hf-chat-ui \
+  --domain=chat.conveyorclaims.ai \
+  --region=us-central1 \
+  --project=new-project-473022
+
+# 4. Add DNS CNAME record at registrar
+# chat.conveyorclaims.ai → ghs.googlehosted.com.
+```
+
+---
+
+## Cost Estimate
+
+| Component | Monthly Cost |
+|-----------|-------------|
+| **Cloud Run (hf-chat-ui + MongoDB sidecar)** | ~$8-30 (min-instances=1 for MongoDB persistence) |
+| **Cloud Run (mcp-bridge)** | ~$2-10 (lightweight, auto-scales to 0) |
+| **MongoDB** | $0 (bundled sidecar, no external service) |
+| **ruvector-postgres** | $0 (already running for existing services) |
+| **OpenAI API (GPT-5)** | Variable — depends on usage |
+| **Google/Anthropic APIs** | Variable — uses existing Secret Manager keys |
+| **SSL Certificate** | $0 (Google-managed) |
+| **Custom Domain** | $0 (CNAME mapping is free) |
+| **Total Infrastructure** | ~$10-40/month + AI provider usage |
+
+---
+
+## Consequences
+
+### Positive
+- **Immediate GPT-5 access** — no custom UI development needed
+- **Multi-model selection** — users choose GPT-5, GPT-5-mini, GPT-4o, o3, etc.
+- **MCP tool integration** — reuses all existing Cloud Functions without modification
+- **Production-grade** — conversation history, auth, streaming, voice input out of the box
+- **Community maintained** — 10,400+ stars, active development by HuggingFace
+- **Zero disruption** — existing chat system continues operating independently
+- **Cost effective** — MongoDB sidecar eliminates external DB cost, ruvector-postgres already running
+- **Multi-provider resilience** — if one AI provider is down, users switch to another
+
+### Negative
+- **SvelteKit, not React** — different tech stack from existing chat system; team needs familiarity
+- **MongoDB sidecar** — Chat UI requires MongoDB internally; sidecar approach means min-instances=1 for data persistence (Cloud Run stateless otherwise)
+- **Less control** — upstream UI changes may require adaptation; customization is via env vars and assistants, not code
+- **MCP bridge overhead** — extra network hop for tool calls (mitigated by Cloud Run co-location)
+
+### Risks & Mitigations
+| Risk | Mitigation |
+|------|-----------|
+| MongoDB sidecar data loss on scale-to-zero | Set min-instances=1; conversations are recoverable (AI can regenerate) |
+| OpenAI API costs spike | Set `USAGE_LIMITS` to cap messages per minute; use gpt-5-nano for simple queries |
+| HuggingFace Chat UI breaking changes | Pin to specific image tag, test before upgrading |
+| MCP bridge latency | Co-locate in us-central1, same VPC as Cloud Functions |
+| Custom domain SSL delay | Allow 24h for certificate provisioning |
+| Provider key expiration | All keys in Secret Manager — rotate without redeployment |
+
+---
+
+## Updated Architecture Diagram (Full System)
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────┐
+│                          GOOGLE CLOUD PLATFORM                                    │
+│                          Project: new-project-473022                              │
+├──────────────────────────────────────────────────────────────────────────────────┤
+│                                                                                   │
+│  ┌─────────────────────────────────────────────────────────────────────────────┐  │
+│  │                       VPC Network (conveyor-vpc)                             │  │
+│  │                                                                              │  │
+│  │  ┌─────────────────────────────────────────────────────────────┐             │  │
+│  │  │                    Cloud Run Services                        │             │  │
+│  │  │                                                              │             │  │
+│  │  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │             │  │
+│  │  │  │  hf-chat-ui  │  │ chat-system  │  │  mcp-bridge  │      │             │  │
+│  │  │  │  (NEW)       │  │ (existing)   │  │  (NEW)       │      │             │  │
+│  │  │  │              │  │              │  │              │      │             │  │
+│  │  │  │ SvelteKit    │  │ React+Vite   │  │ MCP Server   │      │             │  │
+│  │  │  │ GPT-5 models │  │ Gemini       │  │ Tool bridge  │      │             │  │
+│  │  │  │ Port 3000    │  │ Port 8080    │  │ Port 3001    │      │             │  │
+│  │  │  └──────┬───────┘  └──────────────┘  └──────┬───────┘      │             │  │
+│  │  │         │                                     │              │             │  │
+│  │  │         │chat.conveyorclaims.ai               │              │             │  │
+│  │  └─────────┼─────────────────────────────────────┼──────────────┘             │  │
+│  │            │                                     │                            │  │
+│  │  ┌────────┼─────────────────────────────────────┼───────────────────┐        │  │
+│  │  │        │         Cloud Functions              │                   │        │  │
+│  │  │        │                                      │                   │        │  │
+│  │  │        │  • airtable-agent  ◄─────────────────┤                   │        │  │
+│  │  │        │  • db-query-agent  ◄─────────────────┤                   │        │  │
+│  │  │        │  • case-manager    ◄─────────────────┤                   │        │  │
+│  │  │        │  • simulation-agent◄─────────────────┤                   │        │  │
+│  │  │        │  • workflow-search ◄─────────────────┘                   │        │  │
+│  │  │        │                                                          │        │  │
+│  │  └────────┼──────────────────────────────────────────────────────────┘        │  │
+│  │           │                                                                   │  │
+│  │  ┌────────▼─────────┐                                                         │  │
+│  │  │  ruvector-postgres│                                                        │  │
+│  │  │  10.128.0.2:5432 │                                                        │  │
+│  │  │  PostgreSQL 17.7  │                                                        │  │
+│  │  │  ruvector 2.0.1   │                                                        │  │
+│  │  └──────────────────┘                                                         │  │
+│  └───────────────────────────────────────────────────────────────────────────────┘  │
+│                                                                                     │
+│  ┌───────────────────────────┐    ┌───────────────────────────────────┐              │
+│  │  Secret Manager           │    │  AI Providers (Multi-Provider)    │              │
+│  │  • openai-api-key         │    │  • OpenAI    → GPT-5 family      │              │
+│  │  • anthropic-api-key      │    │  • Google    → Gemini 2.5        │              │
+│  │  • google-api-key         │    │  • Anthropic → Claude Sonnet 4   │              │
+│  │  • airtable-api-key       │    └───────────────────────────────────┘              │
+│  │  • ruvector-db-password   │                                                       │
+│  └───────────────────────────┘                                                       │
+└─────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Service Inventory (Post-Implementation)
+
+| Service | Domain | Purpose | Tools/Models |
+|---------|--------|---------|--------------|
+| **hf-chat-ui** (NEW) | `chat.conveyorclaims.ai` | Multi-provider chat with 3 MCP tool servers | GPT-5.2, GPT-5, GPT-5-mini, GPT-4o, o3, Gemini 2.5, Claude Sonnet 4 |
+| **mcp-bridge** (NEW) | internal | Custom MCP → Cloud Functions + ruvector-postgres | 5 tools (search, query, case, sim, airtable) |
+| **Airtable MCP** (external) | `mcp.airtable.com` | Official Airtable direct access | Schema browse, CRUD, search |
+| **Google Drive MCP** (external) | `mcp.googleapis.com` | Official Google Drive access | File search, doc read, sheets |
+| **chat-system** (existing) | `chat-system-*.run.app` | Gemini-powered workflow chat | gemini-2.5-pro/flash |
+| **mcp-server** (existing) | `mcp-server-*.run.app` | General MCP server | N/A |
+
+---
+
+## Timeline
+
+| Phase | Duration | Deliverable |
+|-------|----------|-------------|
+| Phase 1: MongoDB Atlas | 1 hour | Free cluster + secret in Secret Manager |
+| Phase 2: MCP Bridge | 2-3 hours | Cloud Run service with 5 tools |
+| Phase 3: Model Config | 30 min | MODELS env var with 7 GPT-5 variants |
+| Phase 4: Chat UI Deploy | 1-2 hours | Cloud Run service from pre-built image |
+| Phase 5: Domain Mapping | 1-24 hours | `chat.conveyorclaims.ai` live (DNS propagation) |
+| Phase 6: System Prompt | 30 min | Default Conveyor AI assistant |
+| **Total** | **~1 day** | Full deployment |
+
+---
+
+## Next Steps
+
+1. **Approve this ADR** and proceed to Phase 1 (MongoDB Atlas)
+2. Build and deploy the MCP Bridge server (Phase 2)
+3. Deploy Chat UI with GPT-5 models (Phases 3-4)
+4. Configure DNS and custom domain (Phase 5)
+5. Test end-to-end: model selection → tool calling → workflow search → response
+6. Configure Conveyor AI assistant with system prompt (Phase 6)
+7. Update ADR-028 to reference this parallel deployment
+
+---
+
+## Post-Deployment Updates (2026-03-03)
+
+### Update 1: Google OIDC Authentication
+
+Added Google OAuth login to restrict access to authenticated users only.
+
+**Configuration approach:** HF Chat UI reads OIDC settings from the `DOTENV_LOCAL` environment variable, which acts as an in-memory `.env.local` file. Individual `OPENID_*` env vars are NOT read by Chat UI — they must be inside `DOTENV_LOCAL`.
+
+**OAuth client:** `245235083640-gkbo4otq57lqeisuigcat0bg037f49oc.apps.googleusercontent.com` (Web Application type)
+
+**Secret:** `google-client-secret` in Secret Manager (version 2) — `GOCSPX-QzuZ-...`
+
+**Redirect URI:** `https://chat.conveyorclaims.ai/login/callback` (added manually in Google Cloud Console → APIs & Services → Credentials)
+
+**OIDC env vars added to DOTENV_LOCAL:**
+```ini
+OPENID_PROVIDER_URL=https://accounts.google.com
+OPENID_CLIENT_ID=245235083640-gkbo4otq57lqeisuigcat0bg037f49oc.apps.googleusercontent.com
+OPENID_SCOPES=openid profile email
+OPENID_NAME_CLAIM=name
+COOKIE_SECURE=true
+COOKIE_SAMESITE=lax
+```
+
+**Key lesson:** IAP OAuth clients (`*-9lt8...`) cannot be used for custom web OIDC flows — they are locked to IAP-specific redirect patterns. Only standard Web Application OAuth clients work.
+
+**Files modified:**
+- `infrastructure/gcp/hf-chat-ui/update-preprompt.js` — added OIDC vars to DOTENV_LOCAL output
+- `infrastructure/gcp/hf-chat-ui/cloudbuild.yaml` — added OIDC env vars + `OPENID_CLIENT_SECRET` secret binding
+- `infrastructure/gcp/hf-chat-ui/deploy.sh` — added OIDC env vars + secret binding
+
+### Update 2: Branded Welcome Animation
+
+Replaced the default HuggingFace `omni-welcome.gif` with a branded "Conveyor AI" animated GIF matching the Three.js `AnimatedBackground.tsx` aesthetic from the existing chat system.
+
+**Design:**
+- 480x320px, 90 frames (3s @ 30fps), ~1.75 MB
+- Dark background `#0d0d1a`
+- Rotating wireframe geometric shapes (icosahedron + octahedron) in cyan/blue/indigo
+- Scattered glowing dots matching blue-500/sky-500/indigo-500 palette
+- "Conveyor AI" text centered with subtle glow effect
+
+**Implementation:**
+- `infrastructure/gcp/hf-chat-ui/generate-welcome.cjs` — Node.js script using `canvas` + `gif-encoder-2` (`.cjs` extension required because root `package.json` has `"type": "module"`)
+- `infrastructure/gcp/hf-chat-ui/Dockerfile` — extends `ghcr.io/huggingface/chat-ui-db:latest`, copies branded GIF to `/app/build/client/chatui/omni-welcome.gif` and `/app/static/chatui/omni-welcome.gif`
+- `infrastructure/gcp/hf-chat-ui/cloudbuild.yaml` — changed from pull+tag to Docker build with custom Dockerfile
+
+### Update 3: MCP Bridge Tool Mapping Fixes
+
+Fixed all 5 tool-to-Cloud-Function mappings in the MCP Bridge. Every tool was sending incorrect or missing parameters to its backend Cloud Function.
+
+| Tool | Issue | Fix |
+|------|-------|-----|
+| `search_workflows` | Was working | No change needed |
+| `query_database` | Missing `action` field entirely | Added `action: "nl_query"` |
+| `manage_case` | Sent `status` as action, backend expects `get` | Map `status` → `get`, `next_steps` → `get` |
+| `run_simulation` | Missing `action` field, wrong field names | Added `action: "run_qlearning"`, mapped `scenario` → `caseType`, `episodes` → `iterations` |
+| `airtable_query` | Wrong field name `table` (backend expects `tableName`), wrong action names | Map `list` → `query`, `get` → `get_case_status`, `create`/`update` → `upsert` |
+
+**File modified:** `infrastructure/gcp/mcp-bridge/index.js`
+
+### Update 4: Natural Language to SQL (db-query-agent)
+
+Added `nl_query` action to the db-query-agent Cloud Function. This enables natural language questions like "How many cases were opened this month?" to be converted to SQL via Gemini.
+
+**Flow:** Natural language → Gemini generates SQL → validate (no DROP/DELETE) → execute against ruvector-postgres → return results
+
+**File modified:** `infrastructure/gcp/functions/db-query-agent/index.js`
+
+### Update 5: Multi-Provider Chat Completions Proxy
+
+Added an OpenAI-compatible `/chat/completions` proxy to the MCP Bridge that routes requests to the correct AI provider based on model name. This enables HF Chat UI to use `OPENAI_BASE_URL` pointing to the MCP Bridge, which then routes:
+- `gpt-*`, `o*-*` models → OpenAI API
+- `gemini-*` models → Google Generative Language API
+
+Also added `/models` endpoint returning only the curated model list (7 models) instead of the full OpenAI model catalog (114+ models).
+
+**File modified:** `infrastructure/gcp/mcp-bridge/index.js`
+
+### Deployment Status (2026-03-03)
+
+| Component | Deployed? | Notes |
+|-----------|-----------|-------|
+| HF Chat UI (with OIDC + branded GIF) | Yes | Custom Docker image with Dockerfile |
+| MCP Bridge (with tool fixes + proxy) | Yes | All 5 tools validated working |
+| db-query-agent (with nl_query) | Yes | Entry point: `dbQueryAgent` |
+
+---
+
+## Post-Deployment Updates (2026-03-04)
+
+### Update 6: Server-Side API Key Fix
+
+Fixed 401 errors where the MCP Bridge was forwarding the user's Google OAuth token to OpenAI instead of using the server-side API key.
+
+**Root cause:** `getKey: (req) => req.headers.authorization?.replace("Bearer ", "") || process.env.OPENAI_API_KEY` extracted the OIDC session token `ya29.A0A...` and sent it to OpenAI.
+
+**Fix:** Changed to `getKey: () => process.env.OPENAI_API_KEY` — always use server-side key. Added `OPENAI_API_KEY=openai-api-key:latest` to MCP bridge `cloudbuild.yaml` `--set-secrets`.
+
+### Update 7: Airtable Table Name Mapping
+
+Added `TABLE_MAP` to the MCP Bridge to translate friendly table names to actual Airtable table names. The LLM sends `"table": "Cases"` but Airtable expects `"All Cases (dev)"`.
+
+| Friendly Name | Actual Airtable Name |
+|---------------|---------------------|
+| Cases | All Cases (dev) |
+| Managed Cases | Managed Cases (dev) |
+| Clients / Contacts | Contacts |
+| Carriers / Partners | Co-Counsel & Referral Partners |
+| Users | Conveyor Users |
+| Invoices | Invoices |
+| Payments | Payments |
+| Emails | Emails |
+
+### Update 8: Case Search by Number and Client Name
+
+Enhanced `airtable_query` tool to support searching by case number or client name instead of only listing all records.
+
+- Added `search` action and `search` parameter to tool schema
+- Case number patterns (e.g., `C-01748`) route to `get_case_status` for precise lookup
+- Name searches use `query` with `{search: searchTerm}` for fuzzy matching
+- `manage_case` status/next_steps now route to airtable-agent's `get_case_status` for better results
+
+### Update 9: Table-Aware Search Formula
+
+Fixed "Unknown field names" errors when searching non-case tables. The airtable-agent search formula previously hardcoded `{Case Number}` which doesn't exist in tables like `Co-Counsel & Referral Partners`.
+
+**Fix:** Added `TABLE_SEARCH_FIELDS` map in `airtable-agent/index.js`:
+
+| Table | Search Fields |
+|-------|--------------|
+| All Cases (dev) | Case Number |
+| Contacts | Full Name, Email |
+| Co-Counsel & Referral Partners | Partner Name |
+| Invoices | Invoice Number, Reference Number |
+| Conveyor Users | Full Name, Email Address |
+
+### Update 10: Multi-Provider Model Catalog (17 Models)
+
+Expanded from 7 models to 17 models across 6 providers. Gemini 2.5 Pro set as default (first position).
+
+| Provider | Route | Models |
+|----------|-------|--------|
+| Google (direct) | Gemini API | Gemini 2.5 Pro (Default), Gemini 2.5 Flash |
+| OpenAI (direct) | OpenAI API | GPT-5.2 Pro, GPT-5, GPT-5 Mini, GPT-4o, o4-mini |
+| Anthropic | OpenRouter | Claude Sonnet 4.6, Claude Opus 4.6 |
+| Google next-gen | OpenRouter | Gemini 3 Pro Preview, Gemini 3 Flash Preview |
+| DeepSeek | OpenRouter | DeepSeek V3.2 |
+| Mistral | OpenRouter | Mistral Large, Devstral |
+| xAI | OpenRouter | Grok 4.1 Fast |
+| OpenAI latest | OpenRouter | GPT-5.3 Chat, GPT-5.3 Codex |
+
+**MCP Bridge routing logic:** Models with `/` in the name (e.g., `anthropic/claude-sonnet-4.6`) route to OpenRouter. Models starting with `gemini-` route to Google direct. All others route to OpenAI direct.
+
+### Update 11: Docker-Baked Configuration
+
+Moved MODELS config from Cloud Run env vars to Docker image `.env.local` file. The full MODELS JSON with 17 model preprompts exceeds the 32KB Cloud Run env var limit.
+
+**Architecture:** `update-preprompt.js` generates `dotenv-local.txt` → Dockerfile copies to `/app/.env.local` → HF Chat UI reads at startup. Cloud Run env vars provide secrets only (API keys via Secret Manager).
+
+### Update 12: PWA Icon and Session Cookies
+
+- Added 144x144 PNG icon to Dockerfile (fixes `/chat/chatui/icon-144x144.png` 404)
+- Added `COOKIE_MAX_AGE=604800` (7-day sessions) to reduce OAuth redirect frequency
+
+### Deployment Status (2026-03-04)
+
+| Component | Version | Status |
+|-----------|---------|--------|
+| HF Chat UI | hf-chat-ui-00026 | Live — 17 models, OIDC, branded GIF, PWA icon |
+| MCP Bridge | v2026030419xx | Live — OpenRouter routing, table mapping, search |
+| airtable-agent | Gen2 | Live — table-aware search formula |
+| db-query-agent | Gen2 | Live — nl_query action |
+
+---
+
+## Related ADRs
+
+| ADR | Relationship |
+|-----|-------------|
+| ADR-014 | Existing chat system architecture (continues independently) |
+| ADR-015 | Cloud Functions reused via MCP Bridge |
+| ADR-022 | Workflow documents in ruvector-postgres searched via tools |
+| ADR-024 | Workflow context injection pattern adapted for MCP tools |
+| ADR-027 | Response formatting rules carried into system prompt |
+| ADR-028 | OpenAI GPT-5 integration in existing chat system (complementary) |