feat(web): port conversation sidebar with search, rename, delete actions

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

apps/gateway/src/auth/auth.module.ts

@@ -3,9 +3,11 @@ import { createAuth, type Auth } from '@mosaic/auth';
 import type { Db } from '@mosaic/db';
 import { DB } from '../database/database.module.js';
 import { AUTH } from './auth.tokens.js';
+import { SsoController } from './sso.controller.js';
 
 @Global()
 @Module({
+  controllers: [SsoController],
   providers: [
     {
       provide: AUTH,

apps/gateway/src/auth/sso.controller.spec.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { SsoController } from './sso.controller.js';
+
+describe('SsoController', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('lists configured OIDC providers', () => {
+    vi.stubEnv('WORKOS_CLIENT_ID', 'workos-client');
+    vi.stubEnv('WORKOS_CLIENT_SECRET', 'workos-secret');
+    vi.stubEnv('WORKOS_ISSUER', 'https://auth.workos.com/sso/client_123');
+
+    const controller = new SsoController();
+    const providers = controller.list();
+
+    expect(providers.find((provider) => provider.id === 'workos')).toMatchObject({
+      configured: true,
+      loginMode: 'oidc',
+      callbackPath: '/api/auth/oauth2/callback/workos',
+      teamSync: { enabled: true, claim: 'organization_id' },
+    });
+  });
+
+  it('prefers SAML fallback for Keycloak when only the SAML login URL is configured', () => {
+    vi.stubEnv('KEYCLOAK_SAML_LOGIN_URL', 'https://sso.example.com/realms/mosaic/protocol/saml');
+
+    const controller = new SsoController();
+    const providers = controller.list();
+
+    expect(providers.find((provider) => provider.id === 'keycloak')).toMatchObject({
+      configured: true,
+      loginMode: 'saml',
+      samlFallback: {
+        configured: true,
+        loginUrl: 'https://sso.example.com/realms/mosaic/protocol/saml',
+      },
+    });
+  });
+});

apps/gateway/src/auth/sso.controller.ts

@@ -0,0 +1,10 @@
+import { Controller, Get } from '@nestjs/common';
+import { buildSsoDiscovery, type SsoProviderDiscovery } from '@mosaic/auth';
+
+@Controller('api/sso/providers')
+export class SsoController {
+  @Get()
+  list(): SsoProviderDiscovery[] {
+    return buildSsoDiscovery();
+  }
+}

apps/gateway/src/main.ts

@@ -11,6 +11,7 @@ import { NestFactory } from '@nestjs/core';
 import { Logger, ValidationPipe } from '@nestjs/common';
 import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
 import helmet from '@fastify/helmet';
+import { listSsoStartupWarnings } from '@mosaic/auth';
 import { AppModule } from './app.module.js';
 import { mountAuthHandler } from './auth/auth.controller.js';
 import { mountMcpHandler } from './mcp/mcp.controller.js';
@@ -23,13 +24,8 @@ async function bootstrap(): Promise<void> {
     throw new Error('BETTER_AUTH_SECRET is required');
   }
 
-  if (
-    process.env['AUTHENTIK_CLIENT_ID'] &&
-    (!process.env['AUTHENTIK_CLIENT_SECRET'] || !process.env['AUTHENTIK_ISSUER'])
-  ) {
-    console.warn(
-      '[warn] AUTHENTIK_CLIENT_ID is set but AUTHENTIK_CLIENT_SECRET or AUTHENTIK_ISSUER is missing — Authentik SSO will not work',
-    );
+  for (const warning of listSsoStartupWarnings()) {
+    logger.warn(warning);
   }
 
   const app = await NestFactory.create<NestFastifyApplication>(

apps/web/src/app/(auth)/login/page.tsx

@@ -1,17 +1,27 @@
 'use client';
 
-import Link from 'next/link';
+import { useEffect, useState } from 'react';
 import { useRouter } from 'next/navigation';
-import { useState } from 'react';
-import { signIn } from '@/lib/auth-client';
-import { getEnabledSsoProviders } from '@/lib/sso-providers';
+import Link from 'next/link';
+import { api } from '@/lib/api';
+import { authClient, signIn } from '@/lib/auth-client';
+import type { SsoProviderDiscovery } from '@/lib/sso';
+import { SsoProviderButtons } from '@/components/auth/sso-provider-buttons';
 
 export default function LoginPage(): React.ReactElement {
   const router = useRouter();
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
-  const ssoProviders = getEnabledSsoProviders();
-  const hasSsoProviders = ssoProviders.length > 0;
+  const [ssoProviders, setSsoProviders] = useState<SsoProviderDiscovery[]>([]);
+  const [ssoLoadingProviderId, setSsoLoadingProviderId] = useState<
+    SsoProviderDiscovery['id'] | null
+  >(null);
+
+  useEffect(() => {
+    api<SsoProviderDiscovery[]>('/api/sso/providers')
+      .catch(() => [] as SsoProviderDiscovery[])
+      .then((providers) => setSsoProviders(providers.filter((provider) => provider.configured)));
+  }, []);
 
   async function handleSubmit(e: React.FormEvent<HTMLFormElement>): Promise<void> {
     e.preventDefault();
@@ -33,6 +43,27 @@ export default function LoginPage(): React.ReactElement {
     router.push('/chat');
   }
 
+  async function handleSsoSignIn(providerId: SsoProviderDiscovery['id']): Promise<void> {
+    setError(null);
+    setSsoLoadingProviderId(providerId);
+
+    try {
+      const result = await authClient.signIn.oauth2({
+        providerId,
+        callbackURL: '/chat',
+        newUserCallbackURL: '/chat',
+      });
+
+      if (result.error) {
+        setError(result.error.message ?? `Sign in with ${providerId} failed`);
+        setSsoLoadingProviderId(null);
+      }
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : `Sign in with ${providerId} failed`);
+      setSsoLoadingProviderId(null);
+    }
+  }
+
   return (
     <div>
       <h1 className="text-2xl font-semibold">Sign in</h1>
@@ -47,26 +78,7 @@ export default function LoginPage(): React.ReactElement {
         </div>
       )}
 
-      {hasSsoProviders && (
-        <div className="mt-6 space-y-3">
-          {ssoProviders.map((provider) => (
-            <Link
-              key={provider.id}
-              href={provider.href}
-              className="flex w-full items-center justify-center gap-2 rounded-lg border border-surface-border bg-surface-elevated px-4 py-2.5 text-sm font-medium text-text-primary transition-colors hover:bg-surface-hover focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card"
-            >
-              {provider.buttonLabel}
-            </Link>
-          ))}
-          <div className="relative flex items-center">
-            <div className="flex-1 border-t border-surface-border" />
-            <span className="mx-3 text-xs text-text-muted">or</span>
-            <div className="flex-1 border-t border-surface-border" />
-          </div>
-        </div>
-      )}
-
-      <form className={hasSsoProviders ? 'space-y-4' : 'mt-6 space-y-4'} onSubmit={handleSubmit}>
+      <form className="mt-6 space-y-4" onSubmit={handleSubmit}>
         <div>
           <label htmlFor="email" className="block text-sm font-medium text-text-secondary">
             Email
@@ -108,6 +120,14 @@ export default function LoginPage(): React.ReactElement {
         </button>
       </form>
 
+      <SsoProviderButtons
+        providers={ssoProviders}
+        loadingProviderId={ssoLoadingProviderId}
+        onOidcSignIn={(providerId) => {
+          void handleSsoSignIn(providerId);
+        }}
+      />
+
       <p className="mt-4 text-center text-sm text-text-muted">
         Don&apos;t have an account?{' '}
         <Link href="/register" className="text-blue-400 hover:text-blue-300">

apps/web/src/app/(dashboard)/chat/page.tsx

@@ -1,190 +1,153 @@
 'use client';
 
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { api } from '@/lib/api';
 import { destroySocket, getSocket } from '@/lib/socket';
-import type { Conversation, Message, ModelInfo, ProviderInfo } from '@/lib/types';
-import { ConversationList } from '@/components/chat/conversation-list';
+import type { Conversation, Message } from '@/lib/types';
+import {
+  ConversationSidebar,
+  type ConversationSidebarRef,
+} from '@/components/chat/conversation-sidebar';
 import { MessageBubble } from '@/components/chat/message-bubble';
 import { ChatInput } from '@/components/chat/chat-input';
 import { StreamingMessage } from '@/components/chat/streaming-message';
-import { AppHeader } from '@/components/layout/app-header';
 
-const FALLBACK_MODELS: ModelInfo[] = [
-  {
-    id: 'claude-3-5-sonnet',
-    provider: 'anthropic',
-    name: 'claude-3.5-sonnet',
-    reasoning: true,
-    contextWindow: 200_000,
-    maxTokens: 8_192,
-    inputTypes: ['text'],
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-  },
-  {
-    id: 'gpt-4.1',
-    provider: 'openai',
-    name: 'gpt-4.1',
-    reasoning: false,
-    contextWindow: 128_000,
-    maxTokens: 8_192,
-    inputTypes: ['text'],
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-  },
-  {
-    id: 'gemini-2.0-flash',
-    provider: 'google',
-    name: 'gemini-2.0-flash',
-    reasoning: false,
-    contextWindow: 1_000_000,
-    maxTokens: 8_192,
-    inputTypes: ['text', 'image'],
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-  },
-];
+interface ModelInfo {
+  id: string;
+  provider: string;
+  name: string;
+  reasoning: boolean;
+  contextWindow: number;
+  maxTokens: number;
+  inputTypes: ('text' | 'image')[];
+  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+}
+
+interface ProviderInfo {
+  id: string;
+  name: string;
+  available: boolean;
+  models: ModelInfo[];
+}
 
 export default function ChatPage(): React.ReactElement {
-  const [conversations, setConversations] = useState<Conversation[]>([]);
   const [activeId, setActiveId] = useState<string | null>(null);
   const [messages, setMessages] = useState<Message[]>([]);
-  const [sidebarOpen, setSidebarOpen] = useState(true);
-  const [models, setModels] = useState<ModelInfo[]>(FALLBACK_MODELS);
-  const [selectedModelId, setSelectedModelId] = useState(FALLBACK_MODELS[0]?.id ?? '');
   const [streamingText, setStreamingText] = useState('');
-  const [streamingThinking, setStreamingThinking] = useState('');
   const [isStreaming, setIsStreaming] = useState(false);
+  const [isSidebarOpen, setIsSidebarOpen] = useState(true);
+  const [models, setModels] = useState<ModelInfo[]>([]);
+  const [selectedModelId, setSelectedModelId] = useState('');
   const messagesEndRef = useRef<HTMLDivElement>(null);
-  const activeIdRef = useRef<string | null>(null);
-  const streamingTextRef = useRef('');
-  const streamingThinkingRef = useRef('');
+  const sidebarRef = useRef<ConversationSidebarRef>(null);
 
+  // Track the active conversation ID in a ref so socket event handlers always
+  // see the current value without needing to be re-registered.
+  const activeIdRef = useRef<string | null>(null);
   activeIdRef.current = activeId;
 
-  const selectedModel = useMemo(
-    () => models.find((model) => model.id === selectedModelId) ?? models[0] ?? null,
-    [models, selectedModelId],
-  );
-  const selectedModelRef = useRef<ModelInfo | null>(selectedModel);
-  selectedModelRef.current = selectedModel;
+  // Accumulate streamed text in a ref so agent:end can read the full content
+  // without stale-closure issues.
+  const streamingTextRef = useRef('');
 
   useEffect(() => {
-    api<Conversation[]>('/api/conversations')
-      .then(setConversations)
-      .catch(() => {});
+    const savedState = window.localStorage.getItem('mosaic-sidebar-open');
+    if (savedState !== null) {
+      setIsSidebarOpen(savedState === 'true');
+    }
   }, []);
 
+  useEffect(() => {
+    window.localStorage.setItem('mosaic-sidebar-open', String(isSidebarOpen));
+  }, [isSidebarOpen]);
+
   useEffect(() => {
     api<ProviderInfo[]>('/api/providers')
-      .then((providers) =>
-        providers.filter((provider) => provider.available).flatMap((provider) => provider.models),
-      )
-      .then((availableModels) => {
-        if (availableModels.length === 0) return;
+      .then((providers) => {
+        const availableModels = providers
+          .filter((provider) => provider.available)
+          .flatMap((provider) => provider.models);
         setModels(availableModels);
-        setSelectedModelId((current) =>
-          availableModels.some((model) => model.id === current) ? current : availableModels[0]!.id,
-        );
+        setSelectedModelId((current) => current || availableModels[0]?.id || '');
       })
       .catch(() => {
-        setModels(FALLBACK_MODELS);
+        setModels([]);
+        setSelectedModelId('');
       });
   }, []);
 
+  // Load messages when active conversation changes
   useEffect(() => {
     if (!activeId) {
       setMessages([]);
       return;
     }
-
+    // Clear streaming state when switching conversations
     setIsStreaming(false);
     setStreamingText('');
-    setStreamingThinking('');
     streamingTextRef.current = '';
-    streamingThinkingRef.current = '';
-
     api<Message[]>(`/api/conversations/${activeId}/messages`)
-      .then((fetchedMessages) => setMessages(fetchedMessages.map(normalizeMessage)))
+      .then(setMessages)
       .catch(() => {});
   }, [activeId]);
 
+  // Auto-scroll to bottom
   useEffect(() => {
     messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
-  }, [messages, streamingText, streamingThinking]);
+  }, [messages, streamingText]);
 
+  // Socket.io setup — connect once for the page lifetime
   useEffect(() => {
     const socket = getSocket();
 
     function onAgentStart(data: { conversationId: string }): void {
+      // Only update state if the event belongs to the currently viewed conversation
       if (activeIdRef.current !== data.conversationId) return;
       setIsStreaming(true);
       setStreamingText('');
-      setStreamingThinking('');
       streamingTextRef.current = '';
-      streamingThinkingRef.current = '';
     }
 
-    function onAgentText(data: { conversationId: string; text?: string; thinking?: string }): void {
+    function onAgentText(data: { conversationId: string; text: string }): void {
       if (activeIdRef.current !== data.conversationId) return;
-      if (data.text) {
-        streamingTextRef.current += data.text;
-        setStreamingText((prev) => prev + data.text);
-      }
-      if (data.thinking) {
-        streamingThinkingRef.current += data.thinking;
-        setStreamingThinking((prev) => prev + data.thinking);
-      }
+      streamingTextRef.current += data.text;
+      setStreamingText((prev) => prev + data.text);
     }
 
-    function onAgentEnd(data: {
-      conversationId: string;
-      thinking?: string;
-      model?: string;
-      provider?: string;
-      promptTokens?: number;
-      completionTokens?: number;
-      totalTokens?: number;
-    }): void {
+    function onAgentEnd(data: { conversationId: string }): void {
       if (activeIdRef.current !== data.conversationId) return;
       const finalText = streamingTextRef.current;
-      const finalThinking = data.thinking ?? streamingThinkingRef.current;
       setIsStreaming(false);
       setStreamingText('');
-      setStreamingThinking('');
       streamingTextRef.current = '';
-      streamingThinkingRef.current = '';
-
+      // Append the completed assistant message to the local message list.
+      // The Pi agent session is in-memory so the assistant response is not
+      // persisted to the DB — we build the local UI state instead.
       if (finalText) {
         setMessages((prev) => [
           ...prev,
           {
             id: `assistant-${Date.now()}`,
             conversationId: data.conversationId,
-            role: 'assistant',
+            role: 'assistant' as const,
             content: finalText,
-            thinking: finalThinking || undefined,
-            model: data.model ?? selectedModelRef.current?.name,
-            provider: data.provider ?? selectedModelRef.current?.provider,
-            promptTokens: data.promptTokens,
-            completionTokens: data.completionTokens,
-            totalTokens: data.totalTokens,
             createdAt: new Date().toISOString(),
           },
         ]);
+        sidebarRef.current?.refresh();
       }
     }
 
     function onError(data: { error: string; conversationId?: string }): void {
       setIsStreaming(false);
       setStreamingText('');
-      setStreamingThinking('');
       streamingTextRef.current = '';
-      streamingThinkingRef.current = '';
       setMessages((prev) => [
         ...prev,
         {
           id: `error-${Date.now()}`,
           conversationId: data.conversationId ?? '',
-          role: 'system',
+          role: 'system' as const,
           content: `Error: ${data.error}`,
           createdAt: new Date().toISOString(),
         },
@@ -196,6 +159,7 @@ export default function ChatPage(): React.ReactElement {
     socket.on('agent:end', onAgentEnd);
     socket.on('error', onError);
 
+    // Connect if not already connected
     if (!socket.connected) {
       socket.connect();
     }
@@ -205,263 +169,197 @@ export default function ChatPage(): React.ReactElement {
       socket.off('agent:text', onAgentText);
       socket.off('agent:end', onAgentEnd);
       socket.off('error', onError);
+      // Fully tear down the socket when the chat page unmounts so we get a
+      // fresh authenticated connection next time the page is visited.
       destroySocket();
     };
   }, []);
 
-  const handleNewConversation = useCallback(async () => {
-    const conversation = await api<Conversation>('/api/conversations', {
+  const handleNewConversation = useCallback(async (projectId?: string | null) => {
+    const conv = await api<Conversation>('/api/conversations', {
       method: 'POST',
-      body: { title: 'New conversation' },
+      body: { title: 'New conversation', projectId: projectId ?? null },
     });
-    setConversations((prev) => [conversation, ...prev]);
-    setActiveId(conversation.id);
+
+    sidebarRef.current?.addConversation({
+      id: conv.id,
+      title: conv.title,
+      projectId: conv.projectId,
+      updatedAt: conv.updatedAt,
+      archived: conv.archived,
+    });
+
+    setActiveId(conv.id);
     setMessages([]);
+    setIsSidebarOpen(true);
   }, []);
 
-  const handleRename = useCallback(async (id: string, title: string) => {
-    const updated = await api<Conversation>(`/api/conversations/${id}`, {
-      method: 'PATCH',
-      body: { title },
-    });
-    setConversations((prev) =>
-      prev.map((conversation) => (conversation.id === id ? updated : conversation)),
-    );
-  }, []);
-
-  const handleDelete = useCallback(
-    async (id: string) => {
-      try {
-        await api<void>(`/api/conversations/${id}`, { method: 'DELETE' });
-        setConversations((prev) => prev.filter((conversation) => conversation.id !== id));
-        if (activeId === id) {
-          setActiveId(null);
-          setMessages([]);
-        }
-      } catch (error) {
-        console.error('[ChatPage] Failed to delete conversation:', error);
-      }
-    },
-    [activeId],
-  );
-
-  const handleArchive = useCallback(
-    async (id: string, archived: boolean) => {
-      const updated = await api<Conversation>(`/api/conversations/${id}`, {
-        method: 'PATCH',
-        body: { archived },
-      });
-      setConversations((prev) =>
-        prev.map((conversation) => (conversation.id === id ? updated : conversation)),
-      );
-      if (archived && activeId === id) {
-        setActiveId(null);
-        setMessages([]);
-      }
-    },
-    [activeId],
-  );
-
   const handleSend = useCallback(
     async (content: string, options?: { modelId?: string }) => {
-      let conversationId = activeId;
+      let convId = activeId;
 
-      if (!conversationId) {
+      // Auto-create conversation if none selected
+      if (!convId) {
         const autoTitle = content.slice(0, 60);
-        const conversation = await api<Conversation>('/api/conversations', {
+        const conv = await api<Conversation>('/api/conversations', {
           method: 'POST',
           body: { title: autoTitle },
         });
-        setConversations((prev) => [conversation, ...prev]);
-        setActiveId(conversation.id);
-        conversationId = conversation.id;
-      } else {
-        const activeConversation = conversations.find(
-          (conversation) => conversation.id === conversationId,
-        );
-        if (activeConversation?.title === 'New conversation' && messages.length === 0) {
-          const autoTitle = content.slice(0, 60);
-          api<Conversation>(`/api/conversations/${conversationId}`, {
-            method: 'PATCH',
-            body: { title: autoTitle },
-          })
-            .then((updated) => {
-              setConversations((prev) =>
-                prev.map((conversation) =>
-                  conversation.id === conversationId ? updated : conversation,
-                ),
-              );
-            })
-            .catch(() => {});
-        }
+        sidebarRef.current?.addConversation({
+          id: conv.id,
+          title: conv.title,
+          projectId: conv.projectId,
+          updatedAt: conv.updatedAt,
+          archived: conv.archived,
+        });
+        setActiveId(conv.id);
+        convId = conv.id;
+      } else if (messages.length === 0) {
+        // Auto-title the initial placeholder conversation from the first user message.
+        const autoTitle = content.slice(0, 60);
+        api<Conversation>(`/api/conversations/${convId}`, {
+          method: 'PATCH',
+          body: { title: autoTitle },
+        })
+          .then(() => sidebarRef.current?.refresh())
+          .catch(() => {});
       }
 
+      // Optimistic user message in local UI state
       setMessages((prev) => [
         ...prev,
         {
           id: `user-${Date.now()}`,
-          conversationId,
-          role: 'user',
+          conversationId: convId,
+          role: 'user' as const,
           content,
           createdAt: new Date().toISOString(),
         },
       ]);
 
-      api<Message>(`/api/conversations/${conversationId}/messages`, {
+      // Persist the user message to the DB so conversation history is
+      // available when the page is reloaded or a new session starts.
+      api<Message>(`/api/conversations/${convId}/messages`, {
         method: 'POST',
         body: { role: 'user', content },
-      }).catch(() => {});
+      }).catch(() => {
+        // Non-fatal: the agent can still process the message even if
+        // REST persistence fails.
+      });
 
+      // Send to WebSocket — gateway creates/resumes the agent session and
+      // streams the response back via agent:start / agent:text / agent:end.
       const socket = getSocket();
       if (!socket.connected) {
         socket.connect();
       }
       socket.emit('message', {
-        conversationId,
+        conversationId: convId,
         content,
-        model: options?.modelId ?? selectedModelRef.current?.id,
+        modelId: (options?.modelId ?? selectedModelId) || undefined,
       });
     },
-    [activeId, conversations, messages.length],
+    [activeId, messages, selectedModelId],
   );
 
-  const handleStop = useCallback(() => {
-    const socket = getSocket();
-    socket.emit('cancel', { conversationId: activeIdRef.current });
-
-    const partialText = streamingTextRef.current.trim();
-    const partialThinking = streamingThinkingRef.current.trim();
-
-    if (partialText) {
-      setMessages((prev) => [
-        ...prev,
-        {
-          id: `assistant-partial-${Date.now()}`,
-          conversationId: activeIdRef.current ?? '',
-          role: 'assistant',
-          content: partialText,
-          thinking: partialThinking || undefined,
-          model: selectedModelRef.current?.name,
-          provider: selectedModelRef.current?.provider,
-          createdAt: new Date().toISOString(),
-        },
-      ]);
-    }
-
-    setIsStreaming(false);
-    setStreamingText('');
-    setStreamingThinking('');
-    streamingTextRef.current = '';
-    streamingThinkingRef.current = '';
-    destroySocket();
-  }, []);
-
-  const handleEditLastMessage = useCallback((): string | null => {
-    const lastUserMessage = [...messages].reverse().find((message) => message.role === 'user');
-    return lastUserMessage?.content ?? null;
-  }, [messages]);
-
-  const activeConversation =
-    conversations.find((conversation) => conversation.id === activeId) ?? null;
-
   return (
-    <div className="-m-6 flex h-[100dvh] overflow-hidden">
-      <ConversationList
-        conversations={conversations}
-        activeId={activeId}
-        isOpen={sidebarOpen}
-        onClose={() => setSidebarOpen(false)}
-        onSelect={setActiveId}
-        onNew={handleNewConversation}
-        onRename={handleRename}
-        onDelete={handleDelete}
-        onArchive={handleArchive}
+    <div
+      className="-m-6 flex h-[calc(100vh-3.5rem)] overflow-hidden"
+      style={{ background: 'var(--bg-deep, var(--color-surface-bg, #0a0f1a))' }}
+    >
+      <ConversationSidebar
+        ref={sidebarRef}
+        isOpen={isSidebarOpen}
+        onClose={() => setIsSidebarOpen(false)}
+        currentConversationId={activeId}
+        onSelectConversation={(conversationId) => {
+          setActiveId(conversationId);
+          setMessages([]);
+          if (conversationId && window.innerWidth < 768) {
+            setIsSidebarOpen(false);
+          }
+        }}
+        onNewConversation={(projectId) => {
+          void handleNewConversation(projectId);
+        }}
       />
 
-      <div
-        className="relative flex min-w-0 flex-1 flex-col overflow-hidden"
-        style={{
-          background:
-            'radial-gradient(circle at top, color-mix(in srgb, var(--color-ms-blue-500) 14%, transparent), transparent 35%), var(--color-bg)',
-        }}
-      >
-        <AppHeader
-          conversationTitle={activeConversation?.title}
-          isSidebarOpen={sidebarOpen}
-          onToggleSidebar={() => setSidebarOpen((prev) => !prev)}
-        />
-
-        <div className="flex-1 overflow-y-auto px-4 py-6 md:px-6">
-          <div className="mx-auto flex w-full max-w-4xl flex-col gap-4">
-            {messages.length === 0 && !isStreaming ? (
-              <div className="flex min-h-full flex-1 items-center justify-center py-16">
-                <div className="max-w-xl text-center">
-                  <div className="mb-4 text-xs uppercase tracking-[0.3em] text-[var(--color-muted)]">
-                    Mosaic Chat
-                  </div>
-                  <h2 className="text-3xl font-semibold text-[var(--color-text)]">
-                    Start a new session with a better chat interface.
-                  </h2>
-                  <p className="mt-3 text-sm leading-7 text-[var(--color-text-2)]">
-                    Pick a model, send a prompt, and the response area will keep reasoning,
-                    metadata, and streaming status visible without leaving the page.
-                  </p>
-                </div>
-              </div>
-            ) : null}
-
-            {messages.map((message) => (
-              <MessageBubble key={message.id} message={message} />
-            ))}
-
-            {isStreaming ? (
-              <StreamingMessage
-                text={streamingText}
-                thinking={streamingThinking}
-                modelName={selectedModel?.name ?? null}
-              />
-            ) : null}
-
-            <div ref={messagesEndRef} />
+      <div className="flex min-w-0 flex-1 flex-col">
+        <div
+          className="flex items-center gap-3 border-b px-4 py-3"
+          style={{ borderColor: 'var(--border)' }}
+        >
+          <button
+            type="button"
+            onClick={() => setIsSidebarOpen((open) => !open)}
+            className="rounded-lg border p-2 transition-colors"
+            style={{
+              borderColor: 'var(--border)',
+              background: 'var(--surface)',
+              color: 'var(--text)',
+            }}
+            aria-label={isSidebarOpen ? 'Close conversation sidebar' : 'Open conversation sidebar'}
+          >
+            <svg viewBox="0 0 24 24" className="h-4 w-4" fill="none" stroke="currentColor">
+              <path strokeWidth="2" strokeLinecap="round" d="M4 7h16M4 12h16M4 17h16" />
+            </svg>
+          </button>
+          <div>
+            <h1 className="text-sm font-semibold" style={{ color: 'var(--text)' }}>
+              Mosaic Chat
+            </h1>
+            <p className="text-xs" style={{ color: 'var(--muted)' }}>
+              {activeId ? 'Active conversation selected' : 'Choose or start a conversation'}
+            </p>
           </div>
         </div>
 
-        <div className="sticky bottom-0">
-          <div className="mx-auto w-full max-w-4xl">
+        {activeId ? (
+          <>
+            <div className="flex-1 space-y-4 overflow-y-auto p-6">
+              {messages.map((msg) => (
+                <MessageBubble key={msg.id} message={msg} />
+              ))}
+              {isStreaming && <StreamingMessage text={streamingText} />}
+              <div ref={messagesEndRef} />
+            </div>
             <ChatInput
               onSend={handleSend}
-              onStop={handleStop}
               isStreaming={isStreaming}
               models={models}
               selectedModelId={selectedModelId}
               onModelChange={setSelectedModelId}
-              onRequestEditLastMessage={handleEditLastMessage}
             />
+          </>
+        ) : (
+          <div className="flex flex-1 items-center justify-center px-6">
+            <div
+              className="max-w-md rounded-2xl border px-8 py-10 text-center"
+              style={{
+                borderColor: 'var(--border)',
+                background: 'var(--surface)',
+              }}
+            >
+              <h2 className="text-lg font-medium" style={{ color: 'var(--text)' }}>
+                Welcome to Mosaic Chat
+              </h2>
+              <p className="mt-1 text-sm" style={{ color: 'var(--muted)' }}>
+                Select a conversation or start a new one
+              </p>
+              <button
+                type="button"
+                onClick={() => {
+                  void handleNewConversation();
+                }}
+                className="mt-4 rounded-lg px-4 py-2 text-sm font-medium text-white transition-colors"
+                style={{ background: 'var(--primary)' }}
+              >
+                Start new conversation
+              </button>
+            </div>
           </div>
-        </div>
+        )}
       </div>
     </div>
   );
 }
-
-function normalizeMessage(message: Message): Message {
-  const metadata = message.metadata ?? {};
-
-  return {
-    ...message,
-    thinking:
-      message.thinking ?? (typeof metadata.thinking === 'string' ? metadata.thinking : undefined),
-    model: message.model ?? (typeof metadata.model === 'string' ? metadata.model : undefined),
-    provider:
-      message.provider ?? (typeof metadata.provider === 'string' ? metadata.provider : undefined),
-    promptTokens:
-      message.promptTokens ??
-      (typeof metadata.prompt_tokens === 'number' ? metadata.prompt_tokens : undefined),
-    completionTokens:
-      message.completionTokens ??
-      (typeof metadata.completion_tokens === 'number' ? metadata.completion_tokens : undefined),
-    totalTokens:
-      message.totalTokens ??
-      (typeof metadata.total_tokens === 'number' ? metadata.total_tokens : undefined),
-  };
-}

apps/web/src/app/(dashboard)/settings/page.tsx

@@ -3,6 +3,8 @@
 import { useCallback, useEffect, useState } from 'react';
 import { api } from '@/lib/api';
 import { authClient, useSession } from '@/lib/auth-client';
+import type { SsoProviderDiscovery } from '@/lib/sso';
+import { SsoProviderSection } from '@/components/settings/sso-provider-section';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -424,7 +426,9 @@ function NotificationsTab(): React.ReactElement {
 
 function ProvidersTab(): React.ReactElement {
   const [providers, setProviders] = useState<ProviderInfo[]>([]);
+  const [ssoProviders, setSsoProviders] = useState<SsoProviderDiscovery[]>([]);
   const [loading, setLoading] = useState(true);
+  const [ssoLoading, setSsoLoading] = useState(true);
   const [testStatuses, setTestStatuses] = useState<Record<string, ProviderTestStatus>>({});
 
   useEffect(() => {
@@ -434,6 +438,13 @@ function ProvidersTab(): React.ReactElement {
       .finally(() => setLoading(false));
   }, []);
 
+  useEffect(() => {
+    api<SsoProviderDiscovery[]>('/api/sso/providers')
+      .catch(() => [] as SsoProviderDiscovery[])
+      .then((providers) => setSsoProviders(providers))
+      .finally(() => setSsoLoading(false));
+  }, []);
+
   const testConnection = useCallback(async (providerId: string): Promise<void> => {
     setTestStatuses((prev) => ({
       ...prev,
@@ -464,35 +475,44 @@ function ProvidersTab(): React.ReactElement {
     .find((m) => providers.find((p) => p.id === m.provider)?.available);
 
   return (
-    <section className="space-y-4">
-      <h2 className="text-lg font-medium text-text-secondary">LLM Providers</h2>
-      {loading ? (
-        <p className="text-sm text-text-muted">Loading providers...</p>
-      ) : providers.length === 0 ? (
-        <div className="rounded-lg border border-surface-border bg-surface-card p-4">
-          <p className="text-sm text-text-muted">
-            No providers configured. Set{' '}
-            <code className="rounded bg-surface-elevated px-1 py-0.5 text-xs">OLLAMA_BASE_URL</code>{' '}
-            or{' '}
-            <code className="rounded bg-surface-elevated px-1 py-0.5 text-xs">
-              MOSAIC_CUSTOM_PROVIDERS
-            </code>{' '}
-            to add providers.
-          </p>
-        </div>
-      ) : (
-        <div className="space-y-4">
-          {providers.map((provider) => (
-            <ProviderCard
-              key={provider.id}
-              provider={provider}
-              defaultModel={defaultModel}
-              testStatus={testStatuses[provider.id] ?? { state: 'idle' }}
-              onTest={() => void testConnection(provider.id)}
-            />
-          ))}
-        </div>
-      )}
+    <section className="space-y-6">
+      <div className="space-y-4">
+        <h2 className="text-lg font-medium text-text-secondary">SSO Providers</h2>
+        <SsoProviderSection providers={ssoProviders} loading={ssoLoading} />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-lg font-medium text-text-secondary">LLM Providers</h2>
+        {loading ? (
+          <p className="text-sm text-text-muted">Loading providers...</p>
+        ) : providers.length === 0 ? (
+          <div className="rounded-lg border border-surface-border bg-surface-card p-4">
+            <p className="text-sm text-text-muted">
+              No providers configured. Set{' '}
+              <code className="rounded bg-surface-elevated px-1 py-0.5 text-xs">
+                OLLAMA_BASE_URL
+              </code>{' '}
+              or{' '}
+              <code className="rounded bg-surface-elevated px-1 py-0.5 text-xs">
+                MOSAIC_CUSTOM_PROVIDERS
+              </code>{' '}
+              to add providers.
+            </p>
+          </div>
+        ) : (
+          <div className="space-y-4">
+            {providers.map((provider) => (
+              <ProviderCard
+                key={provider.id}
+                provider={provider}
+                defaultModel={defaultModel}
+                testStatus={testStatuses[provider.id] ?? { state: 'idle' }}
+                onTest={() => void testConnection(provider.id)}
+              />
+            ))}
+          </div>
+        )}
+      </div>
     </section>
   );
 }

apps/web/src/app/globals.css

@@ -1,101 +1,186 @@
 @import 'tailwindcss';
 
-/*
- * Mosaic Stack design tokens mapped to Tailwind v4 theme.
- * Source: @mosaic/design-tokens (AD-13)
- * Fonts: Outfit (sans), Fira Code (mono)
- * Palette: deep blue-grays + blue/purple/teal accents
- * Default: dark theme
- */
+/* =============================================================================
+   MOSAIC DESIGN SYSTEM — Reference token system from dashboard design
+   ============================================================================= */
 
-@theme {
-  /* ─── Fonts ─── */
-  --font-sans: 'Outfit', system-ui, -apple-system, sans-serif;
-  --font-mono: 'Fira Code', ui-monospace, Menlo, monospace;
+/* -----------------------------------------------------------------------------
+   Primitive Tokens (Dark-first — dark is the default theme)
+   ----------------------------------------------------------------------------- */
+:root {
+  /* Mosaic design tokens — dark palette (default) */
+  --ms-bg-950: #080b12;
+  --ms-bg-900: #0f141d;
+  --ms-bg-850: #151b26;
+  --ms-surface-800: #1b2331;
+  --ms-surface-750: #232d3f;
+  --ms-border-700: #2f3b52;
+  --ms-text-100: #eef3ff;
+  --ms-text-300: #c5d0e6;
+  --ms-text-500: #8f9db7;
+  --ms-blue-500: #2f80ff;
+  --ms-blue-400: #56a0ff;
+  --ms-red-500: #e5484d;
+  --ms-red-400: #f06a6f;
+  --ms-purple-500: #8b5cf6;
+  --ms-purple-400: #a78bfa;
+  --ms-teal-500: #14b8a6;
+  --ms-teal-400: #2dd4bf;
+  --ms-amber-500: #f59e0b;
+  --ms-amber-400: #fbbf24;
+  --ms-pink-500: #ec4899;
+  --ms-emerald-500: #10b981;
+  --ms-orange-500: #f97316;
+  --ms-cyan-500: #06b6d4;
+  --ms-indigo-500: #6366f1;
 
-  /* ─── Neutral blue-gray scale ─── */
-  --color-gray-50: #f0f2f5;
-  --color-gray-100: #dce0e8;
-  --color-gray-200: #b8c0cc;
-  --color-gray-300: #8e99a9;
-  --color-gray-400: #6b7a8d;
-  --color-gray-500: #4e5d70;
-  --color-gray-600: #3b4859;
-  --color-gray-700: #2a3544;
-  --color-gray-800: #1c2433;
-  --color-gray-900: #111827;
-  --color-gray-950: #0a0f1a;
+  /* Semantic aliases — dark theme is default */
+  --bg: var(--ms-bg-900);
+  --bg-deep: var(--ms-bg-950);
+  --bg-mid: var(--ms-bg-850);
+  --surface: var(--ms-surface-800);
+  --surface-2: var(--ms-surface-750);
+  --border: var(--ms-border-700);
+  --text: var(--ms-text-100);
+  --text-2: var(--ms-text-300);
+  --muted: var(--ms-text-500);
+  --primary: var(--ms-blue-500);
+  --primary-l: var(--ms-blue-400);
+  --danger: var(--ms-red-500);
+  --success: var(--ms-teal-500);
+  --warn: var(--ms-amber-500);
+  --purple: var(--ms-purple-500);
 
-  /* ─── Primary — blue ─── */
-  --color-blue-50: #eff4ff;
-  --color-blue-100: #dae5ff;
-  --color-blue-200: #bdd1ff;
-  --color-blue-300: #8fb4ff;
-  --color-blue-400: #5b8bff;
-  --color-blue-500: #3b6cf7;
-  --color-blue-600: #2551e0;
-  --color-blue-700: #1d40c0;
-  --color-blue-800: #1e369c;
-  --color-blue-900: #1e317b;
-  --color-blue-950: #162050;
+  /* Typography */
+  --font: var(--font-outfit, 'Outfit'), system-ui, sans-serif;
+  --mono: var(--font-fira-code, 'Fira Code'), 'Cascadia Code', monospace;
 
-  /* ─── Accent — purple ─── */
-  --color-purple-50: #f3f0ff;
-  --color-purple-100: #e7dfff;
-  --color-purple-200: #d2c3ff;
-  --color-purple-300: #b49aff;
-  --color-purple-400: #9466ff;
-  --color-purple-500: #7c3aed;
-  --color-purple-600: #6d28d9;
-  --color-purple-700: #5b21b6;
-  --color-purple-800: #4c1d95;
-  --color-purple-900: #3b1578;
-  --color-purple-950: #230d4d;
+  /* Radius scale */
+  --r: 8px;
+  --r-sm: 5px;
+  --r-lg: 12px;
+  --r-xl: 16px;
 
-  /* ─── Accent — teal ─── */
-  --color-teal-50: #effcf9;
-  --color-teal-100: #d0f7ef;
-  --color-teal-200: #a4eddf;
-  --color-teal-300: #6fddcb;
-  --color-teal-400: #3ec5b2;
-  --color-teal-500: #25aa99;
-  --color-teal-600: #1c897e;
-  --color-teal-700: #1b6e66;
-  --color-teal-800: #1a5853;
-  --color-teal-900: #194945;
-  --color-teal-950: #082d2b;
+  /* Layout dimensions */
+  --sidebar-w: 260px;
+  --topbar-h: 56px;
+  --terminal-h: 220px;
 
-  /* ─── Semantic surface tokens ─── */
-  --color-surface-bg: #0a0f1a;
-  --color-surface-card: #111827;
-  --color-surface-elevated: #1c2433;
-  --color-surface-border: #2a3544;
+  /* Easing */
+  --ease: cubic-bezier(0.16, 1, 0.3, 1);
 
-  /* ─── Semantic text tokens ─── */
-  --color-text-primary: #f0f2f5;
-  --color-text-secondary: #8e99a9;
-  --color-text-muted: #6b7a8d;
-
-  /* ─── Status colors ─── */
-  --color-success: #22c55e;
-  --color-warning: #f59e0b;
-  --color-error: #ef4444;
-  --color-info: #3b82f6;
-
-  /* ─── Sidebar width ─── */
-  --spacing-sidebar: 16rem;
+  /* Legacy shadow tokens (retained for component compat) */
+  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.3);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.4), 0 2px 4px -2px rgb(0 0 0 / 0.3);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.5), 0 4px 6px -4px rgb(0 0 0 / 0.4);
 }
 
-/* ─── Base styles ─── */
-body {
-  background-color: var(--color-surface-bg);
-  color: var(--color-text-primary);
-  font-family: var(--font-sans);
+[data-theme='light'] {
+  --ms-bg-950: #f8faff;
+  --ms-bg-900: #f0f4fc;
+  --ms-bg-850: #e8edf8;
+  --ms-surface-800: #dde4f2;
+  --ms-surface-750: #d0d9ec;
+  --ms-border-700: #b8c4de;
+  --ms-text-100: #0f141d;
+  --ms-text-300: #2f3b52;
+  --ms-text-500: #5a6a87;
+  --bg: var(--ms-bg-900);
+  --bg-deep: var(--ms-bg-950);
+  --bg-mid: var(--ms-bg-850);
+  --surface: var(--ms-surface-800);
+  --surface-2: var(--ms-surface-750);
+  --border: var(--ms-border-700);
+  --text: var(--ms-text-100);
+  --text-2: var(--ms-text-300);
+  --muted: var(--ms-text-500);
+  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05), 0 1px 3px 0 rgb(0 0 0 / 0.05);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.08), 0 2px 4px -2px rgb(0 0 0 / 0.06);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.08);
+}
+
+@theme {
+  --font-sans: var(--font);
+  --font-mono: var(--mono);
+  --color-surface-bg: var(--bg);
+  --color-surface-card: var(--surface);
+  --color-surface-elevated: var(--surface-2);
+  --color-surface-border: var(--border);
+  --color-text-primary: var(--text);
+  --color-text-secondary: var(--text-2);
+  --color-text-muted: var(--muted);
+  --color-accent: var(--primary);
+  --color-success: var(--success);
+  --color-warning: var(--warn);
+  --color-error: var(--danger);
+  --color-info: var(--primary-l);
+  --spacing-sidebar: var(--sidebar-w);
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  font-size: 15px;
+  font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 }
 
-/* ─── Scrollbar styling ─── */
+body {
+  font-family: var(--font);
+  background: var(--bg);
+  color: var(--text);
+  line-height: 1.5;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+button {
+  font-family: inherit;
+  cursor: pointer;
+  border: none;
+  background: none;
+  color: inherit;
+}
+
+input,
+select,
+textarea {
+  font-family: inherit;
+}
+
+ul {
+  list-style: none;
+}
+
+body::before {
+  content: '';
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  z-index: 9999;
+  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 200 200' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='1'/%3E%3C/svg%3E");
+  opacity: 0.025;
+}
+
+@layer base {
+  :focus-visible {
+    outline: 2px solid var(--ms-blue-400);
+    outline-offset: 2px;
+  }
+
+  :focus:not(:focus-visible) {
+    outline: none;
+  }
+}
+
 ::-webkit-scrollbar {
   width: 6px;
   height: 6px;
@@ -106,10 +191,96 @@ body {
 }
 
 ::-webkit-scrollbar-thumb {
-  background: var(--color-gray-600);
+  background: var(--border);
   border-radius: 3px;
 }
 
 ::-webkit-scrollbar-thumb:hover {
-  background: var(--color-gray-500);
+  background: var(--muted);
+}
+
+* {
+  scrollbar-width: thin;
+  scrollbar-color: var(--border) transparent;
+}
+
+.app-shell {
+  display: grid;
+  grid-template-columns: var(--sidebar-w) 1fr;
+  grid-template-rows: var(--topbar-h) 1fr;
+  height: 100vh;
+  overflow: hidden;
+}
+
+.app-header {
+  grid-column: 1 / -1;
+  grid-row: 1;
+  background: var(--bg-deep);
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  align-items: center;
+  padding: 0 20px;
+  gap: 12px;
+  z-index: 100;
+}
+
+.app-sidebar {
+  grid-column: 1;
+  grid-row: 2;
+  background: var(--bg-deep);
+  border-right: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.app-main {
+  grid-column: 2;
+  grid-row: 2;
+  background: var(--bg);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  position: relative;
+}
+
+@media (max-width: 767px) {
+  .app-shell {
+    grid-template-columns: 1fr;
+  }
+
+  .app-sidebar {
+    position: fixed;
+    left: 0;
+    top: var(--topbar-h);
+    bottom: 0;
+    width: 240px;
+    z-index: 150;
+    transform: translateX(-100%);
+    transition: transform 0.2s ease;
+  }
+
+  .app-sidebar[data-mobile-open='true'] {
+    transform: translateX(0);
+  }
+
+  .app-main,
+  .app-header {
+    grid-column: 1;
+  }
+}
+
+@media (min-width: 768px) and (max-width: 1023px) {
+  .app-shell[data-sidebar-hidden='true'] {
+    grid-template-columns: 1fr;
+  }
+
+  .app-shell[data-sidebar-hidden='true'] .app-sidebar {
+    display: none;
+  }
+
+  .app-shell[data-sidebar-hidden='true'] .app-main,
+  .app-shell[data-sidebar-hidden='true'] .app-header {
+    grid-column: 1;
+  }
 }

apps/web/src/app/layout.tsx

@@ -1,30 +1,41 @@
+import type { Metadata } from 'next';
 import type { ReactNode } from 'react';
-import { Outfit, Fira_Code } from 'next/font/google';
+import { ThemeProvider } from '@/providers/theme-provider';
 import './globals.css';
 
-const outfit = Outfit({
-  subsets: ['latin'],
-  variable: '--font-sans',
-  display: 'swap',
-  weight: ['300', '400', '500', '600', '700'],
-});
-
-const firaCode = Fira_Code({
-  subsets: ['latin'],
-  variable: '--font-mono',
-  display: 'swap',
-  weight: ['400', '500', '700'],
-});
-
-export const metadata = {
+export const metadata: Metadata = {
   title: 'Mosaic',
   description: 'Mosaic Stack Dashboard',
 };
 
+function themeScript(): string {
+  return `
+    (function () {
+      try {
+        var theme = window.localStorage.getItem('mosaic-theme') || 'dark';
+        document.documentElement.setAttribute('data-theme', theme === 'light' ? 'light' : 'dark');
+      } catch (error) {
+        document.documentElement.setAttribute('data-theme', 'dark');
+      }
+    })();
+  `;
+}
+
 export default function RootLayout({ children }: { children: ReactNode }): React.ReactElement {
   return (
-    <html lang="en" className={`dark ${outfit.variable} ${firaCode.variable}`}>
-      <body>{children}</body>
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+        <link
+          rel="stylesheet"
+          href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Fira+Code:wght@400;500&display=swap"
+        />
+        <script dangerouslySetInnerHTML={{ __html: themeScript() }} />
+      </head>
+      <body>
+        <ThemeProvider>{children}</ThemeProvider>
+      </body>
     </html>
   );
 }

apps/web/src/components/auth/sso-provider-buttons.spec.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { SsoProviderButtons } from './sso-provider-buttons.js';
+
+describe('SsoProviderButtons', () => {
+  it('renders OIDC sign-in buttons and SAML fallback links', () => {
+    const html = renderToStaticMarkup(
+      <SsoProviderButtons
+        providers={[
+          {
+            id: 'workos',
+            name: 'WorkOS',
+            protocols: ['oidc'],
+            configured: true,
+            loginMode: 'oidc',
+            callbackPath: '/api/auth/oauth2/callback/workos',
+            teamSync: { enabled: true, claim: 'organization_id' },
+            samlFallback: { configured: false, loginUrl: null },
+            warnings: [],
+          },
+          {
+            id: 'keycloak',
+            name: 'Keycloak',
+            protocols: ['oidc', 'saml'],
+            configured: true,
+            loginMode: 'saml',
+            callbackPath: null,
+            teamSync: { enabled: true, claim: 'groups' },
+            samlFallback: {
+              configured: true,
+              loginUrl: 'https://sso.example.com/realms/mosaic/protocol/saml',
+            },
+            warnings: [],
+          },
+        ]}
+        onOidcSignIn={vi.fn()}
+      />,
+    );
+
+    expect(html).toContain('Continue with WorkOS');
+    expect(html).toContain('Continue with Keycloak (SAML)');
+    expect(html).toContain('https://sso.example.com/realms/mosaic/protocol/saml');
+  });
+});

apps/web/src/components/auth/sso-provider-buttons.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import type { SsoProviderDiscovery } from '@/lib/sso';
+
+interface SsoProviderButtonsProps {
+  providers: SsoProviderDiscovery[];
+  loadingProviderId?: string | null;
+  onOidcSignIn: (providerId: SsoProviderDiscovery['id']) => void;
+}
+
+export function SsoProviderButtons({
+  providers,
+  loadingProviderId = null,
+  onOidcSignIn,
+}: SsoProviderButtonsProps): React.ReactElement | null {
+  const visibleProviders = providers.filter((provider) => provider.configured);
+
+  if (visibleProviders.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="mt-6 space-y-3 border-t border-surface-border pt-6">
+      <p className="text-sm font-medium text-text-secondary">Single sign-on</p>
+      <div className="space-y-3">
+        {visibleProviders.map((provider) => {
+          if (provider.loginMode === 'saml' && provider.samlFallback.loginUrl) {
+            return (
+              <a
+                key={provider.id}
+                href={provider.samlFallback.loginUrl}
+                className="flex w-full items-center justify-center rounded-lg border border-surface-border bg-surface-elevated px-4 py-2.5 text-sm font-medium text-text-primary transition-colors hover:border-accent/50 hover:text-accent"
+              >
+                Continue with {provider.name} (SAML)
+              </a>
+            );
+          }
+
+          return (
+            <button
+              key={provider.id}
+              type="button"
+              disabled={loadingProviderId === provider.id}
+              onClick={() => onOidcSignIn(provider.id)}
+              className="flex w-full items-center justify-center rounded-lg border border-surface-border bg-surface-elevated px-4 py-2.5 text-sm font-medium text-text-primary transition-colors hover:border-accent/50 hover:text-accent disabled:opacity-50"
+            >
+              {loadingProviderId === provider.id
+                ? `Redirecting to ${provider.name}...`
+                : `Continue with ${provider.name}`}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

apps/web/src/components/chat/conversation-sidebar.tsx

@@ -0,0 +1,576 @@
+'use client';
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { api } from '@/lib/api';
+import type { Conversation, Project } from '@/lib/types';
+
+export interface ConversationSummary {
+  id: string;
+  title: string | null;
+  projectId: string | null;
+  updatedAt: string;
+  archived?: boolean;
+}
+
+export interface ConversationSidebarRef {
+  refresh: () => void;
+  addConversation: (conversation: ConversationSummary) => void;
+}
+
+interface ConversationSidebarProps {
+  isOpen: boolean;
+  onClose: () => void;
+  currentConversationId: string | null;
+  onSelectConversation: (conversationId: string | null) => void;
+  onNewConversation: (projectId?: string | null) => void;
+}
+
+interface GroupedConversations {
+  key: string;
+  label: string;
+  projectId: string | null;
+  conversations: ConversationSummary[];
+}
+
+function toSummary(conversation: Conversation): ConversationSummary {
+  return {
+    id: conversation.id,
+    title: conversation.title,
+    projectId: conversation.projectId,
+    updatedAt: conversation.updatedAt,
+    archived: conversation.archived,
+  };
+}
+
+function formatRelativeTime(dateStr: string): string {
+  const date = new Date(dateStr);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMinutes = Math.floor(diffMs / 60_000);
+  const diffHours = Math.floor(diffMs / 3_600_000);
+  const diffDays = Math.floor(diffMs / 86_400_000);
+
+  if (diffMinutes < 1) return 'Just now';
+  if (diffMinutes < 60) return `${diffMinutes}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays === 1) return 'Yesterday';
+  if (diffDays < 7) return `${diffDays}d ago`;
+
+  return date.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+}
+
+export const ConversationSidebar = forwardRef<ConversationSidebarRef, ConversationSidebarProps>(
+  function ConversationSidebar(
+    { isOpen, onClose, currentConversationId, onSelectConversation, onNewConversation },
+    ref,
+  ): React.ReactElement {
+    const [conversations, setConversations] = useState<ConversationSummary[]>([]);
+    const [projects, setProjects] = useState<Project[]>([]);
+    const [searchQuery, setSearchQuery] = useState('');
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState<string | null>(null);
+    const [renamingId, setRenamingId] = useState<string | null>(null);
+    const [renameValue, setRenameValue] = useState('');
+    const [pendingDeleteId, setPendingDeleteId] = useState<string | null>(null);
+    const [hoveredId, setHoveredId] = useState<string | null>(null);
+    const renameInputRef = useRef<HTMLInputElement>(null);
+
+    const loadSidebarData = useCallback(async (): Promise<void> => {
+      try {
+        setIsLoading(true);
+        setError(null);
+
+        const [loadedConversations, loadedProjects] = await Promise.all([
+          api<Conversation[]>('/api/conversations'),
+          api<Project[]>('/api/projects').catch(() => [] as Project[]),
+        ]);
+
+        setConversations(
+          loadedConversations
+            .filter((conversation) => !conversation.archived)
+            .map(toSummary)
+            .sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt)),
+        );
+        setProjects(loadedProjects);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to load conversations');
+      } finally {
+        setIsLoading(false);
+      }
+    }, []);
+
+    useEffect(() => {
+      void loadSidebarData();
+    }, [loadSidebarData]);
+
+    useEffect(() => {
+      if (!renamingId) return;
+      const timer = window.setTimeout(() => renameInputRef.current?.focus(), 0);
+      return () => window.clearTimeout(timer);
+    }, [renamingId]);
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        refresh: () => {
+          void loadSidebarData();
+        },
+        addConversation: (conversation) => {
+          setConversations((prev) => {
+            const next = [conversation, ...prev.filter((item) => item.id !== conversation.id)];
+            return next.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
+          });
+        },
+      }),
+      [loadSidebarData],
+    );
+
+    const filteredConversations = useMemo(() => {
+      const query = searchQuery.trim().toLowerCase();
+      if (!query) return conversations;
+
+      return conversations.filter((conversation) =>
+        (conversation.title ?? 'Untitled conversation').toLowerCase().includes(query),
+      );
+    }, [conversations, searchQuery]);
+
+    const groupedConversations = useMemo<GroupedConversations[]>(() => {
+      if (projects.length === 0) {
+        return [
+          {
+            key: 'all',
+            label: 'All conversations',
+            projectId: null,
+            conversations: filteredConversations,
+          },
+        ];
+      }
+
+      const byProject = new Map<string | null, ConversationSummary[]>();
+      for (const conversation of filteredConversations) {
+        const key = conversation.projectId ?? null;
+        const items = byProject.get(key) ?? [];
+        items.push(conversation);
+        byProject.set(key, items);
+      }
+
+      const groups: GroupedConversations[] = [];
+
+      for (const project of projects) {
+        const projectConversations = byProject.get(project.id);
+        if (!projectConversations?.length) continue;
+
+        groups.push({
+          key: project.id,
+          label: project.name,
+          projectId: project.id,
+          conversations: projectConversations,
+        });
+      }
+
+      const ungrouped = byProject.get(null);
+      if (ungrouped?.length) {
+        groups.push({
+          key: 'general',
+          label: 'General',
+          projectId: null,
+          conversations: ungrouped,
+        });
+      }
+
+      if (groups.length === 0) {
+        groups.push({
+          key: 'all',
+          label: 'All conversations',
+          projectId: null,
+          conversations: filteredConversations,
+        });
+      }
+
+      return groups;
+    }, [filteredConversations, projects]);
+
+    const startRename = useCallback((conversation: ConversationSummary): void => {
+      setPendingDeleteId(null);
+      setRenamingId(conversation.id);
+      setRenameValue(conversation.title ?? '');
+    }, []);
+
+    const cancelRename = useCallback((): void => {
+      setRenamingId(null);
+      setRenameValue('');
+    }, []);
+
+    const commitRename = useCallback(async (): Promise<void> => {
+      if (!renamingId) return;
+
+      const title = renameValue.trim() || 'Untitled conversation';
+
+      try {
+        const updated = await api<Conversation>(`/api/conversations/${renamingId}`, {
+          method: 'PATCH',
+          body: { title },
+        });
+
+        const summary = toSummary(updated);
+        setConversations((prev) =>
+          prev
+            .map((conversation) => (conversation.id === renamingId ? summary : conversation))
+            .sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt)),
+        );
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to rename conversation');
+      } finally {
+        setRenamingId(null);
+        setRenameValue('');
+      }
+    }, [renameValue, renamingId]);
+
+    const deleteConversation = useCallback(
+      async (conversationId: string): Promise<void> => {
+        try {
+          await api<void>(`/api/conversations/${conversationId}`, { method: 'DELETE' });
+          setConversations((prev) =>
+            prev.filter((conversation) => conversation.id !== conversationId),
+          );
+          if (currentConversationId === conversationId) {
+            onSelectConversation(null);
+          }
+        } catch (err) {
+          setError(err instanceof Error ? err.message : 'Failed to delete conversation');
+        } finally {
+          setPendingDeleteId(null);
+        }
+      },
+      [currentConversationId, onSelectConversation],
+    );
+
+    return (
+      <>
+        {isOpen ? (
+          <button
+            type="button"
+            aria-label="Close conversation sidebar"
+            className="fixed inset-0 z-30 bg-black/50 md:hidden"
+            onClick={onClose}
+          />
+        ) : null}
+
+        <aside
+          aria-label="Conversation sidebar"
+          className="fixed left-0 top-0 z-40 flex h-full flex-col border-r md:relative md:z-0"
+          style={{
+            width: 'var(--sidebar-w)',
+            background: 'var(--bg)',
+            borderColor: 'var(--border)',
+            transform: isOpen ? 'translateX(0)' : 'translateX(calc(-1 * var(--sidebar-w)))',
+            transition: 'transform 220ms var(--ease)',
+          }}
+        >
+          <div
+            className="flex items-center justify-between border-b px-4 py-3"
+            style={{ borderColor: 'var(--border)' }}
+          >
+            <div>
+              <p className="text-sm font-semibold" style={{ color: 'var(--text)' }}>
+                Conversations
+              </p>
+              <p className="text-xs" style={{ color: 'var(--muted)' }}>
+                Search, rename, and manage threads
+              </p>
+            </div>
+            <button
+              type="button"
+              onClick={onClose}
+              className="rounded-md p-2 md:hidden"
+              style={{ color: 'var(--text-2)' }}
+            >
+              <svg viewBox="0 0 24 24" className="h-4 w-4" fill="none" stroke="currentColor">
+                <path strokeWidth="2" strokeLinecap="round" d="M6 6l12 12M18 6 6 18" />
+              </svg>
+            </button>
+          </div>
+
+          <div className="space-y-3 border-b p-3" style={{ borderColor: 'var(--border)' }}>
+            <button
+              type="button"
+              onClick={() => onNewConversation(null)}
+              className="flex w-full items-center justify-center gap-2 rounded-lg border px-3 py-2 text-sm font-medium transition-colors"
+              style={{
+                borderColor: 'var(--primary)',
+                background: 'color-mix(in srgb, var(--primary) 12%, transparent)',
+                color: 'var(--text)',
+              }}
+            >
+              <svg viewBox="0 0 24 24" className="h-4 w-4" fill="none" stroke="currentColor">
+                <path strokeWidth="2" strokeLinecap="round" d="M12 5v14M5 12h14" />
+              </svg>
+              New conversation
+            </button>
+
+            <div className="relative">
+              <svg
+                viewBox="0 0 24 24"
+                className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2"
+                fill="none"
+                stroke="currentColor"
+                style={{ color: 'var(--muted)' }}
+              >
+                <circle cx="11" cy="11" r="7" strokeWidth="2" />
+                <path d="m20 20-3.5-3.5" strokeWidth="2" strokeLinecap="round" />
+              </svg>
+              <input
+                type="search"
+                value={searchQuery}
+                onChange={(event) => setSearchQuery(event.target.value)}
+                placeholder="Search conversations"
+                className="w-full rounded-lg border px-9 py-2 text-sm outline-none"
+                style={{
+                  background: 'var(--surface)',
+                  borderColor: 'var(--border)',
+                  color: 'var(--text)',
+                }}
+              />
+            </div>
+          </div>
+
+          <div className="flex-1 overflow-y-auto p-3">
+            {isLoading ? (
+              <div className="py-8 text-center text-sm" style={{ color: 'var(--muted)' }}>
+                Loading conversations...
+              </div>
+            ) : error ? (
+              <div
+                className="space-y-3 rounded-xl border p-4 text-sm"
+                style={{
+                  background: 'color-mix(in srgb, var(--danger) 10%, var(--surface))',
+                  borderColor: 'color-mix(in srgb, var(--danger) 35%, var(--border))',
+                  color: 'var(--text)',
+                }}
+              >
+                <p>{error}</p>
+                <button
+                  type="button"
+                  onClick={() => void loadSidebarData()}
+                  className="rounded-md px-3 py-1.5 text-xs font-medium"
+                  style={{ background: 'var(--danger)', color: 'white' }}
+                >
+                  Retry
+                </button>
+              </div>
+            ) : filteredConversations.length === 0 ? (
+              <div className="py-10 text-center">
+                <p className="text-sm" style={{ color: 'var(--text-2)' }}>
+                  {searchQuery ? 'No matching conversations' : 'No conversations yet'}
+                </p>
+                <p className="mt-1 text-xs" style={{ color: 'var(--muted)' }}>
+                  {searchQuery ? 'Try another title search.' : 'Start a new conversation to begin.'}
+                </p>
+              </div>
+            ) : (
+              <div className="space-y-4">
+                {groupedConversations.map((group) => (
+                  <section key={group.key} className="space-y-2">
+                    {projects.length > 0 ? (
+                      <div className="flex items-center justify-between px-1">
+                        <h3
+                          className="text-[11px] font-semibold uppercase tracking-[0.16em]"
+                          style={{ color: 'var(--muted)' }}
+                        >
+                          {group.label}
+                        </h3>
+                        <button
+                          type="button"
+                          onClick={() => onNewConversation(group.projectId)}
+                          className="rounded-md px-2 py-1 text-[11px] font-medium"
+                          style={{ color: 'var(--ms-blue-500)' }}
+                        >
+                          New
+                        </button>
+                      </div>
+                    ) : null}
+
+                    <div className="space-y-1">
+                      {group.conversations.map((conversation) => {
+                        const isActive = currentConversationId === conversation.id;
+                        const isRenaming = renamingId === conversation.id;
+                        const showActions =
+                          hoveredId === conversation.id ||
+                          isRenaming ||
+                          pendingDeleteId === conversation.id;
+
+                        return (
+                          <div
+                            key={conversation.id}
+                            onMouseEnter={() => setHoveredId(conversation.id)}
+                            onMouseLeave={() =>
+                              setHoveredId((current) =>
+                                current === conversation.id ? null : current,
+                              )
+                            }
+                            className="rounded-xl border p-2 transition-colors"
+                            style={{
+                              borderColor: isActive
+                                ? 'color-mix(in srgb, var(--primary) 60%, var(--border))'
+                                : 'transparent',
+                              background: isActive ? 'var(--surface-2)' : 'transparent',
+                            }}
+                          >
+                            {isRenaming ? (
+                              <input
+                                ref={renameInputRef}
+                                value={renameValue}
+                                onChange={(event) => setRenameValue(event.target.value)}
+                                onBlur={() => void commitRename()}
+                                onKeyDown={(event) => {
+                                  if (event.key === 'Enter') {
+                                    event.preventDefault();
+                                    void commitRename();
+                                  }
+                                  if (event.key === 'Escape') {
+                                    event.preventDefault();
+                                    cancelRename();
+                                  }
+                                }}
+                                maxLength={255}
+                                className="w-full rounded-md border px-2 py-1.5 text-sm outline-none"
+                                style={{
+                                  background: 'var(--surface)',
+                                  borderColor: 'var(--ms-blue-500)',
+                                  color: 'var(--text)',
+                                }}
+                              />
+                            ) : (
+                              <button
+                                type="button"
+                                onClick={() => onSelectConversation(conversation.id)}
+                                className="block w-full text-left"
+                              >
+                                <div className="flex items-start gap-2">
+                                  <div className="min-w-0 flex-1">
+                                    <p
+                                      className="truncate text-sm font-medium"
+                                      style={{
+                                        color: isActive ? 'var(--text)' : 'var(--text-2)',
+                                      }}
+                                    >
+                                      {conversation.title ?? 'Untitled conversation'}
+                                    </p>
+                                    <p className="mt-1 text-xs" style={{ color: 'var(--muted)' }}>
+                                      {formatRelativeTime(conversation.updatedAt)}
+                                    </p>
+                                  </div>
+
+                                  {showActions ? (
+                                    <div className="flex items-center gap-1">
+                                      <button
+                                        type="button"
+                                        onClick={(event) => {
+                                          event.stopPropagation();
+                                          startRename(conversation);
+                                        }}
+                                        className="rounded-md p-1.5 transition-colors"
+                                        style={{ color: 'var(--text-2)' }}
+                                        aria-label={`Rename ${conversation.title ?? 'conversation'}`}
+                                      >
+                                        <svg
+                                          viewBox="0 0 24 24"
+                                          className="h-3.5 w-3.5"
+                                          fill="none"
+                                          stroke="currentColor"
+                                        >
+                                          <path
+                                            d="M4 20h4l10.5-10.5a1.4 1.4 0 0 0 0-2L16.5 5.5a1.4 1.4 0 0 0-2 0L4 16v4Z"
+                                            strokeWidth="1.8"
+                                            strokeLinejoin="round"
+                                          />
+                                        </svg>
+                                      </button>
+                                      <button
+                                        type="button"
+                                        onClick={(event) => {
+                                          event.stopPropagation();
+                                          setPendingDeleteId((current) =>
+                                            current === conversation.id ? null : conversation.id,
+                                          );
+                                          setRenamingId(null);
+                                        }}
+                                        className="rounded-md p-1.5 transition-colors"
+                                        style={{ color: 'var(--danger)' }}
+                                        aria-label={`Delete ${conversation.title ?? 'conversation'}`}
+                                      >
+                                        <svg
+                                          viewBox="0 0 24 24"
+                                          className="h-3.5 w-3.5"
+                                          fill="none"
+                                          stroke="currentColor"
+                                        >
+                                          <path
+                                            d="M4 7h16M10 11v6M14 11v6M6 7l1 12h10l1-12M9 7V4h6v3"
+                                            strokeWidth="1.8"
+                                            strokeLinecap="round"
+                                            strokeLinejoin="round"
+                                          />
+                                        </svg>
+                                      </button>
+                                    </div>
+                                  ) : null}
+                                </div>
+                              </button>
+                            )}
+
+                            {pendingDeleteId === conversation.id ? (
+                              <div
+                                className="mt-2 flex items-center justify-between rounded-lg border px-2 py-2"
+                                style={{
+                                  borderColor:
+                                    'color-mix(in srgb, var(--danger) 45%, var(--border))',
+                                  background:
+                                    'color-mix(in srgb, var(--danger) 10%, var(--surface))',
+                                }}
+                              >
+                                <p className="text-xs" style={{ color: 'var(--text-2)' }}>
+                                  Delete this conversation?
+                                </p>
+                                <div className="flex items-center gap-2">
+                                  <button
+                                    type="button"
+                                    onClick={() => setPendingDeleteId(null)}
+                                    className="rounded-md px-2 py-1 text-xs"
+                                    style={{ color: 'var(--text-2)' }}
+                                  >
+                                    Cancel
+                                  </button>
+                                  <button
+                                    type="button"
+                                    onClick={() => void deleteConversation(conversation.id)}
+                                    className="rounded-md px-2 py-1 text-xs font-medium"
+                                    style={{ background: 'var(--danger)', color: 'white' }}
+                                  >
+                                    Delete
+                                  </button>
+                                </div>
+                              </div>
+                            ) : null}
+                          </div>
+                        );
+                      })}
+                    </div>
+                  </section>
+                ))}
+              </div>
+            )}
+          </div>
+        </aside>
+      </>
+    );
+  },
+);

apps/web/src/components/layout/app-shell.tsx

@@ -1,4 +1,7 @@
+'use client';
+
 import type { ReactNode } from 'react';
+import { SidebarProvider, useSidebar } from './sidebar-context';
 import { Sidebar } from './sidebar';
 import { Topbar } from './topbar';
 
@@ -6,14 +9,24 @@ interface AppShellProps {
   children: ReactNode;
 }
 
-export function AppShell({ children }: AppShellProps): React.ReactElement {
+function AppShellFrame({ children }: AppShellProps): React.ReactElement {
+  const { collapsed, isMobile } = useSidebar();
+
   return (
-    <div className="min-h-screen">
+    <div className="app-shell" data-sidebar-hidden={!isMobile && collapsed ? 'true' : undefined}>
+      <Topbar />
       <Sidebar />
-      <div className="pl-sidebar">
-        <Topbar />
-        <main className="p-6">{children}</main>
+      <div className="app-main">
+        <main className="h-full overflow-y-auto p-6">{children}</main>
       </div>
     </div>
   );
 }
+
+export function AppShell({ children }: AppShellProps): React.ReactElement {
+  return (
+    <SidebarProvider>
+      <AppShellFrame>{children}</AppShellFrame>
+    </SidebarProvider>
+  );
+}

apps/web/src/components/layout/sidebar-context.tsx

@@ -0,0 +1,67 @@
+'use client';
+
+import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
+
+interface SidebarContextValue {
+  collapsed: boolean;
+  toggleCollapsed: () => void;
+  mobileOpen: boolean;
+  setMobileOpen: (open: boolean) => void;
+  isMobile: boolean;
+}
+
+const MOBILE_MAX_WIDTH = 767;
+const SidebarContext = createContext<SidebarContextValue | undefined>(undefined);
+
+export function SidebarProvider({ children }: { children: ReactNode }): React.JSX.Element {
+  const [collapsed, setCollapsed] = useState(false);
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const [isMobile, setIsMobile] = useState(false);
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia(`(max-width: ${String(MOBILE_MAX_WIDTH)}px)`);
+
+    const syncState = (matches: boolean): void => {
+      setIsMobile(matches);
+      if (!matches) {
+        setMobileOpen(false);
+      }
+    };
+
+    syncState(mediaQuery.matches);
+
+    const handleChange = (event: MediaQueryListEvent): void => {
+      syncState(event.matches);
+    };
+
+    mediaQuery.addEventListener('change', handleChange);
+
+    return () => {
+      mediaQuery.removeEventListener('change', handleChange);
+    };
+  }, []);
+
+  return (
+    <SidebarContext.Provider
+      value={{
+        collapsed,
+        toggleCollapsed: () => setCollapsed((value) => !value),
+        mobileOpen,
+        setMobileOpen,
+        isMobile,
+      }}
+    >
+      {children}
+    </SidebarContext.Provider>
+  );
+}
+
+export function useSidebar(): SidebarContextValue {
+  const context = useContext(SidebarContext);
+
+  if (!context) {
+    throw new Error('useSidebar must be used within SidebarProvider');
+  }
+
+  return context;
+}

apps/web/src/components/layout/sidebar.tsx

@@ -3,58 +3,178 @@
 import Link from 'next/link';
 import { usePathname } from 'next/navigation';
 import { cn } from '@/lib/cn';
+import { MosaicLogo } from '@/components/ui/mosaic-logo';
+import { useSidebar } from './sidebar-context';
 
 interface NavItem {
   label: string;
   href: string;
-  icon: string;
+  icon: React.JSX.Element;
+}
+
+function IconChat(): React.JSX.Element {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <path d="M3 4.5A2.5 2.5 0 0 1 5.5 2h5A2.5 2.5 0 0 1 13 4.5v3A2.5 2.5 0 0 1 10.5 10H8l-3.5 3v-3H5.5A2.5 2.5 0 0 1 3 7.5z" />
+    </svg>
+  );
+}
+
+function IconTasks(): React.JSX.Element {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <path d="M6 3h7M6 8h7M6 13h7" />
+      <path d="M2.5 3.5 3.5 4.5 5 2.5M2.5 8.5 3.5 9.5 5 7.5M2.5 13.5 3.5 14.5 5 12.5" />
+    </svg>
+  );
+}
+
+function IconProjects(): React.JSX.Element {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <path d="M2 4.5A1.5 1.5 0 0 1 3.5 3h3l1.5 1.5h4A1.5 1.5 0 0 1 13.5 6v5.5A1.5 1.5 0 0 1 12 13H3.5A1.5 1.5 0 0 1 2 11.5z" />
+    </svg>
+  );
+}
+
+function IconSettings(): React.JSX.Element {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <circle cx="8" cy="8" r="2.25" />
+      <path d="M8 1.5v2M8 12.5v2M1.5 8h2M12.5 8h2M3.05 3.05l1.4 1.4M11.55 11.55l1.4 1.4M3.05 12.95l1.4-1.4M11.55 4.45l1.4-1.4" />
+    </svg>
+  );
+}
+
+function IconAdmin(): React.JSX.Element {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <path d="M8 1.75 13 3.5v3.58c0 3.12-1.88 5.94-5 7.17-3.12-1.23-5-4.05-5-7.17V3.5z" />
+      <path d="M6.25 7.75 7.5 9l2.5-2.5" />
+    </svg>
+  );
 }
 
 const navItems: NavItem[] = [
-  { label: 'Chat', href: '/chat', icon: '💬' },
-  { label: 'Tasks', href: '/tasks', icon: '📋' },
-  { label: 'Projects', href: '/projects', icon: '📁' },
-  { label: 'Settings', href: '/settings', icon: '⚙️' },
-  { label: 'Admin', href: '/admin', icon: '🛡️' },
+  { label: 'Chat', href: '/chat', icon: <IconChat /> },
+  { label: 'Tasks', href: '/tasks', icon: <IconTasks /> },
+  { label: 'Projects', href: '/projects', icon: <IconProjects /> },
+  { label: 'Settings', href: '/settings', icon: <IconSettings /> },
+  { label: 'Admin', href: '/admin', icon: <IconAdmin /> },
 ];
 
 export function Sidebar(): React.ReactElement {
   const pathname = usePathname();
+  const { mobileOpen, setMobileOpen } = useSidebar();
 
   return (
-    <aside className="fixed left-0 top-0 z-30 flex h-screen w-sidebar flex-col border-r border-surface-border bg-surface-card">
-      <div className="flex h-14 items-center px-4">
-        <Link href="/" className="text-lg font-semibold text-text-primary">
-          Mosaic
-        </Link>
-      </div>
+    <>
+      <aside
+        className="app-sidebar"
+        data-mobile-open={mobileOpen ? 'true' : undefined}
+        style={{
+          width: 'var(--sidebar-w)',
+          background: 'var(--surface)',
+          borderRightColor: 'var(--border)',
+        }}
+      >
+        <div
+          className="flex h-16 items-center gap-3 border-b px-5"
+          style={{ borderColor: 'var(--border)' }}
+        >
+          <MosaicLogo size={32} />
+          <div className="flex min-w-0 flex-col">
+            <span className="text-sm font-semibold uppercase tracking-[0.12em] text-[var(--text)]">
+              Mosaic
+            </span>
+            <span className="text-xs text-[var(--muted)]">Mission Control</span>
+          </div>
+        </div>
 
-      <nav className="flex-1 space-y-1 px-2 py-2">
-        {navItems.map((item) => {
-          const isActive = pathname === item.href || pathname.startsWith(`${item.href}/`);
-          return (
-            <Link
-              key={item.href}
-              href={item.href}
-              className={cn(
-                'flex items-center gap-3 rounded-lg px-3 py-2 text-sm transition-colors',
-                isActive
-                  ? 'bg-blue-600/20 text-blue-400'
-                  : 'text-text-secondary hover:bg-surface-elevated hover:text-text-primary',
-              )}
-            >
-              <span className="text-base" aria-hidden="true">
-                {item.icon}
-              </span>
-              {item.label}
-            </Link>
-          );
-        })}
-      </nav>
+        <nav className="flex-1 px-3 py-4">
+          <div className="mb-3 px-2 text-[11px] font-medium uppercase tracking-[0.18em] text-[var(--muted)]">
+            Workspace
+          </div>
+          <div className="space-y-1.5">
+            {navItems.map((item) => {
+              const isActive = pathname === item.href || pathname.startsWith(`${item.href}/`);
 
-      <div className="border-t border-surface-border p-4">
-        <p className="text-xs text-text-muted">Mosaic Stack v0.0.4</p>
-      </div>
-    </aside>
+              return (
+                <Link
+                  key={item.href}
+                  href={item.href}
+                  onClick={() => setMobileOpen(false)}
+                  className={cn(
+                    'group flex items-center gap-3 rounded-xl px-3 py-2.5 text-sm transition-all duration-150',
+                    isActive ? 'font-medium' : 'hover:bg-white/4',
+                  )}
+                  style={
+                    isActive
+                      ? {
+                          background: 'color-mix(in srgb, var(--primary) 18%, transparent)',
+                          color: 'var(--primary)',
+                        }
+                      : { color: 'var(--text-2)' }
+                  }
+                >
+                  <span className="shrink-0" aria-hidden="true">
+                    {item.icon}
+                  </span>
+                  <span>{item.label}</span>
+                </Link>
+              );
+            })}
+          </div>
+        </nav>
+
+        <div className="border-t px-5 py-4" style={{ borderColor: 'var(--border)' }}>
+          <p className="text-xs text-[var(--muted)]">Mosaic Stack v0.0.4</p>
+        </div>
+      </aside>
+
+      {mobileOpen ? (
+        <button
+          type="button"
+          aria-label="Close sidebar"
+          className="fixed inset-0 z-40 bg-black/40 md:hidden"
+          onClick={() => setMobileOpen(false)}
+        />
+      ) : null}
+    </>
   );
 }

apps/web/src/components/layout/theme-toggle.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import { useTheme } from '@/providers/theme-provider';
+
+interface ThemeToggleProps {
+  className?: string;
+}
+
+export function ThemeToggle({ className = '' }: ThemeToggleProps): React.JSX.Element {
+  const { theme, toggleTheme } = useTheme();
+
+  return (
+    <button
+      type="button"
+      onClick={toggleTheme}
+      className={`btn-ghost rounded-md p-2 ${className}`}
+      title={`Switch to ${theme === 'dark' ? 'light' : 'dark'} mode`}
+      aria-label={`Switch to ${theme === 'dark' ? 'light' : 'dark'} mode`}
+    >
+      {theme === 'dark' ? (
+        <svg
+          className="h-5 w-5"
+          style={{ color: 'var(--warn)' }}
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth={1.5}
+        >
+          <circle cx="12" cy="12" r="4" />
+          <path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41" />
+        </svg>
+      ) : (
+        <svg
+          className="h-5 w-5"
+          style={{ color: 'var(--text-2)' }}
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth={1.5}
+        >
+          <path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z" />
+        </svg>
+      )}
+    </button>
+  );
+}

apps/web/src/components/layout/topbar.tsx

@@ -1,42 +1,87 @@
 'use client';
 
-import { usePathname, useRouter } from 'next/navigation';
-import { useSession, signOut } from '@/lib/auth-client';
+import { useRouter } from 'next/navigation';
+import { signOut, useSession } from '@/lib/auth-client';
+import { ThemeToggle } from './theme-toggle';
+import { useSidebar } from './sidebar-context';
+
+function MenuIcon(): React.JSX.Element {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <path d="M2 4h12M2 8h12M2 12h12" />
+    </svg>
+  );
+}
 
 export function Topbar(): React.ReactElement {
   const { data: session } = useSession();
   const router = useRouter();
-  const pathname = usePathname();
-
-  if (pathname.startsWith('/chat')) {
-    return <></>;
-  }
+  const { isMobile, mobileOpen, setMobileOpen, toggleCollapsed } = useSidebar();
 
   async function handleSignOut(): Promise<void> {
     await signOut();
     router.replace('/login');
   }
 
-  return (
-    <header className="sticky top-0 z-20 flex h-14 items-center justify-between border-b border-surface-border bg-surface-card/80 px-6 backdrop-blur-sm">
-      <div />
+  function handleSidebarToggle(): void {
+    if (isMobile) {
+      setMobileOpen(!mobileOpen);
+      return;
+    }
 
-      <div className="flex items-center gap-4">
+    toggleCollapsed();
+  }
+
+  return (
+    <header
+      className="app-header justify-between border-b px-4 md:px-6"
+      style={{
+        height: 'var(--topbar-h)',
+        background: 'color-mix(in srgb, var(--surface) 88%, transparent)',
+        borderBottomColor: 'var(--border)',
+      }}
+    >
+      <div className="flex items-center gap-3">
+        <button
+          type="button"
+          onClick={handleSidebarToggle}
+          className="btn-ghost rounded-lg border p-2"
+          style={{ borderColor: 'var(--border)', color: 'var(--text-2)' }}
+          aria-label="Toggle sidebar"
+        >
+          <MenuIcon />
+        </button>
+        <div className="hidden sm:block">
+          <div className="text-sm font-medium text-[var(--text)]">Workspace</div>
+          <div className="text-xs text-[var(--muted)]">Unified agent operations</div>
+        </div>
+      </div>
+
+      <div className="flex items-center gap-3">
+        <ThemeToggle />
         {session?.user ? (
           <>
-            <span className="text-sm text-text-secondary">
+            <span className="hidden text-sm text-[var(--text-2)] sm:block">
               {session.user.name ?? session.user.email}
             </span>
             <button
               type="button"
               onClick={handleSignOut}
-              className="rounded-md px-3 py-1.5 text-sm text-text-muted transition-colors hover:bg-surface-elevated hover:text-text-primary"
+              className="rounded-md px-3 py-1.5 text-sm transition-colors"
+              style={{ color: 'var(--muted)' }}
             >
               Sign out
             </button>
           </>
         ) : (
-          <span className="text-sm text-text-muted">Not signed in</span>
+          <span className="text-sm text-[var(--muted)]">Not signed in</span>
         )}
       </div>
     </header>

apps/web/src/components/settings/sso-provider-section.spec.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { SsoProviderSection } from './sso-provider-section.js';
+
+describe('SsoProviderSection', () => {
+  it('renders configured providers with callback, sync, and fallback details', () => {
+    const html = renderToStaticMarkup(
+      <SsoProviderSection
+        loading={false}
+        providers={[
+          {
+            id: 'workos',
+            name: 'WorkOS',
+            protocols: ['oidc'],
+            configured: true,
+            loginMode: 'oidc',
+            callbackPath: '/api/auth/oauth2/callback/workos',
+            teamSync: { enabled: true, claim: 'organization_id' },
+            samlFallback: { configured: false, loginUrl: null },
+            warnings: [],
+          },
+          {
+            id: 'keycloak',
+            name: 'Keycloak',
+            protocols: ['oidc', 'saml'],
+            configured: true,
+            loginMode: 'saml',
+            callbackPath: null,
+            teamSync: { enabled: true, claim: 'groups' },
+            samlFallback: {
+              configured: true,
+              loginUrl: 'https://sso.example.com/realms/mosaic/protocol/saml',
+            },
+            warnings: [],
+          },
+        ]}
+      />,
+    );
+
+    expect(html).toContain('WorkOS');
+    expect(html).toContain('/api/auth/oauth2/callback/workos');
+    expect(html).toContain('Team sync claim: organization_id');
+    expect(html).toContain('SAML fallback: https://sso.example.com/realms/mosaic/protocol/saml');
+  });
+});

apps/web/src/components/settings/sso-provider-section.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import type { SsoProviderDiscovery } from '@/lib/sso';
+
+interface SsoProviderSectionProps {
+  providers: SsoProviderDiscovery[];
+  loading: boolean;
+}
+
+export function SsoProviderSection({
+  providers,
+  loading,
+}: SsoProviderSectionProps): React.ReactElement {
+  if (loading) {
+    return <p className="text-sm text-text-muted">Loading SSO providers...</p>;
+  }
+
+  const configuredProviders = providers.filter((provider) => provider.configured);
+
+  if (providers.length === 0 || configuredProviders.length === 0) {
+    return (
+      <div className="rounded-lg border border-surface-border bg-surface-card p-4">
+        <p className="text-sm text-text-muted">
+          No SSO providers configured. Set WorkOS or Keycloak environment variables to enable SSO.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      {configuredProviders.map((provider) => (
+        <div
+          key={provider.id}
+          className="rounded-lg border border-surface-border bg-surface-card p-4"
+        >
+          <div className="flex items-center justify-between gap-4">
+            <div>
+              <h3 className="text-sm font-medium text-text-primary">{provider.name}</h3>
+              <p className="text-xs text-text-muted">
+                {provider.protocols.join(' + ').toUpperCase()}
+                {provider.loginMode ? ` • primary ${provider.loginMode.toUpperCase()}` : ''}
+              </p>
+            </div>
+            <span className="rounded-full border border-accent/30 bg-accent/10 px-2 py-1 text-xs font-medium text-accent">
+              Enabled
+            </span>
+          </div>
+
+          <div className="mt-3 space-y-2 text-xs text-text-muted">
+            {provider.callbackPath && <p>Callback: {provider.callbackPath}</p>}
+            {provider.teamSync.enabled && provider.teamSync.claim && (
+              <p>Team sync claim: {provider.teamSync.claim}</p>
+            )}
+            {provider.samlFallback.configured && provider.samlFallback.loginUrl && (
+              <p>SAML fallback: {provider.samlFallback.loginUrl}</p>
+            )}
+            {provider.warnings.map((warning) => (
+              <p key={warning} className="text-warning">
+                {warning}
+              </p>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

apps/web/src/components/ui/mosaic-logo.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import type { CSSProperties } from 'react';
+
+export interface MosaicLogoProps {
+  size?: number;
+  spinning?: boolean;
+  spinDuration?: number;
+  className?: string;
+}
+
+export function MosaicLogo({
+  size = 36,
+  spinning = false,
+  spinDuration = 20,
+  className = '',
+}: MosaicLogoProps): React.JSX.Element {
+  const scale = size / 36;
+  const squareSize = Math.round(14 * scale);
+  const circleSize = Math.round(11 * scale);
+  const borderRadius = Math.round(3 * scale);
+
+  const animationValue = spinning
+    ? `mosaicLogoSpin ${String(spinDuration)}s linear infinite`
+    : undefined;
+
+  const containerStyle: CSSProperties = {
+    width: size,
+    height: size,
+    position: 'relative',
+    flexShrink: 0,
+    animation: animationValue,
+    transformOrigin: 'center',
+  };
+
+  const baseSquareStyle: CSSProperties = {
+    position: 'absolute',
+    width: squareSize,
+    height: squareSize,
+    borderRadius,
+  };
+
+  const circleStyle: CSSProperties = {
+    position: 'absolute',
+    top: '50%',
+    left: '50%',
+    transform: 'translate(-50%, -50%)',
+    width: circleSize,
+    height: circleSize,
+    borderRadius: '50%',
+    background: 'var(--ms-pink-500)',
+  };
+
+  return (
+    <>
+      {spinning ? (
+        <style>{`
+          @keyframes mosaicLogoSpin {
+            from { transform: rotate(0deg); }
+            to { transform: rotate(360deg); }
+          }
+        `}</style>
+      ) : null}
+      <div style={containerStyle} className={className} role="img" aria-label="Mosaic logo">
+        <div style={{ ...baseSquareStyle, top: 0, left: 0, background: 'var(--ms-blue-500)' }} />
+        <div style={{ ...baseSquareStyle, top: 0, right: 0, background: 'var(--ms-purple-500)' }} />
+        <div
+          style={{
+            ...baseSquareStyle,
+            bottom: 0,
+            right: 0,
+            background: 'var(--ms-teal-500)',
+          }}
+        />
+        <div
+          style={{
+            ...baseSquareStyle,
+            bottom: 0,
+            left: 0,
+            background: 'var(--ms-amber-500)',
+          }}
+        />
+        <div style={circleStyle} />
+      </div>
+    </>
+  );
+}
+
+export default MosaicLogo;

apps/web/src/lib/sso.ts

@@ -0,0 +1,20 @@
+export type SsoProtocol = 'oidc' | 'saml';
+export type SsoLoginMode = 'oidc' | 'saml' | null;
+
+export interface SsoProviderDiscovery {
+  id: 'authentik' | 'workos' | 'keycloak';
+  name: string;
+  protocols: SsoProtocol[];
+  configured: boolean;
+  loginMode: SsoLoginMode;
+  callbackPath: string | null;
+  teamSync: {
+    enabled: boolean;
+    claim: string | null;
+  };
+  samlFallback: {
+    configured: boolean;
+    loginUrl: string | null;
+  };
+  warnings: string[];
+}

apps/web/src/providers/theme-provider.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+export type Theme = 'dark' | 'light';
+
+interface ThemeContextValue {
+  theme: Theme;
+  toggleTheme: () => void;
+  setTheme: (theme: Theme) => void;
+}
+
+const STORAGE_KEY = 'mosaic-theme';
+const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+
+function getInitialTheme(): Theme {
+  if (typeof document === 'undefined') {
+    return 'dark';
+  }
+
+  return document.documentElement.getAttribute('data-theme') === 'light' ? 'light' : 'dark';
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }): React.JSX.Element {
+  const [theme, setThemeState] = useState<Theme>(getInitialTheme);
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', theme);
+    window.localStorage.setItem(STORAGE_KEY, theme);
+  }, [theme]);
+
+  useEffect(() => {
+    const storedTheme = window.localStorage.getItem(STORAGE_KEY);
+    if (storedTheme === 'light' || storedTheme === 'dark') {
+      setThemeState(storedTheme);
+      return;
+    }
+
+    document.documentElement.setAttribute('data-theme', 'dark');
+  }, []);
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({
+      theme,
+      toggleTheme: () => setThemeState((current) => (current === 'dark' ? 'light' : 'dark')),
+      setTheme: (nextTheme) => setThemeState(nextTheme),
+    }),
+    [theme],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext);
+
+  if (!context) {
+    throw new Error('useTheme must be used within ThemeProvider');
+  }
+
+  return context;
+}

docs/guides/admin-guide.md

@@ -237,14 +237,23 @@ external clients. Authentication requires a valid BetterAuth session (cookie or
 
 ### SSO (Optional)
 
-| Variable                  | Description                    |
-| ------------------------- | ------------------------------ |
-| `AUTHENTIK_CLIENT_ID`     | Authentik OAuth2 client ID     |
-| `AUTHENTIK_CLIENT_SECRET` | Authentik OAuth2 client secret |
-| `AUTHENTIK_ISSUER`        | Authentik OIDC issuer URL      |
+| Variable                    | Description                                                                  |
+| --------------------------- | ---------------------------------------------------------------------------- |
+| `AUTHENTIK_CLIENT_ID`       | Authentik OAuth2 client ID                                                   |
+| `AUTHENTIK_CLIENT_SECRET`   | Authentik OAuth2 client secret                                               |
+| `AUTHENTIK_ISSUER`          | Authentik OIDC issuer URL                                                    |
+| `AUTHENTIK_TEAM_SYNC_CLAIM` | Optional claim used to derive team sync data (defaults to `groups`)          |
+| `WORKOS_CLIENT_ID`          | WorkOS OAuth client ID                                                       |
+| `WORKOS_CLIENT_SECRET`      | WorkOS OAuth client secret                                                   |
+| `WORKOS_ISSUER`             | WorkOS OIDC issuer URL                                                       |
+| `WORKOS_TEAM_SYNC_CLAIM`    | Optional claim used to derive team sync data (defaults to `organization_id`) |
+| `KEYCLOAK_CLIENT_ID`        | Keycloak OAuth client ID                                                     |
+| `KEYCLOAK_CLIENT_SECRET`    | Keycloak OAuth client secret                                                 |
+| `KEYCLOAK_ISSUER`           | Keycloak realm issuer URL                                                    |
+| `KEYCLOAK_TEAM_SYNC_CLAIM`  | Optional claim used to derive team sync data (defaults to `groups`)          |
+| `KEYCLOAK_SAML_LOGIN_URL`   | Optional SAML login URL used when OIDC is unavailable                        |
 
-All three Authentik variables must be set together. If only `AUTHENTIK_CLIENT_ID`
-is set, a warning is logged and SSO is disabled.
+Each OIDC provider requires its client ID, client secret, and issuer URL together. If only part of a provider configuration is set, gateway startup logs a warning and that provider is skipped. Keycloak can fall back to SAML when `KEYCLOAK_SAML_LOGIN_URL` is configured.
 
 ### Agent
 

packages/auth/src/auth.ts

@@ -1,8 +1,9 @@
 import { betterAuth } from 'better-auth';
 import { drizzleAdapter } from 'better-auth/adapters/drizzle';
 import { admin } from 'better-auth/plugins';
-import { genericOAuth, keycloak, type GenericOAuthConfig } from 'better-auth/plugins/generic-oauth';
+import { genericOAuth, type GenericOAuthConfig } from 'better-auth/plugins/generic-oauth';
 import type { Db } from '@mosaic/db';
+import { buildGenericOidcProviderConfigs } from './sso.js';
 
 export interface AuthConfig {
   db: Db;
@@ -10,118 +11,21 @@ export interface AuthConfig {
   secret?: string;
 }
 
-/** Builds the list of enabled OAuth providers from environment variables. Exported for testing. */
 export function buildOAuthProviders(): GenericOAuthConfig[] {
-  const providers: GenericOAuthConfig[] = [];
-
-  const authentikIssuer = normalizeIssuer(process.env['AUTHENTIK_ISSUER']);
-  const authentikClientId = process.env['AUTHENTIK_CLIENT_ID'];
-  const authentikClientSecret = process.env['AUTHENTIK_CLIENT_SECRET'];
-  assertOptionalProviderConfig('Authentik SSO', {
-    required: ['AUTHENTIK_ISSUER', 'AUTHENTIK_CLIENT_ID', 'AUTHENTIK_CLIENT_SECRET'],
-    values: [authentikIssuer, authentikClientId, authentikClientSecret],
-  });
-
-  if (authentikIssuer && authentikClientId && authentikClientSecret) {
-    providers.push({
-      providerId: 'authentik',
-      clientId: authentikClientId,
-      clientSecret: authentikClientSecret,
-      issuer: authentikIssuer,
-      discoveryUrl: buildDiscoveryUrl(authentikIssuer),
-      scopes: ['openid', 'email', 'profile'],
-      requireIssuerValidation: true,
-    });
-  }
-
-  const workosIssuer = normalizeIssuer(process.env['WORKOS_ISSUER']);
-  const workosClientId = process.env['WORKOS_CLIENT_ID'];
-  const workosClientSecret = process.env['WORKOS_CLIENT_SECRET'];
-  assertOptionalProviderConfig('WorkOS SSO', {
-    required: ['WORKOS_ISSUER', 'WORKOS_CLIENT_ID', 'WORKOS_CLIENT_SECRET'],
-    values: [workosIssuer, workosClientId, workosClientSecret],
-  });
-
-  if (workosIssuer && workosClientId && workosClientSecret) {
-    providers.push({
-      providerId: 'workos',
-      clientId: workosClientId,
-      clientSecret: workosClientSecret,
-      issuer: workosIssuer,
-      discoveryUrl: buildDiscoveryUrl(workosIssuer),
-      scopes: ['openid', 'email', 'profile'],
-      requireIssuerValidation: true,
-    });
-  }
-
-  const keycloakIssuer = resolveKeycloakIssuer();
-  const keycloakClientId = process.env['KEYCLOAK_CLIENT_ID'];
-  const keycloakClientSecret = process.env['KEYCLOAK_CLIENT_SECRET'];
-  assertOptionalProviderConfig('Keycloak SSO', {
-    required: ['KEYCLOAK_CLIENT_ID', 'KEYCLOAK_CLIENT_SECRET', 'KEYCLOAK_ISSUER'],
-    values: [keycloakClientId, keycloakClientSecret, keycloakIssuer],
-  });
-
-  if (keycloakIssuer && keycloakClientId && keycloakClientSecret) {
-    providers.push(
-      keycloak({
-        clientId: keycloakClientId,
-        clientSecret: keycloakClientSecret,
-        issuer: keycloakIssuer,
-        scopes: ['openid', 'email', 'profile'],
-      }),
-    );
-  }
-
-  return providers;
-}
-
-function resolveKeycloakIssuer(): string | undefined {
-  const issuer = normalizeIssuer(process.env['KEYCLOAK_ISSUER']);
-  if (issuer) {
-    return issuer;
-  }
-
-  const baseUrl = normalizeIssuer(process.env['KEYCLOAK_URL']);
-  const realm = process.env['KEYCLOAK_REALM']?.trim();
-
-  if (!baseUrl || !realm) {
-    return undefined;
-  }
-
-  return `${baseUrl}/realms/${realm}`;
-}
-
-function buildDiscoveryUrl(issuer: string): string {
-  return `${issuer}/.well-known/openid-configuration`;
-}
-
-function normalizeIssuer(value: string | undefined): string | undefined {
-  return value?.trim().replace(/\/+$/, '') || undefined;
-}
-
-function assertOptionalProviderConfig(
-  providerName: string,
-  config: { required: string[]; values: Array<string | undefined> },
-): void {
-  const hasAnyValue = config.values.some((value) => Boolean(value?.trim()));
-  const hasAllValues = config.values.every((value) => Boolean(value?.trim()));
-
-  if (!hasAnyValue || hasAllValues) {
-    return;
-  }
-
-  throw new Error(
-    `@mosaic/auth: ${providerName} requires ${config.required.join(', ')}. Set them in your config or via the listed environment variables.`,
-  );
+  return buildGenericOidcProviderConfigs() as GenericOAuthConfig[];
 }
 
 export function createAuth(config: AuthConfig) {
   const { db, baseURL, secret } = config;
-
-  const oauthProviders = buildOAuthProviders();
+  const oidcConfigs = buildOAuthProviders();
   const plugins =
-    oauthProviders.length > 0 ? [genericOAuth({ config: oauthProviders })] : undefined;
+    oidcConfigs.length > 0
+      ? [
+          genericOAuth({
+            config: oidcConfigs,
+          }),
+        ]
+      : undefined;
 
   const corsOrigin = process.env['GATEWAY_CORS_ORIGIN'] ?? 'http://localhost:3000';
   const trustedOrigins = corsOrigin.split(',').map((o) => o.trim());

packages/auth/src/index.ts

@@ -1 +1,12 @@
 export { createAuth, type Auth, type AuthConfig } from './auth.js';
+export {
+  buildGenericOidcProviderConfigs,
+  buildSsoDiscovery,
+  listSsoStartupWarnings,
+  type GenericOidcProviderConfig,
+  type SsoLoginMode,
+  type SsoProtocol,
+  type SsoProviderDiscovery,
+  type SsoTeamSyncConfig,
+  type SupportedSsoProviderId,
+} from './sso.js';

packages/auth/src/sso.spec.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildGenericOidcProviderConfigs,
+  buildSsoDiscovery,
+  listSsoStartupWarnings,
+} from './sso.js';
+
+describe('SSO provider config helpers', () => {
+  it('builds OIDC configs for Authentik, WorkOS, and Keycloak when fully configured', () => {
+    const configs = buildGenericOidcProviderConfigs({
+      AUTHENTIK_CLIENT_ID: 'authentik-client',
+      AUTHENTIK_CLIENT_SECRET: 'authentik-secret',
+      AUTHENTIK_ISSUER: 'https://authentik.example.com',
+      WORKOS_CLIENT_ID: 'workos-client',
+      WORKOS_CLIENT_SECRET: 'workos-secret',
+      WORKOS_ISSUER: 'https://auth.workos.com/sso/client_123',
+      KEYCLOAK_CLIENT_ID: 'keycloak-client',
+      KEYCLOAK_CLIENT_SECRET: 'keycloak-secret',
+      KEYCLOAK_ISSUER: 'https://sso.example.com/realms/mosaic',
+    });
+
+    expect(configs.map((config) => config.providerId)).toEqual(['authentik', 'workos', 'keycloak']);
+    expect(configs.find((config) => config.providerId === 'workos')).toMatchObject({
+      discoveryUrl: 'https://auth.workos.com/sso/client_123/.well-known/openid-configuration',
+      pkce: true,
+      requireIssuerValidation: true,
+    });
+    expect(configs.find((config) => config.providerId === 'keycloak')).toMatchObject({
+      discoveryUrl: 'https://sso.example.com/realms/mosaic/.well-known/openid-configuration',
+      pkce: true,
+    });
+  });
+
+  it('exposes Keycloak SAML fallback when OIDC is not configured', () => {
+    const providers = buildSsoDiscovery({
+      KEYCLOAK_SAML_LOGIN_URL: 'https://sso.example.com/realms/mosaic/protocol/saml',
+    });
+
+    expect(providers.find((provider) => provider.id === 'keycloak')).toMatchObject({
+      configured: true,
+      loginMode: 'saml',
+      samlFallback: {
+        configured: true,
+        loginUrl: 'https://sso.example.com/realms/mosaic/protocol/saml',
+      },
+    });
+  });
+
+  it('reports partial provider configuration as startup warnings', () => {
+    const warnings = listSsoStartupWarnings({
+      WORKOS_CLIENT_ID: 'workos-client',
+      KEYCLOAK_CLIENT_ID: 'keycloak-client',
+    });
+
+    expect(warnings).toContain(
+      'workos OIDC is partially configured. Missing: WORKOS_CLIENT_SECRET, WORKOS_ISSUER',
+    );
+    expect(warnings).toContain(
+      'keycloak OIDC is partially configured. Missing: KEYCLOAK_CLIENT_SECRET, KEYCLOAK_ISSUER',
+    );
+  });
+});

packages/auth/src/sso.ts

@@ -0,0 +1,241 @@
+export type SupportedSsoProviderId = 'authentik' | 'workos' | 'keycloak';
+export type SsoProtocol = 'oidc' | 'saml';
+export type SsoLoginMode = 'oidc' | 'saml' | null;
+
+type EnvMap = Record<string, string | undefined>;
+
+export interface GenericOidcProviderConfig {
+  providerId: SupportedSsoProviderId;
+  clientId: string;
+  clientSecret: string;
+  discoveryUrl?: string;
+  issuer?: string;
+  authorizationUrl?: string;
+  tokenUrl?: string;
+  userInfoUrl?: string;
+  scopes: string[];
+  pkce?: boolean;
+  requireIssuerValidation?: boolean;
+}
+
+export interface SsoTeamSyncConfig {
+  enabled: boolean;
+  claim: string | null;
+}
+
+export interface SsoProviderDiscovery {
+  id: SupportedSsoProviderId;
+  name: string;
+  protocols: SsoProtocol[];
+  configured: boolean;
+  loginMode: SsoLoginMode;
+  callbackPath: string | null;
+  teamSync: SsoTeamSyncConfig;
+  samlFallback: {
+    configured: boolean;
+    loginUrl: string | null;
+  };
+  warnings: string[];
+}
+
+const DEFAULT_SCOPES = ['openid', 'email', 'profile'];
+
+function readEnv(env: EnvMap, key: string): string | undefined {
+  const value = env[key]?.trim();
+  return value ? value : undefined;
+}
+
+function toDiscoveryUrl(issuer: string): string {
+  return `${issuer.replace(/\/$/, '')}/.well-known/openid-configuration`;
+}
+
+function getTeamSyncClaim(env: EnvMap, envKey: string, fallbackClaim?: string): SsoTeamSyncConfig {
+  const claim = readEnv(env, envKey) ?? fallbackClaim ?? null;
+  return {
+    enabled: claim !== null,
+    claim,
+  };
+}
+
+function buildAuthentikConfig(env: EnvMap): GenericOidcProviderConfig | null {
+  const issuer = readEnv(env, 'AUTHENTIK_ISSUER');
+  const clientId = readEnv(env, 'AUTHENTIK_CLIENT_ID');
+  const clientSecret = readEnv(env, 'AUTHENTIK_CLIENT_SECRET');
+
+  const fields = [issuer, clientId, clientSecret];
+  const presentCount = fields.filter(Boolean).length;
+  if (presentCount > 0 && presentCount < fields.length) {
+    throw new Error(
+      '@mosaic/auth: Authentik SSO requires AUTHENTIK_ISSUER, AUTHENTIK_CLIENT_ID, AUTHENTIK_CLIENT_SECRET.',
+    );
+  }
+  if (!issuer || !clientId || !clientSecret) {
+    return null;
+  }
+
+  const baseIssuer = issuer.replace(/\/$/, '');
+
+  return {
+    providerId: 'authentik',
+    issuer: baseIssuer,
+    clientId,
+    clientSecret,
+    discoveryUrl: toDiscoveryUrl(baseIssuer),
+    authorizationUrl: `${baseIssuer}/application/o/authorize/`,
+    tokenUrl: `${baseIssuer}/application/o/token/`,
+    userInfoUrl: `${baseIssuer}/application/o/userinfo/`,
+    scopes: DEFAULT_SCOPES,
+  };
+}
+
+function buildWorkosConfig(env: EnvMap): GenericOidcProviderConfig | null {
+  const issuer = readEnv(env, 'WORKOS_ISSUER');
+  const clientId = readEnv(env, 'WORKOS_CLIENT_ID');
+  const clientSecret = readEnv(env, 'WORKOS_CLIENT_SECRET');
+
+  const fields = [issuer, clientId, clientSecret];
+  const presentCount = fields.filter(Boolean).length;
+  if (presentCount > 0 && presentCount < fields.length) {
+    throw new Error(
+      '@mosaic/auth: WorkOS SSO requires WORKOS_ISSUER, WORKOS_CLIENT_ID, WORKOS_CLIENT_SECRET.',
+    );
+  }
+  if (!issuer || !clientId || !clientSecret) {
+    return null;
+  }
+
+  const normalizedIssuer = issuer.replace(/\/$/, '');
+
+  return {
+    providerId: 'workos',
+    issuer: normalizedIssuer,
+    clientId,
+    clientSecret,
+    discoveryUrl: toDiscoveryUrl(normalizedIssuer),
+    scopes: DEFAULT_SCOPES,
+    pkce: true,
+    requireIssuerValidation: true,
+  };
+}
+
+function buildKeycloakConfig(env: EnvMap): GenericOidcProviderConfig | null {
+  const explicitIssuer = readEnv(env, 'KEYCLOAK_ISSUER');
+  const keycloakUrl = readEnv(env, 'KEYCLOAK_URL');
+  const keycloakRealm = readEnv(env, 'KEYCLOAK_REALM');
+  const clientId = readEnv(env, 'KEYCLOAK_CLIENT_ID');
+  const clientSecret = readEnv(env, 'KEYCLOAK_CLIENT_SECRET');
+
+  // Derive issuer from KEYCLOAK_URL + KEYCLOAK_REALM if KEYCLOAK_ISSUER not set
+  const issuer =
+    explicitIssuer ??
+    (keycloakUrl && keycloakRealm
+      ? `${keycloakUrl.replace(/\/$/, '')}/realms/${keycloakRealm}`
+      : undefined);
+
+  const anySet = !!(issuer || clientId || clientSecret);
+  if (anySet && (!issuer || !clientId || !clientSecret)) {
+    throw new Error(
+      '@mosaic/auth: Keycloak SSO requires KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET, KEYCLOAK_ISSUER.',
+    );
+  }
+  if (!issuer || !clientId || !clientSecret) {
+    return null;
+  }
+
+  const normalizedIssuer = issuer.replace(/\/$/, '');
+
+  return {
+    providerId: 'keycloak',
+    issuer: normalizedIssuer,
+    clientId,
+    clientSecret,
+    discoveryUrl: toDiscoveryUrl(normalizedIssuer),
+    scopes: DEFAULT_SCOPES,
+    pkce: true,
+    requireIssuerValidation: true,
+  };
+}
+
+function collectWarnings(env: EnvMap, provider: SupportedSsoProviderId): string[] {
+  const prefix = provider.toUpperCase();
+  const oidcFields = [
+    `${prefix}_CLIENT_ID`,
+    `${prefix}_CLIENT_SECRET`,
+    `${prefix}_ISSUER`,
+  ] as const;
+  const presentOidcFields = oidcFields.filter((field) => readEnv(env, field));
+  const warnings: string[] = [];
+
+  if (presentOidcFields.length > 0 && presentOidcFields.length < oidcFields.length) {
+    const missing = oidcFields.filter((field) => !readEnv(env, field));
+    warnings.push(`${provider} OIDC is partially configured. Missing: ${missing.join(', ')}`);
+  }
+
+  return warnings;
+}
+
+export function buildGenericOidcProviderConfigs(
+  env: EnvMap = process.env,
+): GenericOidcProviderConfig[] {
+  return [buildAuthentikConfig(env), buildWorkosConfig(env), buildKeycloakConfig(env)].filter(
+    (config): config is GenericOidcProviderConfig => config !== null,
+  );
+}
+
+export function listSsoStartupWarnings(env: EnvMap = process.env): string[] {
+  return ['authentik', 'workos', 'keycloak'].flatMap((provider) =>
+    collectWarnings(env, provider as SupportedSsoProviderId),
+  );
+}
+
+export function buildSsoDiscovery(env: EnvMap = process.env): SsoProviderDiscovery[] {
+  const oidcConfigs = new Map(
+    buildGenericOidcProviderConfigs(env).map((config) => [config.providerId, config]),
+  );
+  const keycloakSamlLoginUrl = readEnv(env, 'KEYCLOAK_SAML_LOGIN_URL') ?? null;
+
+  return [
+    {
+      id: 'authentik',
+      name: 'Authentik',
+      protocols: ['oidc'],
+      configured: oidcConfigs.has('authentik'),
+      loginMode: oidcConfigs.has('authentik') ? 'oidc' : null,
+      callbackPath: oidcConfigs.has('authentik') ? '/api/auth/oauth2/callback/authentik' : null,
+      teamSync: getTeamSyncClaim(env, 'AUTHENTIK_TEAM_SYNC_CLAIM', 'groups'),
+      samlFallback: {
+        configured: false,
+        loginUrl: null,
+      },
+      warnings: collectWarnings(env, 'authentik'),
+    },
+    {
+      id: 'workos',
+      name: 'WorkOS',
+      protocols: ['oidc'],
+      configured: oidcConfigs.has('workos'),
+      loginMode: oidcConfigs.has('workos') ? 'oidc' : null,
+      callbackPath: oidcConfigs.has('workos') ? '/api/auth/oauth2/callback/workos' : null,
+      teamSync: getTeamSyncClaim(env, 'WORKOS_TEAM_SYNC_CLAIM', 'organization_id'),
+      samlFallback: {
+        configured: false,
+        loginUrl: null,
+      },
+      warnings: collectWarnings(env, 'workos'),
+    },
+    {
+      id: 'keycloak',
+      name: 'Keycloak',
+      protocols: ['oidc', 'saml'],
+      configured: oidcConfigs.has('keycloak') || keycloakSamlLoginUrl !== null,
+      loginMode: oidcConfigs.has('keycloak') ? 'oidc' : keycloakSamlLoginUrl ? 'saml' : null,
+      callbackPath: oidcConfigs.has('keycloak') ? '/api/auth/oauth2/callback/keycloak' : null,
+      teamSync: getTeamSyncClaim(env, 'KEYCLOAK_TEAM_SYNC_CLAIM', 'groups'),
+      samlFallback: {
+        configured: keycloakSamlLoginUrl !== null,
+        loginUrl: keycloakSamlLoginUrl,
+      },
+      warnings: collectWarnings(env, 'keycloak'),
+    },
+  ];
+}